Perform payroll enquiry

Payroll Enquiry API enables businesses to track payroll processing after submitting a payroll request through the Process Payroll API. It provides the overall payroll status and, where supported, the status of individual employee payment transactions, including completion, failure, and partial completion details.

The API also helps identify processing errors, retrieve bank references, and determine whether further enquiries are required before the final payroll outcome is established.

Important information

If the initial response returns StatusCode: Processing or StatusCode: Request_Timeout, perform the first enquiry 30 minutes after submission, subject to the applicable bank's processing requirements
Use the Payroll Enquiry API to:
- Retrieve the latest status of a submitted payroll request
- Track payroll requests that return Processing or Request_Timeout
- Check the status of individual employee payments
- Identify failed or partially completed payroll transactions
- Retrieve transaction-level error codes, status messages, and bank references, where supported
- Verify payroll processing progress before considering the request complete
If the Process Payroll API returns StatusCode: Failed, do not perform a Payroll Enquiry unless the applicable bank's documentation specifies otherwise
Riyadh Bank doesn't support payroll enquiry services

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

Environment	Domain	Rate/Limit
Sandbox	sandboxapi.onesingleview.com	3 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/v2/payroll/enquiry`	POST	`CompanyId` `SVReferenceID` `DateTimeStamp` `Device` `Authorization: Bearer`

Sample request

Payroll Payouts Enquiry Request

curl --location 'https://sandboxapi.onesingleview.com/api/v2/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": {
    "OSVPayrollEnquiryRequest": {
      "TransactionType": "PPE",
      "BankCode": "ALRAJHI",
      "CompanyCode": "125001291",
      "PayrollReferenceNumber": "98198322",
      "OrderingCustomerAccountNumber": "SA8080000204608015129123",
      "MessageDescription": "Payroll Message Description",
      "Date": "YYMMDD",
      "FileSeqNo": "",
      "BankReferenceNumber": ""
    }
  },
"Signature": "daMcbZ7RpZu5uQO+4JQKw0DPni2ggvBNx8TT/1IwB+whN8HxIjdkwcvL96ybblvtgnsj7Yc6wH8yUWTn9/jJ84lnqMSdqGWrl3um7WxPput79rgWvD0zXvZyB6rEqIRoiPlCB1TdkSOfyQNcd91JCTv/X7XDXXdNfOoSIydE932k/nonatdzWRBOnMf9zg/FSvWq7TwtnBGH3EtGSE6M3D3sNON1rmjeTu6q6OGjcehxYv/yQqUbjEzRWpRDZSjzATR+Gdxc3kmbRhXX36+Gb2UDVio6YjG/m6OmJrx9NJjuHPA6LfL93btmKom8BI2gYSoSTgdwKOiJl95IQaCyFg=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
OSVPayrollEnquiryRequest	Mandatory	Tag carrying information on the payroll enquiry request	Object
TransactionType	Mandatory	Type of transaction to be specified as `PPE`	String
BankCode	Mandatory	Unique bank identification code `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Alinma Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `GIB` - Gulf International Bank `ALBI` - Bank Al Bilad	String
CompanyCode	Mandatory	Company identifier registered with the service or bank	String
PayrollReferenceNumber	Mandatory	Reference number identifying the payroll request	String
OrderingCustomerAccountNumber	Conditional Mandatory for SNB	Unique bank account details of the ordering customer mentioned in the payroll request	String
MessageDescription	Mandatory	Message details concerned to the specific payroll	String
Date	Mandatory	Date of processing of the payroll request in YYMMDD format	String
FileSeqNo	Conditional Mandatory for NCB	Payroll file sequence identifier	String
BankReferenceNumber	Conditional Mandatory for ANB	Bank-generated reference used to identify the payroll request	String
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",
            "CompanyCode": "125001291",
            "PayrollReferenceNumber": "98198322",
            "StatusCode": "Processing",
            "ErrorCode": "",
            "StatusDetail": "Payroll payments are being processed. Perform payroll enquiry after some time to get updated status.",
            "TimeStamp": "2026-07-09T10:20:39"
        }
    }

Response parameters

JSON Tag	Description	Data type
OSVPayrollEnquiryResponse	Tag carrying information on the requested payroll enquiry	Object
BankCode	Unique bank identification code of the bank `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Alinma Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `GIB` - Gulf International Bank `ALBI` - Bank Al Bilad	String
CompanyCode	Company identifier associated with the payroll	String
PayrollReferenceNumber	Payroll reference returned by the bank or service	String
StatusCode	Overall processing status of the payroll request	String
ErrorCode	Error code associated with the overall request, where applicable	String
StatusDetail	Descriptive message explaining the overall payroll status or error	String
TimeStamp	Date and time associated with the response	String
TransactionData	Array containing individual employee payment statuses and related details	Object
ReferenceNumber	Identifier used to match the response to an individual employee payment. Depending on the bank, it contains the corresponding `SequenceNum` or `Id` value.	String
Status	Current status of the individual employee payment	String
ErrorCode	Error code returned for the individual transaction, where applicable	String
StatusMessage	Descriptive message explaining the transaction status or failure reason	String
BankReference	Bank-generated reference for the individual transaction obtained based on bank agreement	String

Status Information

File-level status

StatusCode	StatusDetail
Processing	Payroll payments are being processed. Perform payroll enquiry after some time to get updated status.
Completed	File processing completed successfully.
Partially_Completed	Payroll processing is partial success. Check individual transactions for more details.
Failed	Payroll payment failed. Transactions are rejected.
Response_Timeout	Unable to get response from the bank. Please perform payment enquiry in few mins or contact SingleView support.

Transaction-level status

Status	StatusMessage
Processing	Payment is being processed.
Completed	Payment completed successfully.
Failed	Transaction failure description
Response_Timeout	Unable to get response from the bank. Please perform payment enquiry in few mins or contact SingleView support.

GENERAL INFORMATION

Getting started

GETTING STARTED

Authentication

ERP API Services

CONSENT MANAGEMENT

AUTHENTICATION

Data APIs

Raw Data APIs

Payment APIs

DATA USE CASE APIS

SADAD

Plug-and-Play Integrations

Virtual Accounts

RESOURCES

SME Onboarding (Draft)

API Archives

Domain details