Overview

Payroll payment is a service that enables your system to submit a file to make payroll payments. It's an easy way to pay your employees no matter the channel you choose. 

 

Payroll Channels
Channel Description
ANB anb to anb
SWIFT International payments through SWIFT network
SARIE Local payments through SARIE RTGS network

 

Prerequisites

To use the Payroll Payment service, you need to do the following:

  • Register/Login to the anb Developer Portal.
  • Create an app.
  • You should now have a client id and secret associated with your app.
  • Get an access token from our auth service using your client id and secret.

 

Payroll File Specification

Payroll payments will be submitted via two CSV (comma separated values) files. The structure of the files should be as the following: 

Header file:

The first row of the file should specify the header of the credit account.

batchNumber,batchType,molEstablishmentId,mainAccountNumber,creditValueDate,organizationName,organizationAddress1,organizationAddress2,organizationAddress3,paymentCount,totalPayrollAmount,narrative
670,PAYROLL,1234-5,0108061198800026,210216,Organization,KSA,RIYADH,Muraba'a,2,2000,Narrative

 

Payroll Header File Specifications
Field Description Required Format Min Length Max Length Note
Batch number A unique number used to avoid duplication. The batch number should be unique Yes Number string 1 20 Appears in "file reference" field in WPS file
Batch type Batch type Yes Enum string [PAYROLL, BENEFIT, BONUS, WELFARE]      
MoL establishment id Establishment identification registered in MoL Yes String 2 15 Appears in "molEstId" field in WPS file
Main account number anb account number to be used to debit the payroll amount Yes Number String 16 16  
Credit value date The date on which the employees' accounts will be credited Yes YYMMDD 6 6  
Organization name Organization Name Yes String 1 35  
Organization address 1 Ordering address 1 Yes String 1 35  
Organization address 2 Organization address 2 Yes String 1 35  
Organization address 3 Organization address 3 Yes String 1 35  
Payment count Number of rows recorded in payroll body file Yes Number 1 6  
Total payroll amount Total amount to be debited from main account number Yes Number      
Narrative Narrative to be sent with the payroll payment Yes String 1 35 Appears as a "payment description" in WPS file for each payroll payment

 

Body file:

The first row of the file should specify the body of of the debit accounts (employees accounts).

employeeId,employeeAccountNumber,salaryAmount,basicSalary,housingAllowance,otherEarnings,salaryDeductions,bicCode,employeeName,employeeAddress1,employeeAddress2,employeeAddress3
802630,0108057386290038,1500.5,1000,500.5,0,0,ARNBSARI,Omar,KSA,Medina,North
802630,0108057386290045,1300,900,400,0,0,ARNBSARI,Abdulrahman,KSA,Medina,North
Payroll Body File Specifications
Field Description Required Format Min Length Max Length Note
Employee id National id or Iqama number of the employee Yes Number String 10 10 Appears in WPS file
Employee account number Employee account number Yes String 16 35 In case the transfer is to a local bank, then the IBAN of the employee's account should be provided
Salary amount Net amount to be sent to the employee Yes Number 1 12  
Basic salary Basic salary Yes Number 1 12 In case not applicable, then your system should send 0
Housing allowance Housing allowance Yes Number 1 12 In case not applicable, then your system should send 0
Other earnings Other earnings Yes Number 1 12 In case not applicable, then your system should send 0
Salary deductions Salary deductions Yes Number 1 12 In case not applicable, then your system should send 0
BIC code Employee bank code Yes String 8 11  
Employee name Full name of the employee Yes String 1 50 It is important to provide the full name to avoid any payment rejections from the destination bank
Employee address 1 Employee address 1 Yes String 1 30  
Employee address 2 Employee address 2 Yes String 1 30  
Employee address 3 Employee address 3 Yes String 1 30  

 

Once the file gets submitted, the service will assure the validity of the file format and its structure. In case of any issue in the structure or the format, the file will be rejected immediately. If the file format is valid, the file will be accepted and prepared to be processed, and you will receive a unique UUID to be used for any further inquiries. Then, each payment will be validated against a couple of static validation to assure its readiness to be processed.

 

 

Payroll Processing In Depth

Once B2B system receives a payroll request, it will validate the file against a couple of static validations (format, length, data types .. etc). If it is not valid, the payroll file will be rejected. If valid, the payroll will be initiated in B2B system, a unique UUID number will be generated and a response will be sent back to the client. Then, dynamic validations will be running to assure the validity of other parameters. Once validated, the payroll will be sent to core systems to post the payments and mark them as either successful or failed.

 

Payroll Statuses
Status Description
INITIATED Payroll schema is valid and is ready to be processed
QUEUED Payroll value date is future, so it is currently queued
ACCEPTED Payroll has been accepted by the PMS(Payroll Management System)
VALIDATED Payroll has been validated by PMS
IN_PROGRESS Payroll is being processed by PMS
COMPLETED Payroll has been processed by PMS
CANCELED Queued Payroll is canceled
FAILED Payroll failed
PROCESSED Local/SWIFT payment is completed
REJECTED Payroll is rejected due to insufficient balance

Payroll Inquiry Service

You can inquire about the status of previously posted payroll files using the unique UUID that is returned from posting.

 

Payroll Inquiry Response
Field Description Always
Id Unique UUID of the payment to be used to inquire about payment status Yes

Status

 payroll status Yes

Payments

 Array of payments No

Payments.employeeId

 Employee id provided in the file No
Payments.employeeAccountNumber The credit account No
Payments.salaryAmount The amount to be transferred No
Payments.bicCode destination bic code No
Payments.paymentId Unique UUID of the payment can be used to inquire about payment status No
Payments.paymentStatus Payment status No

 

 

You may use single payment inquiry service to inquire about the individual payments extracted from the bulk file. Also, the events emitted during single payment processing will also be emitted for each payment submitted in the bulk file.

 

Payroll Payment WPS File Service

You may use this service to get a Wage Protection System (WPS) file. The file complies with the Saudi Labor Law.

 

Cancel Payroll Service

You may use this service to cancel previously submitted payroll. The service will return status canceled if successful.

You can Cancel a payroll only if the status is Queued