Process a Payroll
Make payroll payments using SingleView API services
Overview
Payroll payments can be processed through SingleView APIs and require the following details to be enclosed in the payment processing request:
Mandatory 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
🌐Domain details
- Sandbox API - sandboxapi.onesingleview.com
- Production/LIVE API - To be provided upon onboarding
Process Payroll Payouts
Endpoint details
| Endpoint URL | Method | Authentication requirements |
|---|---|---|
/api/v1/payroll/transfer | POST | 1/. clientid (Optional)2. clientsecret (Optional)3. Authorization: Bearer (Token)4. SVReferenceID5. CompanyId6. Device (Ex: Mobile or Web)7. DateTimeStamp |
Sample request
curl --location 'http://sandboxapi.onesingleview.com/api/v1/payroll/transfer' \
--header 'CompanyId: MYCOMPANY'
--header 'SVReferenceID: Enter-SV-Reference-Id'
--header 'DateTimeStamp :2025-01-02T10:20:39'
--header 'Device: Web'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiTDNyMmpxV29JS2I4MTNodDBNMlZ4WGpFZmR6WFNWaTFad3B5QnlkOVpHelZXR2ZwUmFQNUV1TXl6S1Aybi94Y0lwR2V5STNNMkdPL1pqakd4ZG0yclJKUkdhRXlaWGNpWnZnOHArMWIyOGtOQTVkZ0VKajVVSEdiTmtNPSIsImlhdCI6MTczNTgwMTQ3NywiZXhwIjoxNzM1ODA1MDc3fQ.Bh7LFkvxNFrLe9dmH5rURWjGpES-u4z2EGeyrNM7z6E'
--header 'Content-Type: application/json' \
--data '{
"Message": {
"OSVPayrollMessageRequest": {
"TransactionType": "PAYROLL",
"OSVPayrollTransactionRequest": [
{
"TotalTransactionCount": "1",
"MolCorporateID": "MOLID51922",
"CorporateCommercialRegistrationNumber": "CCRN1237",
"TransactionComment": "WPS Payroll",
"FileSeqNo": "0501",
"BankCode": "ALRAJHI",
"PayrollReferenceNumber": "98198322",
"TransactionData": [
{
"BeneficiaryAccountNumberNameAddress": {
"BeneficiaryADD1": "Head Off P.O Box 66674, Riyadh",
"BeneficiaryName": "Ali",
"BeneficiaryAccount": "SA0580000204608015129115"
},
"OrderingCustomerNameAddress": {
"OrderingCustomerAdd1": "P.O. Box 28, Riyadh 11411",
"OrderingCustomerName": "Al Rajhi Ac Two"
},
"BeneficiaryBankCode": "ALRAJHI",
"BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
"DateCurrencyAmount": {
"Currency": "SAR",
"Amount": "5000",
"Date": "240103"
},
"OrderingCustomerAccountNumber": "SA8080000204608015129123",
"PaymentDetails": "WPS Payroll",
"SalaryDetails": {
"OtherEarnings": "1000",
"Deductions": "1000",
"Id": "2843806023",
"HousingAllowance": "1000",
"BasicSalary": "4000"
},
"OrderingInstitution": "RJHISARI",
"CompanyCode": "125001291",
"SequenceNum": "981983200113"
},
{
"BeneficiaryAccountNumberNameAddress": {
"BeneficiaryADD1": "Head Off P.O Box 66674, Riyadh",
"BeneficiaryName": "Ali",
"BeneficiaryAccount": "SA1380000204608015691668"
},
"OrderingCustomerNameAddress": {
"OrderingCustomerAdd1": "P.O. Box 28, Riyadh 11411",
"OrderingCustomerName": "Al Rajhi Ac Two"
},
"BeneficiaryBankCode": "ALRAJHI",
"BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
"DateCurrencyAmount": {
"Currency": "SAR",
"Amount": "5000",
"Date": "240103"
},
"OrderingCustomerAccountNumber": "SA8080000204608015129123",
"PaymentDetails": "WPS Payroll",
"SalaryDetails": {
"OtherEarnings": "1000",
"Deductions": "1000",
"Id": "2843806023",
"HousingAllowance": "1000",
"BasicSalary": "4000"
},
"OrderingInstitution": "RJHISARI",
"CompanyCode": "125001291",
"SequenceNum": "981983200123"
}
],
"TotalTransactionAmount": "10000"
}
]
}
}
},
"Signature": "UMEH9M8tXknuRnnkrzRjDHaxFRLyZJ+wDNAl408+nTWyfTKaVcBkLLPhX5DKjTX18HK/oEJ8rmSeoswQuKzk9F2WIcXwZI9C+h7GA5d6r0FEu9hAYG+tDjFSyPDPHunMbILe1rgIlenbHra24Xt2IxAqj5115FEhJyabV0saIveNfK4sPOWtB+HeEAhwP6pwHETZoO4Z9kiMgdIbBbyD43IpRyxVQzogtlNKrkRaW/k16eIGzeS8Nh5g0txEoa3aocQTiVqzEtkwBXMKKUnoMZMCIOsPh7XNDN9nmsad0CNHr5wwJZoc9gC2e/d7fWuUu8xqe8AaSWXm3xTIfostIg=="
}'
Request Description
| JSON Tag | Description | Data type |
|---|---|---|
| OSVPayrollPaymentMessageRequest Mandatory | Root node containing all the payroll payment transaction messages | Object |
| TransactionType Mandatory | Type of transaction to be mentioned as PAYROLL | String |
| OSVPayrollTransactionRequest Mandatory | This tag contains multiple banks requests | Object |
| TotalTransactionCount Mandatory | Representation of number of transactions in the payroll | Numeric |
| MolCorporateID Conditional for SNB | Unique MoI assigned corporate identification details Max size of input: 18 Characters | String |
| CorporateCommercialRegistrationNumber Conditional for SNB | Unique Corporate commercial registration identification details Max size of input: 15 Characters | Numeric |
| TransactionComment Mandatory | Transaction description through comment Max size of input: 50 Characters | String |
| FileSeqNo Conditional for SNB | 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 |
| BankCode Mandatory | Unique bank identification code (SingleView Identifier) Ex: ALRAJHI, SABB, BSF, ANB, SNB, ALINMA, GIB, RIYADH, ALBI, BJAZ, ICICI, HDFC | Alphabetical |
| PayrollReferenceNumber Mandatory | It is a unique reference number generated by the customer for each payroll processing Max size of input: 16 Characters | Numeric |
| TransactionData Mandatory | Tag carrying information on payroll transaction | Object |
| BeneficiaryAccountNumberNameAddress Mandatory | Element root containing details of Beneficiary | Object |
| BeneficiaryADD1 Mandatory | Beneficiary Address Line 1 Input size: Min - 3 Characters Max - 35 Characters | String |
| BeneficiaryName Mandatory | Beneficiary Name Input size: Min - 3 Characters Max - 35 Characters | String |
| BeneficiaryAccount Mandatory | Beneficiary account number Input size: Min - 11 Characters Max - 24 Characters | Alphanumeric |
| OrderingCustomerNameAddress Mandatory | Element root containing details of Ordering customer | Object |
| OrderingCustomerName Mandatory | Ordering Customer’s Name Input size: Min - 3 Characters Max - 35 Characters | String |
| OrderingCustomerAdd1 Mandatory | Ordering Customer’s Address Line 1 Input size: Min - 3 Characters Max - 35 Characters | String |
| BeneficiaryBankCode Mandatory | Beneficiary bank identification code Maximum length: 8 or 11 characters | Alphanumeric |
| BeneficiaryAccountWithInstitutionBIC Mandatory | Beneficiary BIC Code Ex: SABBSARI, RJHISARI Maximum length: 8 or 11 characters | String |
| DateCurrencyAmount Mandatory | Tag carrying information on transaction currency, date and amount | Object |
| Currency Mandatory | Unique code representing the currency of the transaction Max size of input: 3 Characters | Alphabetical |
| Amount Mandatory | Amount of the transaction | Numeric |
| Date Mandatory | Date of the transaction in YYMMDD format | Date |
| OrderingCustomerAccountNumber Mandatory | Ordering Customer’s account number (Any one is mandate Account Number or IBAN Number) Input size: Min - 11 Characters Max - 24 Characters | Alphanumeric |
| PaymentDetails Mandatory | Payroll transaction description Max size of input: 35 Characters | String |
| SalaryDetails Mandatory | Tag carrying salary information | Object |
| OtherEarnings Mandatory | Additional amount to be credited apart from basic and housing allowance | Numeric |
| Deductions Mandatory | Total amount that indicates the deductions for the concerned beneficiary | Numeric |
| Id Mandatory | Iqama or National ID number of the beneficiary | String |
| HousingAllowance Mandatory | Salary breakdown indicating the amount allocated to the beneficiary under housing allowances | Numeric |
| BasicSalary Mandatory | Basic salary amount | Numeric |
| OrderingInstitution Mandatory | Ordering Institution Ex: SABBSARI, RJHISARI Maximum length: 8 or 11 characters | Alphanumeric |
| CompanyCode Mandatory | Unique identification code of the company | Alphanumeric |
| SequenceNum Mandatory | Unique reference number for each transaction Length of input: 16 characters | Numeric |
| TotalTransactionAmount Mandatory | Total amount of transactions included under a specific debit account | Numeric |
| Signature Mandatory | Encrypted string generated using a Private Key/CA-Signed Certificate with SHA-256 and RSA (JCE Signature) | String |
Sample response
✅ Successful response
{
"OSVPayrollMessageResponse": {
"OSVPayrollTransactionResponse": [
{
"BankCode": "ALRAJHI",
"PayrollReferenceNumber": "98198322",
"TransactionData": [
{
"CompanyCode": "125001291",
"MessageType": "PRACK",
"MessageDescription": "Payroll Message Acknowledgement",
"TransactionDate": "2025-01-02T10:20:39",
"FileSeqNo": "",
"TransferType": "MT100-Payroll",
"BankReferenceNumber": "",
"StatusCode": "OK",
"StatusDetail": "Payroll File received successfully kindly do the payroll enquiry after 30 min"
}
]
}
]
}
}
Response description
| JSON Tag | Description | Data type |
|---|---|---|
| OSVPayrollMessageResponse | Root node | Object |
| OSVPayrollTransactionResponse | Element root containing response of every bank transactions | Object/Array |
| BankCode | Unique bank identification code Ex: ALRAJHI, SABB, BSF, ANB, SNB, ALINMA, GIB, RIYADH, ALBI, BJAZ, ICICI, HDFC | Alphanumeric |
| PayrollReferenceNumber | Payroll Reference Number | Numeric |
| TransactionData | This tag contains the status of the payments | Object/Array |
| CompanyCode | Sender company Code/Identifier | String |
| MessageType | Type of message | String |
| MessageDescription | Details about the response | String |
| TransactionDate | Date of the transaction | String |
| FileSeqNo | Unique file sequence number of the payroll | Numeric |
| TransferType | Type of transfer MT-100 Payroll | String |
| BankReferenceNumber | Unique bank reference number of the payroll transaction | Alphanumeric |
| StatusCode | Code representing status of the request | String |
| StatusDetail | Details about the status of the request | String |
Important Info
- Payroll submitted should have the value date as at least the next day
- Submitted payroll status will be reflected after 30 minutes
- To know the status of payroll, a payroll enquiry request has to be sent
Updated about 12 hours ago