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

Process Payroll Payouts

Endpoint details

Endpoint URLMethodAuthentication requirements
/api/v1/payroll/transferPOST1. 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 TagDescriptionData type
OSVPayrollPaymentMessageRequest
Mandatory
Root node containing all the payroll payment transaction messagesTag
TransactionType
Mandatory
Always it should be MT100String
OSVPayrollTransactionRequest
Mandatory
This tag contains multiple banks requestsObject
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 bankString
SequenceNum
Mandatory
Unique number representing each transactionString
DateCurrencyAmount
Mandatory
Element root containing details of Date, Currency and AmountString
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 customerObject/Array
OrderingCustomerName
Mandatory
Ordering Customer’s Name String
OrderingCustomerAdd1
Mandatory
Ordering Customer’s AddressString
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 NameString
BeneficiaryName
Mandatory
Beneficiary NameString
BeneficiaryADD1
Mandatory
Beneficiary AddressString
PaymentDetails
Mandatory
Information regarding payment to the specific beneficiaryString
SalaryDetails
Mandatory
This carries the salary details of the concerned beneficiaryString
Id
Mandatory
Iqama or National ID number of the beneficiaryString
BasicSalary
Mandatory
Basic salary amountNumerical
HousingAllowance
Mandatory
Salary breakdown indicating the amount allocated to the beneficiary under housing allowancesNumerical
OtherEarnings
Mandatory
Additional amount to be credited apart from basic and housing allowanceAmount
Deductions
Mandatory
Total amount that indicates the deductions for the concerned beneficiaryNumerical
TransactionComment
Mandatory
Comments regarding the transactions included under the specific debit accountString
TotalTransactionCount
Mandatory
Total number of transactions included under a specific debit accountNumerical
TotalTransactionAmount
Mandatory
Total amount of transactions included under a specific debit accountNumerical
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 TagDescriptionData type
OSVPayrollMessageResponseRoot nodeObject
OSVPayrollTransactionResponseElement root containing response of every bank transactionsObject/Array
BankCodeName of the bank.
Ex: “ALRAJHI”, “SABB”
String
PayrollReferenceNumberPayroll Reference NumberString
TransactionDataThis tag contains the status of the paymentsString
CompanyCodeSender company Code/IdentifierString
MessageTypeType of messageString
MessageDescriptionDetails about the responseString
TransactionDateValue of “SequenceNum” tag in the request message.
Maximum Length :16 digits numeric
String
TransferTypeType of transfer (MT-100 Payroll)String
StatusCodeCode representing status of the requestString
StatusDetailDetails about the status of the requestString