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. `CompanyId` 2. `SVReferenceID` 3. `DateTimeStamp` 4. `Device` 5. `Authorization: Bearer` (Token)

Sample request

curl --location 'https://sandboxapi.onesingleview.com/api/v1/payroll/transfer' \
--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": {
  "OSVPayrollMessageRequest": {
    "TransactionType": "PAYROLL",
    "OSVPayrollTransactionRequest": [
      {
        "BankCode": "ALRAJHI",
        "PayrollReferenceNumber": "98198322",
        "CorporateCommercialRegistrationNumber": "CCRN1237",
        "MolCorporateID": "MOLID51922",
        "FileSeqNo": "0501",
        "CompanyCode": "125001291",
        "OrderingCustomerNameAddress": {
          "OrderingCustomerName": "National Company",
          "OrderingCustomerAdd1": "Suite 3, Business Bay Building",
          "OrderingCustomerAdd2": "Umm Thumamah Road, Riyadh",
          "OrderingCustomerAdd3": "P.O. Box 28, Riyadh 11411"
        },
        "OrderingInstitution": "RJHISARI",
        "OrderingCustomerAccountNumber": "",
        "OrderingCustomerIBAN": "SA8080000204608015129123",
        "TransactionData": [
          {
            "SequenceNum": "981983200113",
            "DateCurrencyAmount": {
              "Date": "240103",
              "Currency": "SAR",
              "Amount": "5000"
            },
            "BeneficiaryBankCode": "ALRAJHI",
            "BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
            "BeneficiaryAccountNumberNameAddress": {
              "BeneficiaryAccount": "SA0580000204608015129115",
              "BeneficiaryName": "Ali",
              "BeneficiaryADD1": "Flat 16, KSA Heights, Al Rabie Road",
              "BeneficiaryADD2": "Riyadh",
              "BeneficiaryADD3": "Head Off P.O Box 66674, Riyadh"
            },
            "PaymentDetails": "WPS Payroll",
            "SalaryDetails": {
              "Id": "2843806023",
              "BasicSalary": "4000",
              "HousingAllowance": "1000",
              "OtherEarnings": "1000",
              "Deductions": "1000"
            }
          },
          {
            "SequenceNum": "981983200113",
            "DateCurrencyAmount": {
              "Date": "240103",
              "Currency": "SAR",
              "Amount": "5000"
            },
            "BeneficiaryBankCode": "ALRAJHI",
            "BeneficiaryAccountWithInstitutionBIC": "RJHISARI",
            "BeneficiaryAccountNumberNameAddress": {
              "BeneficiaryAccount": "SA0580000204608015129115",
              "BeneficiaryName": "Ali",
              "BeneficiaryADD1": "Flat 16, KSA Heights, Al Rabie Road",
              "BeneficiaryADD2": "Riyadh",
              "BeneficiaryADD3": "Head Off P.O Box 66674, Riyadh"
            },
            "PaymentDetails": "WPS Payroll",
            "SalaryDetails": {
              "Id": "2843806023",
              "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 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
BankCode Mandatory	Unique bank identification code (SingleView Identifier) *Ex: `ALRAJHI, SABB, BSF, ANB, SNB, ALINMA, GIB, RIYADH, ALBI, BJAZ`*	Alphabetical
PayrollReferenceNumber Mandatory	It is a unique reference number generated by the customer for each payroll processing Max size of input: 16 Characters	Numeric
CorporateCommercialRegistrationNumber Conditional for SNB	Unique Corporate commercial registration identification details Max size of input: 15 Characters	String
MolCorporateID Conditional for SNB & ANB	Unique MoI assigned corporate identification details Max size of input: 15 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
CompanyCode Mandatory	Unique company identification code	String
OrderingCustomerNameAddress Mandatory	Tag carrying information on the ordering customer name and address	Object
OrderingCustomerName Mandatory	Name of the ordering customer as per bank records	String
OrderingCustomerAdd1 Mandatory	Ordering Customer’s Address Line 1 Input size: Min - 3 Characters Max - 35 Characters	String
OrderingCustomerAdd2 Mandatory	Ordering Customer’s Address Line 2 (`city` to be mentioned) Input size: Min - 3 Characters Max - 35 Characters	String
OrderingCustomerAdd3 Mandatory	Ordering Customer’s Address Line 3 Input size: Min - 3 Characters Max - 35 Characters	String
OrderingInstitution Mandatory	Ordering Institution Ex: SABBSARI, RJHISARI Maximum length: 8 or 11 characters	Alphanumeric
OrderingCustomerAccountNumber Conditional	Account number of the ordering customer Mandatory if OrderingCustomerIBAN is not provided	Alphanumeric
OrderingCustomerIBAN Conditional	International Bank Account Number of the ordering customer	Alphanumeric
TransactionData Mandatory	Tag carrying information on payroll transactions	Object
SequenceNum Mandatory	Unique sequence number for each transaction in the payroll	Numeric
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
BeneficiaryBankCode Mandatory	Unique bank identification code for beneficiary account (SingleView Identifier) *Ex: `ALRAJHI, SABB, BSF, ANB, SNB, ALINMA, GIB, RIYADH, ALBI, BJAZ`*	Alphanumeric
BeneficiaryAccountWithInstitutionBIC Mandatory	Beneficiary BIC Code Ex: SABBSARI, RJHISARI Maximum length: 8 or 11 characters	Alphanumeric
BeneficiaryAccountNumberNameAddress Mandatory	Element root containing details of Beneficiary	Object
BeneficiaryAccount Mandatory	Beneficiary bank account number Input size: Min - 11 Characters Max - 24 Characters	Alphanumeric
BeneficiaryName Mandatory	Name of the beneficiary	String
BeneficiaryAdd1 Mandatory	Beneficiary Address Line 1 Input size: Min - 3 Characters Max - 35 Characters	String
BeneficiaryAdd2 Mandatory	Beneficiary Line 2 (`city` to be mentioned) Input size: Min - 3 Characters Max - 35 Characters	String
BeneficiaryAdd3 Mandatory	Beneficiary Address Line 3 Input size: Min - 3 Characters Max - 35 Characters	String
PaymentDetails Mandatory	Payroll transaction description Max size of input: 35 Characters	String
SalaryDetails Mandatory	Tag carrying salary information	Object
Id Mandatory	Iqama or National ID number of the beneficiary	Alphanumeric
BasicSalary Mandatory	Amount for basic salary	Numeric
HousingAllowance Mandatory	Salary breakdown indicating the amount allocated to the beneficiary under housing allowances	Numeric
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
TransactionComment Mandatory	Comment regarding the payroll transaction	String
TotalTransactionCount Mandatory	Total count of transactions included in the payroll	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`*	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

Submitted payroll status will be reflected after 30 minutes

To know the status of payroll, a payroll enquiry request has to be sent

Process a Payroll

Overview

📘
Mandatory information

Process Payroll Payouts

Endpoint details

Sample request

Sample response

✅ Successful response

❗️
Important Info

Overview

📘Mandatory information

Process Payroll Payouts

Endpoint details

Sample request

Sample response

✅ Successful response

❗️Important Info

📘
Mandatory information

❗️
Important Info