Batch Payments
Batch payments simplify handling multiple transactions by using a file upload system. This allows a quick start to processing payments by uploading/downloading payment files through the Lorum portal.
Batch payments currently support AED local payments processed via UAE payment rails.
File Format
This section describes the requirements to initiate local payouts via a file.
Request File
The request file is a CSV file.
The file should be named as follows:
local-{{ddmmyyyy}}-{{sequence_no}}.csv
- local - This is a fixed constant identifying the file as a local payout file.
- ddmmyyyy - date identifier in
ddmmyyyyformat. The date should be specified in UTC. - sequence_no - the number of file for that day.
The following table describes the file format:
| Column Header | Type | Mandatory | Description |
|---|---|---|---|
| sequence_no | Int (max 65000) | yes | Determines the row number of the payment. Used to correlate with created payments. |
| source_account_id | UUID (36 characters) | yes | The account ID in the Lorum system is where the funds will be paid from. |
| instructed_amount | Int | yes | This is the amount in minor currency. For example, AED1.00 will be 100. |
| beneficiary_name | String (35 characters) | yes | The name on the beneficiary account. |
| beneficiary_iban | String (34 characters) | yes | The IBAN to identify the beneficiary account. |
| beneficiary_bic | String (8 characters) | yes | The BIC code where the beneficiary account is held. |
| beneficiary_address_line1 | String | yes | The first line of the beneficiary address. |
| beneficiary_address_line2 | String | no | The second line of the beneficiary address. |
| beneficiary_address_line3 | String | no | The third line of the beneficiary address. |
| beneficiary_address_line4 | String | no | The fourth line of the beneficiary address. |
| beneficiary_address_country | String (2 characters) | yes | The ISO-3166 Alpha2 country code for the beneficiary address. |
| beneficiary_bank_branch | String | no | The bank branch where the beneficiary account is held. |
| beneficiary_email | String | no | The email address for the beneficiary. |
| beneficiary_phone | String | no | The phone number for the beneficiary. |
| external_reference | String (30 characters) | yes | Reference that can be set by the customer. |
| purpose | String (derived from an enum) | yes | The purpose of the transaction. See possible values below. |
| beneficiary_nationality | String (2 characters) | no | The ISO-3166 Alpha2 country code for the beneficiary address. |
| beneficiary_date_of_birth | String (10 characters) | no | In the date format of yyyy-mm-dd. |
| beneficiary_id_type | String (derived from enum) | no (mandatory if ID number provided) | Possible values: - uae_id - passport - if passport is provided then beneficiary_nationality is also required |
| beneficiary_id_number | String | no (mandatory if ID type provided) | Number of characters and format based on ID type. - uae_id - 18 characters in format of NNN-NNNN-NNNNNNN-N - passport - maximum 100 characters |
| beneficiary_type | String (derived from enum) | yes | The type of beneficiary. Possible values are individualand business |
Response File
The response file is a CSV file.
The Lorum portal provides functionality to find payments for a batch ID and download a CSV which can be used to provide updates to a customer system.
The file will be named as follows:
response-local-{{ddmmyyyy}}-{{sequence_no}}.csv
- response - This is a fixed constant identifying the file as a response file.
- local - This is a fixed constant identifying the file as a local payout file.
- ddmmyyyy - date identifier in
ddmmyyyyformat. The date should be specified in UTC. This will match the timestamp in the request file name. - sequence_no - the number of file for that day. This will match the sequence_no set in the request file name.
The following table describes the file format.
| Column Header | Type | Mandatory | Description |
|---|---|---|---|
| sequence_no | Int (max 65000) | yes | Determines the row number of the payment. Used to correlate with created payments. |
| fuse_transaction_id | UUID (36 characters) | yes | Transaction ID set by the Lorum system. |
| source_account_id | UUID (36 characters) | yes | The account ID in the Lorum system is where the funds will be paid from. |
| instructed_amount | Int | yes | This is the amount in minor currency. For example, AED1.00 will be 100. |
| fee_amount | Int | yes | The fee amount levied on the transaction. |
| amount_with_fee | Int | yes | The total amount including the fee (instructed_amount + fee_amount). |
| beneficiary_name | String (35 characters) | yes | The name on the beneficiary account. |
| beneficiary_iban | String (34 characters) | yes | The IBAN to identify the beneficiary account. |
| external_reference | String (30 characters) | yes | Reference that can be set by the customer. |
| state | String (derived from an enum) | yes | The current status of the payment. |
| failure_reason | String (derived from an enum) | no | The reason the payment failed if the payment state is failed. |
Updated about 1 month ago