Overview

SingleView Payroll Payouts Enquiry service connects Corporate users via a secure channel and enables them to enquire about the status of their payroll transactions quickly and easily. The key feature of the service allows the user to get immediate acknowledgment about the most recent status of their payments.

❗️
Riyadh Bank doesn't support Payroll Enquiry services

🌐
Domain details
Environment Domain Rate/Limit
Sandbox sandboxapi.onesingleview.com 10 Calls per Minute
Production/LIVE To be provided upon onboarding Based on contract

Environment	Domain	Rate/Limit
Sandbox	sandboxapi.onesingleview.com	10 Calls per Minute
Production/LIVE	To be provided upon onboarding	Based on contract

Get Payroll Payouts Enquiry

Endpoint details

Endpoint URL	Method	Authentication requirements
`/api/v1/payroll/enquiry`	POST	`CompanyId` `SVReferenceID` `DateTimeStamp` `Device` `Authorization: Bearer` (Token)

Sample request

curl --location 'https://sandboxapi.onesingleview.com/api/v1/payroll/enquiry' \
--header 'SVReferenceID: SV150619940615' \
--header 'CompanyId: MYCOMPANY' \
--header 'Device: web' \
--header 'DateTimeStamp: 2023-08-10T10:20:39' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNMlZ4WGpFZmR6WFNWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUV1TXl6S1Aybi94Y0lwR2V5STNNMkdPL1pqakd4ZG0yclJKU0VLY3hhSFVoWVBjM3B3ZkI1MjhJcDJ2ank1QWpyV1dFMWNBPSIsImlhdCI6MTczNjE2Mjk1NCwiZXhwIjoxNzM2MTY2NTU0fQ.uy8sphQ4sa-p0_iUj2Rq4ULO5lDitpY_isr4yKP-NFM' \
--header 'Content-Type: application/json' \
--data '{
"Message": {
  "OSVPayrollMessageRequest": {
    "OSVPayrollStatusRequest": [
      {
        "PayrollTransactions": [
          {
            "BankReferenceNumber": "",
            "MessageDescription": "Payroll Message Acknowledgement",
            "OrderingCustomerAccountNumber": "0108061198800019",
            "ValueDate": "20250102",
            "FileSeqNo": "",
            "PayrollReferenceNumber": "6787891596792846",
            "CompanyCode": "125001234"
          }
        ],
        "BankCode": "ALRAJHI"
      }
    ]
  }
},
"Signature": "daMcbZ7RpZu5uQO+4JQKw0DPni2ggvBNx8TT/1IwB+whN8HxIjdkwcvL96ybblvtgnsj7Yc6wH8yUWTn9/jJ84lnqMSdqGWrl3um7WxPput79rgWvD0zXvZyB6rEqIRoiPlCB1TdkSOfyQNcd91JCTv/X7XDXXdNfOoSIydE932k/nonatdzWRBOnMf9zg/FSvWq7TwtnBGH3EtGSE6M3D3sNON1rmjeTu6q6OGjcehxYv/yQqUbjEzRWpRDZSjzATR+Gdxc3kmbRhXX36+Gb2UDVio6YjG/m6OmJrx9NJjuHPA6LfL93btmKom8BI2gYSoSTgdwKOiJl95IQaCyFg=="
}'

Request Description

