Payroll payments processing

Process payroll payments through Singleview Payments API

Overview

Payroll payments can be processed through Singleview Payments API and requires 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" and Session ID
  • Payment Token has to be generated and assigned from the user end
  • OTP has to be requested and a valid OTP has to be mentioned
  • The request should be in the specified format
  • The request should include all the mandatory details with appropriate request tags

Sample request

A Process Payment request for Payroll in the following format should be posted to the URL https://servicesuat.onesingleview.com/v1/api/osvPlatform/payrollPayment.

curl --location --request POST 'https://servicesuat.onesingleview.com/v1/api/osvPlatform/payrollPayment' \
--header 'clientId: Enter_Client_ID' \
--header 'clientcode: Enter_Client_Code' \
--header 'signature: Enter_Signature' \
--header 'sid: Enter_Session_ID' \
--header 'Authorization: Bearer Enter_Authorization_Key' \
--header 'Content-Type: application/json' \
--header 'Cookie: _redisPractice=s%3AZCBGJUQpUkodCfQzjQKS8FVNocn21g2p.jbPbPmfogwh2nDlTq6zjN5PihTC7oFWyrFVWASXiVas' \
--data-raw '{
  "osvPlatformPayrollPaymentRQ": {
    "userName": "Enter_Username",
    "otp": "Enter_OTP",
    "payToken": "Enter_Payment_Token",
    "transactionType": "Enter_Transaction_Type_Code",
    "corporateCommercialRegistrationNumber": "Enter_Corporate_Commercial_Registration_Number",
    "molCorporateID": "Enter_Corporate_Labour_ID",
    "fileSeqNo": "File_Sequence_Number",
    "date": "Enter_Due_Date - Format YYYY-MM-DD",
    "osvPlatformBanks": [
      {
        "bankCode": "Enter_Bank_Code",
        "comments": "Enter_Payroll_Comments",
        "totalTransactionCount": 100,
        "totalTransactionAmount": 00.00,
        "osvPlatformPayments": [
          {
            "companyCode": "Enter_Company_Code",
            "currency": "Enter_Currency",
            "amount": 00.00,
            "debitAccount": {
              "accountHolderName": "Enter_Debit_Account_Holder_Name",
              "accountNumber": "Enter_Debit_Account_Number",
              "BIC":"Enter_BIC",
              "address": "Enter_Address"
            },
            "creditAccount": {
              "accountHolderName": "Enter_Credit_Account_Holder_Name",
              "accountNumber": "Enter_Credit_Account_Number",
              "creditAccountBankCode": "Enter_Bank_Code",
              "BIC":"Enter_BIC",
              "address": "Enter_Address"
            },
            "salaryDetails": {
              "nationalID": "Enter_National_ID",
              "basicSalary": Enter_Basic_Salary_Amount,
              "housingAllowance": Enter_Housing_Allowance_Amount,
              "otherEarnings": Enter_Other_Earnings_Amount,
              "deductions": Enter_Deductions_Amount
            },
            "description": "Enter_Payment_Description"
          },
          {
            "companyCode": "Enter_Company_Code",
            "currency": "Enter_Currency",
            "amount": 00.00,
            "debitAccount": {
              "accountHolderName": "Enter_Debit_Account_Holder_Name",
              "accountNumber": "Enter_Debit_Account_Number",
              "BIC":"Enter_BIC",
              "address": "Enter_Address"
            },
            "creditAccount": {
              "accountHolderName": "Enter_Credit_Account_Holder_Name",
              "accountNumber": "Enter_Credit_Account_Number",
              "creditAccountBankCode": "Enter_Bank_Code",
              "BIC":"Enter_BIC",
              "address": "Enter_Address"
            },
            "salaryDetails": {
              "nationalID": "Enter_National_ID",
              "basicSalary": Enter_Basic_Salary_Amount,
              "housingAllowance": Enter_Housing_Allowance_Amount,
              "otherEarnings": Enter_Other_Earnings_Amount,
              "deductions": Enter_Deductions_Amount
            },
            "description": "Enter_Payment_Description"
          }
        ]
      }
    ]
  }
}'

