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

Try in API Reference ➜

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	Tag
TransactionType Mandatory	Always it should be `MT100`	String
OSVPayrollTransactionRequest Mandatory	This tag contains multiple banks requests	Object
BankCode Mandatory	Bank Code (Identifier) Ex: “ALRAJHI”, “SABB”	String
PayrollReferenceNumber Mandatory	It is a unique reference number generated by the customer for each payroll processing) Maximum length : 16 numeric characters	String
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	String
DateCurrencyAmount Mandatory	Element root containing details of Date, Currency and Amount	String
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	String
Currency Mandatory	This is the currency code used in the transaction. Maximum length : 3 digit currency code	String
Amount Mandatory	This is the amount used in the transaction. Maximum length : 15 digit amount	Numerical
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	String
OrderingCustomerAccountNumber Mandatory	Ordering Customer’s account number (Any one is mandate Account Number or IBAN Number)	String
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	String
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	Numerical
OtherEarnings Mandatory	Additional amount to be credited apart from basic and housing allowance	Amount
Deductions Mandatory	Total amount that indicates the deductions for the concerned beneficiary	Numerical
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	Numerical
TotalTransactionAmount Mandatory	Total amount of transactions included under a specific debit account	Numerical
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”	String
PayrollReferenceNumber	Payroll Reference Number	String
TransactionData	This tag contains the status of the payments	String
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

Process a Payroll

Overview

📘
Mandatory information

Process Payroll Payouts

Endpoint details

Sample request

Sample response

✅ Successful response

Overview

📘Mandatory information

Process Payroll Payouts

Endpoint details

Sample request

Sample response

✅ Successful response

📘
Mandatory information