Process payroll payments

Process Payroll API enables businesses to submit payroll details, including company information, payroll references, employee payment amounts, beneficiary bank details, and salary breakdowns.

The API returns an acknowledgement indicating whether the payroll submission is being processed, along with any available bank references and status information. If the payroll is still being processed, use the Payroll Enquiry API to retrieve the latest status.

Important: A response with the status Processing indicates that the payroll is being processed and does not confirm that all salary payments have been completed successfully. Use the Payroll Enquiry API to retrieve the updated status after 30 minutes, as indicated in the response.

Important information

The user must provide the valid credentials in the header
Valid Signature, Access code as "Authorization: Bearer"
The request should be in the specified format
The request should include all the mandatory details with appropriate request tags
Ensure that the SequenceNum is unique for each transaction. Payments with same sequence number appear as duplicate transactions and affects their processing and enquiry operations.
Beneficiary information should not contain special characters such as #, &, *, %, =, ^, _, \, {, |, }, ~, ", ;, @, [, ], `
Submitted payroll updated status will be reflected after 30 minutes
To know the status of payroll, a payroll enquiry request has to be sent

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

Endpoint details

Endpoint URL	Method	Authentication requirements
`/api/v2/payroll/payment`	POST	`CompanyId` `SVReferenceID` `DateTimeStamp` `Device` `Authorization: Bearer`

Sample request

Process Payroll Payment Request

curl --location 'https://sandboxapi.onesingleview.com/api/v2/payroll/payment' \
--header 'CompanyId: MYCOMPANY'
--header 'SVReferenceID: SV150619940615'
--header 'DateTimeStamp	:2025-01-02T10:20:39'
--header 'Device: Web'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNMlZ4WGpFZmR6WFNWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUV1TXl6S1Aybi94Y0lwR2V5STNNMkdPL1pqakd4ZG0yclJKUkdhRXlaWGNpWnZnOHArMWIyOGtOQTVkZ0VKajVVSEdiTmtNPSIsImlhdCI6MTczNTgwMTQ3NywiZXhwIjoxNzM1ODA1MDc3fQ.Bh7LFkvxNFrLe9dmH5rURWjGpES-u4z2EGeyrNM7z6E'
--header 'Content-Type: application/json' \
--data '{
  "Message": {
    "OSVPayrollPaymentRequest": {
      "TransactionType": "PP",
      "BankCode": "ALRAJHI",
      "CompanyCode": "125001291",
      "PayrollReferenceNumber": "98198322",
      "CorporateCommercialRegistrationNumber": "CCRN1237",
      "MolCorporateID": "MOLID51922",
      "FileSeqNo": "0501",
      "Date": "240103",
      "Currency": "SAR",
      "OSVPayrollOrderingDetails": {
        "OrderingInstitution": "RJHISARI",
        "OrderingCustomerAccountNumber": "",
        "OrderingCustomerName": "National Company",
        "OrderingCustomerAdd1": "Suite 3, Business Bay Building",
        "OrderingCustomerAdd2": "Umm Thumamah Road, Riyadh",
        "OrderingCustomerAdd3": "P.O. Box 28, Riyadh 11411"
      },
      "TransactionData": [
        {
          "SequenceNum": "981983200113",
          "Amount": "5000",
          "PaymentDetails": "WPS Payroll",
          "BeneficiaryDetails": {
            "BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
            "BeneficiaryAccount": "SA0580000204608015129224",
            "BeneficiaryName": "Abdul Rahman",
            "BeneficiaryAdd1": "Flat 28, Al Ameen Towers, Al Akhi Rd",
            "BeneficiaryAdd2": "Jeddah",
            "BeneficiaryAdd3": "Branch Off, P.O Box 55585, Jeddah"
          },
          "SalaryDetails": {
            "Id": "2843806024",
            "EmployeeID": "123457",
            "BasicSalary": "4000",
            "HousingAllowance": "1000",
            "OtherEarnings": "1000",
            "Deductions": "1000"
          }
        },
        {
          "SequenceNum": "981983200114",
          "Amount": "5000",
          "PaymentDetails": "WPS Payroll",
          "BeneficiaryDetails": {
            "BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
            "BeneficiaryAccount": "SA0580000204608015129115",
            "BeneficiaryName": "Ali",
            "BeneficiaryAdd1": "Flat 16, KSA Heights, Al Rabie Road",
            "BeneficiaryAdd2": "Riyadh",
            "BeneficiaryAdd3": "Head Off P.O Box 66674, Riyadh"
          },
          "SalaryDetails": {
            "Id": "2843806023",
            "EmployeeID": "123456",
            "BasicSalary": "4000",
            "HousingAllowance": "1000",
            "OtherEarnings": "1000",
            "Deductions": "1000"
          }
        }
      ],
      "TransactionComment": "WPS Payroll",
      "TotalTransactionCount": "02",
      "TotalTransactionAmount": "10000.00"
    }
  },