JSON Tag	Description	Data type
OSVPayrollMessageRequest Mandatory	Root node containing all the payroll payment transaction messages	Tag
OSVPayrollStatusRequest Mandatory	This tag contains enquiry for multiple banks requests	Object
BankCode Mandatory	Unique bank identification code Ex:`ALRAJHI, SABB, BSF, ANB, NCB, ALINMA, GIB, RIYADH, ALBI, BJAZ`	String
PayrollTransactions Mandatory	This tag contains details of various payroll transactions for enquiry	Object
BankReferenceNumber Conditional	Unique bank reference number of the payroll transaction Required only for Arab National Bank (ANB)	String
MessageDescription Mandatory	Message details concerned to the specific payroll Max size of input: 16 Characters	String
OrderingCustomerAccountNumber Mandatory	Unique bank account details of the ordering customer mentioned in the payroll request Max size of input: 24 Characters	Alphanumeric
ValueDate Mandatory	Date of processing of the payroll request YYYYMMDD	Date
FileSeqNo Conditional for NCB	Unique file sequence number of the WPS payroll request 4 Digit Number in the format of MMSS MM - Current month SS - Sequence of payroll for the month	Numeric
PayrollReferenceNumber Mandatory	It is a unique reference number generated by the customer for each payroll processing) Max size of input: 16 Characters	Numeric
CompanyCode Mandatory	Sender company code/Identifier provided by the bank	Alphanumeric
Signature Mandatory	Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature)	String

Sample responses

✅ Response under acknowledgement stage

{
  "OSVPayrollEnquiryResponse": [
    {
      "BankCode": "ALRAJHI",
      "PayrollReferenceNumber": "6787891596792846",
      "MessageType": "BULKRES",
      "OSVPayrollStatusResponse": [
        {
          "PayrollTransactionResponse": {
            "CompanyCode": "125001234",
            "StatusCode": "SUCCESS",
            "StatusDetail": "Payroll file received successfully kindly check the payroll enquiry after 30 min"
          }
        }
      ]
    }
  ]
}

Response description

JSON Tag	Description	Data type
OSVPayrollEnquiryResponse	Root node	Object
BankCode	Unique bank identification code of the bank Ex:`ALRAJHI, SABB, BSF, ANB, NCB, ALINMA, GIB, RIYADH, ALBI, BJAZ`	String
PayrollReferenceNumber	Payroll Reference Number	String
MessageType	Type of transaction message	String
OSVPayrollStatusResponse	Element root containing response of every payroll transactions	Array
PayrollTransactionResponse	Tag carrying information on payroll transaction response	Object
CompanyCode	Sender company Code/Identifier	String
StatusCode	Status code of the response	String
StatusDetail	Details about the status of the request	String

Status Information

Acknowledgement Stage Process Codes & Details

StatusCode	StatusDetail
SUCCESS	Payroll file received successfully kindly check the payroll enquiry after 30 min
FAILED	Bank response
PENDING	Bank response

✅ Response post-successful acknowledgement stage

{
  "OSVPayrollEnquiryResponse": [
    {
      "BankCode": "ALRAJHI",
      "PayrollReferenceNumber": "6787891596792846",
      "MessageType": "BULKRES",
      "OSVPayrollStatusResponse": [
        {
          "PayrollTransactionResponse": {
            "CompanyCode": "125001234",
            "SequenceNum": "9154422971141234",
            "StatusCode": "FAILED",
            "StatusDetail": "002M : Current account blocked"
          }
        },
        {
          "PayrollTransactionResponse": {
            "CompanyCode": "125001234",
            "SequenceNum": "9543354065045678",
            "StatusCode": "SUCCESS",
            "StatusDetail": "Processed Successfully"
          }
        }
      ]
    }
  ]
}

Response description

JSON Tag	Description	Data type
OSVPayrollEnquiryResponse	Root node	Object
BankCode	Unique bank identification code of the bank Ex:`ALRAJHI, SABB, BSF, ANB, NCB, ALINMA, GIB, RIYADH, ALBI, BJAZ`	String
PayrollReferenceNumber	Payroll Reference Number	String
MessageType	Type of transaction message	String
OSVPayrollStatusResponse	Element root containing response of every payroll transactions	Array
PayrollTransactionResponse	Tag carrying information on payroll transaction response	Object
CompanyCode	Sender company Code/Identifier	String
SequenceNum	Value of “SequenceNum” tag in the request message. Maximum Length :16 digits numeric	String
StatusCode	Status code of the transaction in payroll	String
StatusDetail	Details about the status of the transaction in payroll	String

Status Information

Processing Stage Process Codes & Details

StatusCode	StatusDetail
SUCCESS	Bank response
FAILED	Bank response
PENDING	Bank response