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 - https://sandbox.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 2. clientsecret 3. Authorization: Bearer (Token) 4. SVReferenceID 5. CompanyId 6. Signature |
Sample request
curl --location 'https://sandboxapi.onesingleview.com/api/payroll/transfer' \
--header 'clientsecret: Enter-Client-Secret' \
--header 'clientid: Enter-Client-Id' \
--header 'SVReferenceID: Enter-SV-Reference-Id' \
--header 'Device: Device-type' \
--header 'DateTimeStamp: YYYY-MM-DDTHH:MM:SS' \
--header 'CompanyId: Enter-Company-Id' \
--header 'BaseCurrency: SAR' \
--header 'Authorization: Bearer <Enter-Token>' \
--header 'Content-Type: application/json' \
--data '{
"Message": {
"OSVPayrollMessageRequest": {
"TransactionType": "PAYROLL",
"OSVPayrollTransactionRequest": [
{
"BankCode": "Enter_Bank_Code",
"PayrollReferenceNumber": "Enter_Payroll_Reference_Number",
"TransactionData": [
{
"CompanyCode": "Enter_Company_Code",
"SequenceNum": "Enter_Sequence_Number",
"DateCurrencyAmount": {
"Date": "YYMMDD",
"Currency": "SAR",
"Amount": "Enter_Amount"
},
"OrderingCustomerNameAddress": {
"OrderingCustomerName": "Enter_Name",
"OrderingCustomerAdd1": "Enter_Address"
},
"OrderingInstitution": "Enter_Institution_Code",
"OrderingCustomerAccountNumber": "Enter_Account_Number",
"BeneficiaryAccountWithInstitutionBIC": "Enter_BIC",
"BeneficiaryAccountNumberNameAddress": {
"BeneficiaryAccount": "Enter_Beneficiary_Account_Number",
"BeneficiaryName": "Enter_Beneficiary_Name",
"BeneficiaryADD1": "Enter_Beneficiary_Address"
},
"PaymentDetails": "Purpose_codes",
"SalaryDetails": {
"Id": "Enter_ID_Number",
"BasicSalary": "Enter_Basic_Salary_Amount",
"HousingAllowance": "Enter_Housing_Allowance_Amount",
"OtherEarnings": "Enter_Other_Earnings_Amount",
"Deductions": "Enter_Deductions_Amount"
}
}
],
"TransactionComment": "Enter_Comment",
"TotalTransactionCount": "X",
"TotalTransactionAmount": "Enter_Total_Transactions_Amount"
},
{
"BankCode": "Enter_Bank_Code",
"PayrollReferenceNumber": "Enter_Payroll_Reference_Number",
"TransactionData": [
{
"CompanyCode": "Enter_Company_Code",
"SequenceNum": "Enter_Sequence_Number",
"DateCurrencyAmount": {
"Date": "YYMMDD",
"Currency": "SAR",
"Amount": "Enter_Amount"
},
"OrderingCustomerNameAddress": {
"OrderingCustomerName": "Enter_Name",
"OrderingCustomerAdd1": "Enter_Address"
},
"OrderingInstitution": "Enter_Institution_Code",
"OrderingCustomerAccountNumber": "Enter_Account_Number",
"BeneficiaryAccountWithInstitutionBIC": "Enter_BIC",
"BeneficiaryAccountNumberNameAddress": {
"BeneficiaryAccount": "Enter_Beneficiary_Account_Number",
"BeneficiaryName": "Enter_Beneficiary_Name",
"BeneficiaryADD1": "Enter_Beneficiary_Address"
},
"PaymentDetails": "Purpose_codes",
"SalaryDetails": {
"Id": "Enter_ID_Number",
"BasicSalary": "Enter_Basic_Salary_Amount",
"HousingAllowance": "Enter_Housing_Allowance_Amount",
"OtherEarnings": "Enter_Other_Earnings_Amount",
"Deductions": "Enter_Deductions_Amount"
}
}
],
"TransactionComment": "Enter_Comment",
"TotalTransactionCount": "X",
"TotalTransactionAmount": "Enter_Total_Transactions_Amount"
}
]
}
},
"Signature": "Enter_Signature"
}'
Request Description
| JSON Tag | Description | Data type |
|---|---|---|
| OSVPayrollPaymentMessageRequest Mandatory | Root node containing all the payroll payment transaction messages | Object |
| TransactionType Mandatory | Always it should be MT100 | Alphanumeric |
| OSVPayrollTransactionRequest Mandatory | This tag contains multiple banks requests | Object |
| BankCode Mandatory | Bank Code (Identifier) Ex: “ALRAJHI”, “SABB” | Alphanumeric |
| PayrollReferenceNumber Mandatory | It is a unique reference number generated by the customer for each payroll processing) Maximum length : 16 numeric characters | Numeric |
| TransactionData Mandatory | Payroll transaction Description Maximum length : 35 characters | String |
| CompanyCode Mandatory | Sender company code/Identifier provided by the bank | String |
| SequenceNum Mandatory | Unique number representing each transaction | Numeric |
| DateCurrencyAmount Mandatory | Element root containing details of Date, Currency and Amount | Object |
| Date Mandatory | Value date (Transactions will be performed on this date. Date must be expressed as YYMMDD <year, month, day>) Maximum length : 6 numeric characters | Numeric |
| Currency Mandatory | This is the currency code used in the transaction. Maximum length : 3 digit currency code | Alphabet |
| Amount Mandatory | This is the amount used in the transaction. Maximum length : 15 digit amount | Numeric |
| OrderingCustomerNameAddress Mandatory | Element root containing details of Ordering customer | Object/Array |
| OrderingCustomerName Mandatory | Ordering Customer’s Name | String |
| OrderingCustomerAdd1 Mandatory | Ordering Customer’s Address | String |
| OrderingInstitution Mandatory | Ordering Institution Ex: SABBSARI, RJHISARI | Alphanumeric |
| OrderingCustomerAccountNumber Mandatory | Ordering Customer’s account number (Any one is mandate Account Number or IBAN Number) | Alphanumeric |
| BeneficiaryAccountWithInstitutionBIC Mandatory | Beneficiary BIC Code Ex: SABBSARI, RJHISARI Maximum length: 8 or 11 characters | String |
| BeneficiaryAccountNumberNameAddress Mandatory | Element root containing details of Beneficiary | Object/Array |
| BeneficiaryAccount Mandatory | Beneficiary Customer’s Name | String |
| BeneficiaryName Mandatory | Beneficiary Name Maximum 35 characters | Alphanumeric |
| BeneficiaryADD1 Mandatory | Beneficiary Address | String |
| PaymentDetails Mandatory | Information regarding payment to the specific beneficiary | String |
| SalaryDetails Mandatory | This carries the salary details of the concerned beneficiary | String |
| Id Mandatory | Iqama or National ID number of the beneficiary | String |
| BasicSalary Mandatory | Basic salary amount | Numerical |
| 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 | Comments regarding the transactions included under the specific debit account | String |
| TotalTransactionCount Mandatory | Total number of transactions included under a specific debit account | Numeric |
| TotalTransactionAmount Mandatory | Total amount of transactions included under a specific debit account | Numeric |
| Signature Mandatory | Encrypted string obtained by processing request body with Private Key/Certificate through SHA-256 with RSA Algorithm (Crypto : JCE Sign) | String |
Sample response
✅ Successful response
{
"OSVPayrollMessageResponse": {
"OSVPayrollTransactionResponse": [{
"BankCode": "Bank_Code",
"PayrollReferenceNumber": "Payroll_Reference_Number",
"TransactionData": [{
"CompanyCode": "Company_Code",
"MessageType": "Message",
"MessageDescription": "Payroll_Message_Acknowledgement",
"TransactionDate": "YYYYMMDD",
"TransferType": "MT100-Payroll",
"StatusCode": "Status_Code",
"StatusDetail": "Status_Detail"
}]
},
{
"BankCode": "Bank_Code",
"PayrollReferenceNumber": "Payroll_Reference_Number",
"TransactionData": [{
"CompanyCode": "Company_Code",
"MessageType": "Message",
"MessageDescription": "Payroll_Message_Acknowledgement",
"TransactionDate": "YYYYMMDD",
"TransferType": "MT100-Payroll",
"StatusCode": "Status_Code",
"StatusDetail": "Status_Detail"
}]
}]
}
}
Response description
| JSON Tag | Description | Data type |
|---|---|---|
| OSVPayrollMessageResponse | Root node | Object |
| OSVPayrollTransactionResponse | Element root containing response of every bank transactions | Object/Array |
| BankCode | Name of the bank. Ex: “ALRAJHI”, “SABB” | Alphanumeric |
| PayrollReferenceNumber | Payroll Reference Number | Numeric |
| TransactionData | This tag contains the status of the payments | Object |
| CompanyCode | Sender company Code/Identifier | String |
| MessageType | Type of message | String |
| MessageDescription | Details about the response | String |
| TransactionDate | Value of “SequenceNum” tag in the request message. Maximum Length :16 digits numeric | String |
| TransferType | Type of transfer (MT-100 Payroll) | String |
| StatusCode | Code representing status of the request | String |
| StatusDetail | Details about the status of the request | String |
Updated 24 days ago