"Signature": "UMEH9M8tXknuRnnkrzRjDHaxFRLyZJ+wDNAl408+nTWyfTKaVcBkLLPhX5DKjTX18HK/oEJ8rmSeoswQuKzk9F2WIcXwZI9C+h7GA5d6r0FEu9hAYG+tDjFSyPDPHunMbILe1rgIlenbHra24Xt2IxAqj5115FEhJyabV0saIveNfK4sPOWtB+HeEAhwP6pwHETZoO4Z9kiMgdIbBbyD43IpRyxVQzogtlNKrkRaW/k16eIGzeS8Nh5g0txEoa3aocQTiVqzEtkwBXMKKUnoMZMCIOsPh7XNDN9nmsad0CNHr5wwJZoc9gC2e/d7fWuUu8xqe8AaSWXm3xTIfostIg=="
}'

Request parameters

JSON Tag	Requirement	Description	Data type
OSVPayrollPaymentRequest	Mandatory	Root node containing all the payroll payments transaction information	Object
TransactionType	Mandatory	Type of transaction to be mentioned as `PP`	String
BankCode	Mandatory	Unique bank identification code (SingleView Identifier) `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Alinma Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank `GIB` - Gulf International Bank `ALBI` - Bank Al Bilad	String
CompanyCode	Mandatory	Unique company identification code	String
PayrollReferenceNumber	Mandatory	Unique 16 digit reference number generated by the customer for each payroll processing	String
CorporateCommercialRegistrationNumber	Conditional Mandatory for NCB	Unique corporate commercial registration identification details Max size of input: 15 Characters	String
MolCorporateID	Conditional Mandatory for NCB, SAB, and ANB	Unique MoI assigned corporate identification details Max size of input: 15 Characters	String
FileSeqNo	Conditional Mandatory for NCB	4 digit file sequence number of the WPS payroll request in MMSS format where: MM = Month of payroll SS = Sequence of payroll for the month	String
Date	Mandatory	Date of the transaction in YYMMDD format	String
Currency	Mandatory	3 digit code representing the currency of the transaction	String
OSVPayrollOrderingDetails	Mandatory	Tag carrying information about the company or account initiating the payroll payments	Object
OrderingInstitution	Mandatory	Institution identifier (BIC) of the ordering institution	String
OrderingCustomerAccountNumber	Mandatory	Account number of the ordering customer	String
OrderingCustomerName	Mandatory	Name of the ordering customer as per bank records	String
OrderingCustomerAdd1	Mandatory	Ordering Customer’s Address Line 1 Input size: 3- 35 Characters	String
OrderingCustomerAdd2	Mandatory	Ordering Customer’s Address Line 2 (`city` to be mentioned) Input size: 3- 35 Characters	String
OrderingCustomerAdd3	Mandatory	Ordering Customer’s Address Line 3 Input size: 3- 35 Characters	String
TransactionData	Mandatory	Tag carrying information on the individual employee payment instructions. Each entry represents a payroll transaction.	Object
SequenceNum	Mandatory	Unique sequence number identifying the employee payment transaction	String
Amount	Mandatory	Payment amount for the employee	String
PaymentDetails	Mandatory	Description of the payment, such as `WPS Payroll`	String
BeneficiaryDetails	Mandatory	Tag carrying identification details of the employee receiving the salary payment	Object
BeneficiaryAccountWithInstitutionBIC	Mandatory	BIC or institution identifier associated with the beneficiary account	String
BeneficiaryAccount	Mandatory	Beneficiary's bank account or IBAN	String
BeneficiaryName	Mandatory	Name of the employee receiving the payment	String
BeneficiaryAdd1	Mandatory	First line of the beneficiary address Input size: 3-35 Characters	String
BeneficiaryAdd2	Mandatory	Second line of the beneficiary address (`city` to be mentioned) Input size: 3-35 Characters	String
BeneficiaryAdd3	Mandatory	Third line of the beneficiary address Input size: 3-35 Characters	String
SalaryDetails	Mandatory	Tag carrying information of employee identifiers and the components used to describe the salary payment	Object
Id	Mandatory	Employee or payroll identifier required by the applicable bank	String
EmployeeID	Conditional Mandatory for GIB	Employee identification code assigned by the company	String
BasicSalary	Mandatory	Employee's basic salary amount	String
HousingAllowance	Mandatory	Housing allowance amount	String
OtherEarnings	Mandatory	Additional earnings included in the salary breakdown	String
Deductions	Mandatory	Applicable deductions	String
TransactionComment	Mandatory	Comment description of the overall payroll request	String
TotalTransactionCount	Mandatory	Total number of employee payment transactions included in the request	String
TotalTransactionAmount	Mandatory	Aggregate amount submitted for processing	String
Signature	Mandatory	Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature)	String

Sample response

Process Payroll Payments Successful Response

{
	"OSVPayrollPaymentResponse": {
		"BankCode": "ALRAJHI",
		"CompanyCode": "125001291",
		"PayrollReferenceNumber": "98198322",
		"StatusCode": "Processing",
		"ErrorCode": "",
		"StatusDetail": "Payroll payments are being processed. Perform payroll enquiry after 30 mins to get updated status.",
		"TimeStamp": "2026-07-09T10:20:39",
		"OSVPayrollDetails": {
			"MessageDescription": "Payroll Message Acknowledgement",
			"Date": "240103",
			"FileSeqNo": "0501",
			"BankReferenceNumber": ""
		}
	}
}

Response parameters

JSON Tag	Description	Data type
OSVPayrollPaymentResponse	Tag carrying information on the payroll response	Object
BankCode	Code identifying the bank processing the payroll `ALRAJHI` - Al Rajhi Bank `SABB` - Saudi Awaal Bank `BSF` - Banque Saudi Fransi `ALINMA` - Alinma Bank `ANB` - Arab National Bank `NCB` - Saudi National Bank `RIYADH` - Riyadh Bank `GIB` - Gulf International Bank `ALBI` - Bank Al Bilad	String
CompanyCode	Company identifier associated with the request	String
PayrollReferenceNumber	Payroll reference returned by the bank or service	String
StatusCode	Code denoting the payroll response status	String
ErrorCode	Error code returned when applicable. An empty value indicates that no error code is provided in this example.	String
StatusDetail	Descriptive message explaining the status or the next recommended action	String
TimeStamp	Date and time associated with the response	String
OSVPayrollDetails	Tag carrying additional payroll acknowledgement and bank-specific reference information	Object
MessageDescription	Description of the bank or service response	String
Date	Payroll date as specified in the request	String
FileSeqNo	Payroll file sequence number returned in the response only by `NCB`	String
BankReferenceNumber	Bank-generated reference number provided only by `ANB`	String

Important notes

Use the transaction type PP for payroll requests.
Supply the payroll date in the required YYMMDD format.
Populate the ordering customer account number with the appropriate company account information.
Ensure the transaction count and total amount match the submitted employee payment instructions.
Use valid employee, beneficiary, and salary information.
Generate the signature according to the applicable signing specification.
Treat Processing as an interim status rather than confirmation of completed salary payments.
Use Payroll Enquiry to retrieve updated statuses where supported.
Follow bank-specific requirements for mandatory fields, references, and response handling.
If a payroll needs to be cancelled, use the Cancel Payroll API and submit the request at least 24 hours before the value date, subject to the applicable bank's rules.
For further details on tracking payroll status, refer to the Payroll Enquiry documentation. For cancellation requirements, refer to the Cancel Payroll documentation.

Status Information

File-level status

StatusCode	StatusDetail
Processing	Payroll payments are being processed. Perform payroll enquiry after some time to get updated status.
Failed	Failure description
Response_Timeout	Timeout! Unable to get response from the bank. Please 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

Process payroll payments

Domain details