Request description:

JSON TagDescriptionData type
clientId
Mandatory
Client IDString
clientCode
Mandatory
Client CodeString
signature
Mandatory
SignatureString
sid
Mandatory
Session IDString
Authorization: Bearer
Mandatory
Authorization Bearer Code i.e., Access TokenString
osvPlatformPayrollPaymentRQ
Mandatory
Payroll payment process Request TagObject
userName
Mandatory
Account UsernameString
otp
Mandatory
One-Time Password for Payment VerificationString
payToken
Mandatory
Payment Token for AuthorizationString
corporateCommercialRegistrationNumber
Mandatory
Corporate Commercial Registration NumberString
fileSeqNo
Mandatory
4-Digit Payroll file sequence number (MMNN)
MM - Month
NN - Number of payroll in particular month
String
date
Mandatory
Scheduled date (Due date) in the format YYYY-MM-DDString
transactionType
Mandatory
Type of transactionsString
osvPlatformBanks
Mandatory
Array of BanksArray
bankCode
Mandatory
Bank Code as per Bank NameString
comments
Mandatory
Comments about the paymentString
totalTransactionCount
Mandatory
Number of transactionsString
totalTransactionAmount
Mandatory
Total amount subjected to included transactionsString
osvPlatformPayments
Mandatory
Array of Payment to processArray
companyCode
Mandatory
Company CodeString
currency
Mandatory
Currency of the paymentString
amount
Mandatory
Amount to be paidString
debitAccount
Mandatory
Debit account detailsObject
accountHolderName
Mandatory
Name of the account holderString
accountNumber
Mandatory
Account NumberString
BIC
Mandatory
IFSC Code of the bankString
address
Mandatory
AddressString
creditAccount
Mandatory
Crediting account detailsObject
creditAccountBankCode
Mandatory
Bank code of the crediting accountString
salaryDetails
Mandatory
Details & Breakdown of SalaryString
nationalId
Mandatory
National ID or Iqama IDString
basicSalary
Mandatory
Basic salary amountString
housingAllowance
Mandatory
Amount for housing allowanceString
otherEarnings
Mandatory
Amount representing other earningsString
deductions
Mandatory
Amount representing deductionsString
description
Mandatory
Description messageString

Sample responses

Valid/Successful response

✔️ If Valid information in the header and body of a request is processed successfully

{
  "osvPlatformPayrollPaymentRS": {
    "status": "SUCCESS",
    "osvPlatformBanks": [
      {
        "bankCode": "Bank_Code",
        "transactionReferenceNumber": "Transaction_Reference_Number",
        "osvPlatformPayments": [
          {
            "status": "Status_of_Processing",
            "statusDetail": "Status_Detailed_Message",
            "messageDescription": "Description",
            "companyCode": "Company_Code",
            "transactionDate": "DATE",
            "fileSeqNo": "MMNN"
          }
        ]
      }
    ]
  }
}

Valid/Successful response description:

JSON TagDescriptionData type
osvPlatformPayrollPaymentRSPayroll payment processing Response TagObject
statusStatus of the processString
osvPlatformBanksArray of BanksArray
bankCodeBank CodeString
transactionReferenceNumberTransaction Reference Number by SVString
osvPlatformPaymentsPayment processed tagString
statusStatus of the processString
statusDetailProcess Status DetailsString
messageDescriptionDescriptive messageString
companyCodeCompany CodeString
transactionDateDate of transactionString
fileSeqNoFile Sequence NumberString

Invalid/Failed response

❌ If Invalid information in the header of a request is processed successfully

{
        status: "FAILURE",
        errorCode: "Failed_Code",
        message: "Failed_Message"
      }

Invalid/failed response description:

JSON TagDescriptionData type
statusStatus of the ProcessString
errorCodeError CodeString
messageResponse MessageString

Response in case of a Technical error is encountered

⚠️ When the process encounters a technical error

{
        status: "TECHERROR",
        errorCode: "Error_Code",
        message: "Error_Message"
      }

Error response description:

JSON TagDescriptionData type
statusStatus of the ProcessString
errorCodeError CodeString
messageResponse MessageString