LuLu Money's D9 Platform Services [DPS] provides an ecosystem to manage cross-border payments. DPS supports agency models for both white labeling and payment as service modes. Agents are provided with multiple integration channels to consume services, either through DPS' direct APIs or through reliable DLT networks. This document covers the direct API integration model.
...
Version | Description | Author | Date (dd/mm/yyyy) |
1.0.0 | DRAP API Document | Ajai Antony | 07/06/2024 |
1.0.1 | Transaction Status Update API | Ajai Antony | 25/06/2024 |
1.0.2 | Service types included under - Get Codes, Create Quote & Create Txn | Ajai Antony | 04/07/2024 |
1.0.3 | Host details updated | Ajai Antony | 28/08/2024 |
1.0.4 | BRN Update API changes | Ajai Antony | 24/10/2024 |
1.0.5 | Updated Master APIs | Ajai Antony | 05/11/2024 |
CLASSIFICATION: PUBLIC
Table of Contents |
---|
Overview
...
Transaction Work Flow
...
eKYC Flow
...
Host Details
Type | Domain Name | Environment | IP Address | Port |
Public IP -Inbound | Production | 20.74.248.66 | 443 | |
Public IP - Outbound | Production | 20.233.88.26 | 443 | |
Public IP -Inbound | Sandbox | 129.151.150.45 | 443 | |
Public IP - Outbound | Sandbox | 20.233.88.26 | 443 |
Access & Privileges
DPS API is available for access if its security gate's requirements are cleared.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
access_token | String | 600 | Yes | Access token to access the APIs |
expires_in | Integer | - | Yes | access_token expiry time in seconds |
refresh_expires_in | Integer | - | No | refresh_token expiry time in seconds |
refresh_token | String | 600 | No | Refresh Token |
token_type | String | - | Yes | Token type |
not-before-policy | Integer | - | - | - |
session_state | String | - | - | - |
scope | String | - | Yes | Scope details |
Transaction APIs
A simple three-step transaction processing model where the APIs are invoked in an order of creating quote as the first step, then creating a payment order & authorizing a payment order for the last mile processing.
...
Reference code API to be referred for the properties where the flags and codes are defined by the system is expected by the transaction API. Reference codes to be stored and mapped at sending institution’s systems and to be used while passing the message.
Create Quote
API to get the exchange rate and fee details between the sending country and receiving country and the currency pair.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | String | 120 | Yes | Status code |
data | Object | - | Yes | Data object |
quote_id | String | 16 | Yes | Unique identification key for quote |
created_at | String | 22 | Yes | Quote created date and time in local time |
created_at_gmt | String | 22 | Yes | Quote created date and time in GMT |
expires_at | String | 22 | Yes | Quote expiry date and time in local time |
expires_at_gmt | String | 22 | Yes | Quote expiry date and time in GMT |
sending_country_code | String | 2 | Yes | Send country; ISO 2 Char country code |
sending_currency_code | String | 3 | Yes | Send currency: ISO 3 Char currency code |
receiving_country_code | String | 2 | Yes | Beneficiary receive country; ISO 2 Char country code |
receiving_currency_code | String | 3 | Yes | Beneficiary receive currency; ISO 3 Char currency code |
sending_amount | BigDecimal | - | Yes | Send amount |
receiving_amount | BigDecimal | - | Yes | Receive amount |
total_payin_amount | BigDecimal | - | Yes | Total payin amount |
price_guarantee | String | 10 | Yes | Indicates whether a quote's pricing is |
fx_rates | List |
| Yes | Lulu exchange rate |
cost_rate | BigDecimal | (15,8) | Conditonal | It is a cost to the partner |
rate | BigDecimal | (15,8) | Yes | exchange rate value |
base_currency_code | String | 3 | Yes | base currency for the rate |
counter_currency_code | String | 3 | Yes | counter currency for the rate |
type | String | - | Yes | exchange rate type. buy/sell |
fee_details | List |
| Yes | Lulu fee details |
type | String | - | Yes | fee type like COMMISSION/TAX |
model | String | 4 | Yes | Fee type model. Possible values are OUR/BENE |
currency_code | String | 3 | Yes | fee Currency code; ISO 3 Char currency code depending on the model (OUR/BENE) selected. If OUR - Send Ccy code & if BENE - Receive Ccy code |
amount | BigDecimal | - | Yes | fee amount |
description | String | 60 | No | Description of the fee |
settlement_details | List | - | Yes | Settlement details |
charge_type | String | - | Yes | Charge type like COMMISSION/TREASURYMARGIN |
value | BigDecimal | (15,8) | Yes | Share value |
currency_code | String | - | Yes | fee currency code |
correspondent_rules | List | - | Yes | Correspondent validation rules for create transaction. It varying based on correspondent. No rules then empty list |
field | String | - | No | Field Name |
rule | String | - | No | Mandatory or not |
Create Transaction
It will create transactions in the lulu system after validating sender, receiver and transaction details.
...
Name | Data Type | Max Length | Name | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | String | 120 | Yes | Status code |
data | Object | - | Yes | Data object |
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
transaction_date | String | 26 | Yes | Transaction locked date and time in local time |
transaction_gmt_date | String | 26 | Yes | Transaction locked date and time in GMT |
expires_at | String | 22 | Yes | Payment expiry date and time in local time |
expires_at_gmt | String | 22 | Yes | Payment expiry date and time in GMT |
Confirm Transaction
It will confirm the transaction after validating the transaction number and status.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
Authorize Clearance
It will authorize clearance after validating the transaction number and status.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
Enquire Transaction
Enquire transaction API returns the current status of the transaction. This API can be used to query the current status and details of the transaction.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
transaction_date | String | 26 | Yes | Transaction locked date and time in local time |
transaction_gmt_date | String | 26 | Yes | Transaction locked date and time in GMT |
type | String | 2 | Yes | SD - Send, RV - Receive |
source_of_income | String | 4 | Yes | Sender source of income |
purpose_of_txn | String | 4 | Yes | Purpose of the transaction |
message | String | 200 | No | Any free text |
instrument | String | 60 | Yes | Specify the instrument type like Remittance, Bill Payment |
sender | Object | - | Yes | Sender object |
agent_customer_number | String | 60 | No | Agent stored customer id |
customer_number | String | 16 | Yes | Lulu customer number |
mobile_number | String | 20 | Yes | Sender mobile number |
String | 320 | Yes | Sender email address | |
first_name | String | 60 | Yes | Sender first name |
last_name | String | 60 | Yes | Sender last name |
middle_name | String | 60 | No | Sender middle name |
date_of_birth | Date | - | Yes | Sender date of birth date |
country_of_birth | String | 2 | Yes | Sender country of birth; ISO 2 Char country code |
gender | String | 1 | Yes |
|
nationality | String | 2 | Yes | Sender nationality code; ISO 2 Char country code |
employer | String | 300 | Yes | Sender employer name |
profession_code | String | 4 | Yes | Sender profession code |
visa_type_code | String | 3 | Yes | Sender visa type code |
senderid | List | 1 | Yes |
|
id_code | String | 3 | Yes | Sender id type code. Example : 4 for emirates ID |
id | String | 30 | Yes | Sender ID / number. Example : Emirates ID |
issued_country_code | String | 2 | Yes | Sender id issued country; ISO 2 Char country code |
issued_on | Date | - | No | Sender id issued on date |
valid_through | Date | - | Yes | Sender id expiry date |
issued_by | String | 40 | No | Sender id issued by |
sender_address | List | 1 | Yes |
|
address_type | String | 20 | Yes | Sender address type like Present, Permanent |
address_line | String | 70 | Yes | Sender address line |
street_name | String | 70 | Yes | Sender street name |
building_number | String | 16 | Yes | Sender building number |
post_code | String | 16 | Yes | Sender postal area code. Example: Zipcode, Pincode |
pobox | String | 12 | No | Sender post box number |
town_name | String | 35 | Yes | Sender town name |
country_subdivision | String | 35 | Yes | Sender country sub division like state, city |
country_code | String | 2 | Yes | Sender country code; ISO 2 Char country code |
receiver | Object | - | Yes |
|
agent_receiver_id | String | 60 | No | Agent stored receiver id |
mobile_number | String | 20 | No | Receiver mobile number |
first_name | String | 60 | Yes | Receiver first name |
last_name | String | 60 | Yes | Receiver last name |
middle_name | String | 60 | No | Receiver middle name |
date_of_birth | Date | - | No | YYYY-MM-DD format |
gender | String | 1 | Yes | Receiver gender name |
nationality | String | 2 | Yes | Receiver nationality code; ISO 2 Char country code |
relation_code | String | - | Yes | Relation type like Friend, Brother |
receiver_address | List | 1 | Yes |
|
address_type | String | 20 | Yes | Receiver address type like Present, Permanent |
address_line | String | 70 | Yes | Receiver address line |
street_name | String | 70 | Yes | Receiver street name |
building_number | String | 16 | Yes | Receiver building number |
post_code | String | 16 | Yes | Receiver postal area code. Example: Zipcode, Pincode |
pobox | String | 12 | No | Receiver post box number |
town_name | String | 35 | Yes | Receiver town name |
country_subdivision | String | 35 | Yes | Receiver country sub division, like state, city. |
country_code | String | 2 | Yes | Receiver country code; ISO 2 Char country code |
receiver_id | List | 1 | No |
|
id_code | String | - | No | Receiver id type code. Example : 4 for emirates ID |
id | String | 30 | No | Receiver ID / number. Example : Emirates ID |
issued_country_code | String | 2 | No | Receiver id issued country; ISO 2 Char country code |
issued_on | Date | - | No | Receiver id issued on date |
valid_through | Date | - | No | Receiver id expiry date |
issued_by | String | 40 | No | Receiver id issued by |
bank_details | Object | - | Conditional | Mandatory for Bank transfer |
account_type_code | String | - | Yes | Receiver account type like savings, current. |
account_number | String | 34 | Yes | Receiver bank account number |
iso_code | String | 11 | Yes | Receiver bank ISO code |
iban | String | 34 | No | Receiver bank IBAN number |
cashpickup_details | Object | - | Conditional | Mandatory for cash pick up |
correspondent | String | 2 | Yes | Correspondent name. It is mandatory for Cash Payout |
correspondent_id | String | 100 | Yes | Correspondent ID. It is mandatory for Cash Payout |
correspondent_location_id | String | 100 | Yes | Correspondent location ID. It is mandatory for Cash Payout |
transaction | Object | - | Yes |
|
quote_id | String | 16 | Yes | Unique quote id to identify the rate and fee. |
channel_quote_id | String | 36 | No | Unique channel quote id to push transaction status back to Ripple |
agent_transaction_ref_number | String | 60 | No | Agents unique transaction reference number |
receiving_mode | String | 20 | Yes | Receive mode / delivery mode. Example : BANK, CASHPICKUP |
payment_mode | String | 2 | No | Payment mode |
sending_country_code | String | 2 | Yes | Operation country; ISO 2 Char country code |
sending_currency_code | String | 3 | Yes | Sending currency; ISO 3 Char currency code |
receiving_country_code | String | 2 | Yes | Beneficiary receive country; ISO 2 Char country code |
receiving_currency_code | String | 3 | Yes | Beneficiary receiving currency; ISO 3 Char currency code |
sending_amount | BigDecimal | - | Yes | Send amount |
receiving_amount | BigDecimal | - | Yes | Receiver receiving amount |
total_payin_amount | BigDecimal | - | Yes | Total payin amount |
fx_rates | List |
| Yes | Lulu exchange rate |
rate | BigDecimal | (15,8) | Yes | exchange rate value |
base_currency_code | String | 3 | Yes | base currency for the rate; ISO 3 Char country code |
counter_currency_code | String | 3 | Yes | counter currency for the rate |
type | String | - | Yes | exchange rate type. buy/sell |
fee_details | List |
| Yes | Lulu exchange fee details |
type | String | - | Yes | fee type like COMMISSION/TAX |
model | String | 4 | Yes | Fee type model. Possible values are OUR/BENE |
currency_code | String | 3 | Yes | fee Currency code; ISO 3 Char currency code |
amount | BigDecimal | - | Yes | fee amount |
description | String | 60 | No | Description of the fee |
settlement_details | List | - | Yes | Settlement details |
charge_type | String | - | Yes | Charge type like COMMISSION/TREASURYMARGIN |
value | BigDecimal | (15,8) | Yes | Share value |
currency_code | String | - | Yes | fee Currency code |
BRN Update
It will update the bank reference number.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
Cancel Transaction
It will cancel the transaction after validating the transaction number and status.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
transaction_ref_number | String | 16 | Yes | Transaction reference number |
Transaction Receipt
This API will return the invoice report of the transaction as base64 data.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
data | String |
| Yes | Base64 data |
Transaction Status Update
This API is used to update the status of the transaction like partner where transaction fulfillment happens in partner network. Since fulfillment happens from partner network, status need to take from partners by this API.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | - | Yes | Status value should always be “ACKNOWLEDGED” |
Callback APIs
Transaction Status Callback
This is a callback API that we should call to push the status of the transaction. This API will be hosted by the Partner as per below spec. For integrity validation a pre shared secret can be used for computing payload hash. When calling the API we will compute the hash by concatenating the pre shared secret at the end of the request payload as below:
...
Those transactions status push will not be processed anymore, get the latest information from transaction enquiry API.
...
Master APIs
Get Codes
Get codes API returns the master data for Id types, relation, profession, purpose, payments modes, instruments, receiving modes, fee types, address types, income range types, correspondent, cancelation reasons and account types list for the available services. This API will return all types in the response if the param is empty.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Eg : 200 |
data | Object | - | Yes | Data object |
relationships | Array | - | Yes | Relation array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
id_types | Array | - | Yes | ID Types array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
sources_of_income | Array | - | Yes | Source of Income array object |
code | String | 4 | Yes | ISO code for representing Source of Income |
name | String | 60 | Yes | name |
purposes_of_txn | Array | - | Yes | Purposes of txn array object |
code | String | 4 | Yes | ISO code for representing Purposes of txn |
name | String | 60 | Yes | name |
professions | Array | - | Yes | professions array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
account_types | Array | - | Yes | account types array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
payment_modes | Array | - | Yes | payment modes array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
visa_types | Array | - | Yes | payment modes array object |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
instruments | Array | - | Yes | Instrument value ENUMs |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
address_types | Array | - | Yes | address_type value ENUMs |
id | Integer | - | Yes | id |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
receiving_modes | Array | - | Yes | receiving_modes value ENUMs |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
fee_types | Array | - | Yes | fee_types value ENUMs |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
income_types | Array | - | Yes | Income type values |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
income_range_types | Array | - | Yes | Income type range values |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
cancel_reason_codes | Array | - | Yes | Cancel Reason values |
code | String | 20 | Yes | code |
name | String | 60 | Yes | name |
transaction_count_per_month | Array | - | Yes | Transaction count per month range values |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
transaction_volume_per_month | Array | - | Yes | Transaction volume per month range values |
code | String | 3 | Yes | code |
name | String | 60 | Yes | name |
correspondents | Array | - | Yes |
|
code | String | 2 | Yes | correspondent |
name | String | 60 | Yes | name |
document_types | Array | - | Yes |
|
code | String | 3 | Yes | isocode |
name | String | 60 | Yes | document description |
proof_content_types | Array | - | Yes |
|
code | String | 3 | Yes | extension |
name | String | 60 | Yes | path |
business_types | Array | - | Yes |
|
code | String | 3 | Yes | businessType |
name | String | 60 | Yes | businessDescription |
Get Service Corridor
Fetches the service details, corridor details, currency details and agent details.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Status code |
data | Object Array | - | Yes |
|
instrument | String | 60 | Yes | Instrument type like Remittance, |
transaction_type | String | - | Yes | SEND or RECEIVE |
receiving_mode | String | 20 | Yes | Example : BANK, CASHPICKUP |
sending_country_code | String | 2 | Yes | Operation country code; ISO 2 Char country code |
sending_country | String | 60 | Yes | Operation country name |
receiving_country_code | String | 2 | Yes | Beneficiary receive country code; ISO 2 Char country code |
receiving_country | String | 60 | Yes | Beneficiary receive country |
limit_currency | String | 60 | Yes | Currency name to check the limit |
limit_currency_code | String | 3 | Yes | Currency code to check the limit: ISO 3 Char currency code |
limit_min_amount | BigDecimal | - | Yes | Minimum amount for each transaction |
limit_per_transaction | BigDecimal | - | Yes | Maximum limit per transaction |
send_min_amount | BigDecimal | - | Yes | Minimum limit for transactions |
send_max_amount | BigDecimal | - | Yes | Maximum limit for transactions |
corridor_currencies | Object Array | - | Yes | Agent and currency details |
sending_currency_code | String | 3 | Yes | Sending currency code; ISO 3 Char currency code |
sending_currency | String | 60 | Yes | Sending currency name |
receiving_currency_code | String | 3 | Yes | Receiving currency code; ISO 3 Char currency code |
receiving_currency | String | 60 | Yes | Receiving currency name |
correspondent | String | 2 | Yes | Correspondent code / ID |
correspondent_name | String | 60 | Yes | Correspondent name |
anywhere | Integer | - | No | Indicates the pick up anywhere is available or not |
Get Bank Master
Bank API returns the list of banks available in the country. The results can be paginated if necessary parameters are passed with the request.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | String | 120 | Yes | Status code |
data | Object | - | Yes |
|
list | Object Array | - | Yes | list contains array of banks id,name |
bank_name | String | 60 | Yes | Bank name |
bank_id | Integer | - | Yes | Internal Bank ID |
records | Integer | - | Yes | number of fetched records |
total_records | Integer | - | Yes | Total entries available |
total_page | Integer | - | Yes | Total result page number |
current_page | Integer | - | Yes | Current page no |
Get Bank By Id
Bank API returns the details of bank with the given bank id.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Eg 200,401 |
data | Object | - | Yes |
|
bank_name | String | 60 | Yes | Bank name |
bank_id | String | 20 | Yes | Internal Bank ID |
bank_country_code | String | 2 | Yes | Bank country code Eg : IN |
bank_account_number_length | String | - | Yes | Eg : |
bank_address | String | 60 | Optional | address of bank |
Get Branch Master
Branch API returns the list of branches for the given bank.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Status code |
data | Object | - | Yes |
|
list | Object Array | - | Yes | list contains array of results |
bank_name | String | 60 | Yes | Bank branch name |
branch_id | Integer | - | Yes | Internal Branch code |
bank_id | Integer | - | Yes | Internal bank Id |
branch_name | String | 70 | Yes | Branch name |
routing_code | String | 30 | No | Routing code |
sort | String | 15 | No | Sort code |
iso_code | String | 30 | No | ISO Code |
bank_branch_name | String |
| NO | bank branch name |
ifsc | String |
| NO | ifsc |
bic | String |
| YES | bic |
address | String |
| NO | address |
town_name | String |
| NO | town name |
country_subdivision | String |
| NO | country subdivision |
country_code | String |
| NO | country code |
Get Branch By Id
Bank Branch by Id API returns the details of bank-branch with the given bank_id and branch_id
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | String | 120 | Yes | Status code |
data | Object Array | - | Yes |
|
bank_id | String | - | Yes | Bank Id |
branch_id | String | - | Yes | Internal Branch code |
branch_name | String | - | Yes | Bank branch name |
branch_full_name | String | 300 | Yes | Bank branch full name |
address | String | - | No | address of bank branch |
country_code | String | 2 | Yes | Country code |
routing_code | String | 30 | No | Routing code |
iso_code | String | 11 | No | ISO code |
bic | String | - | No | Bic |
sort | String | 15 | No | Sort code |
bank_name | String |
| No | bank name |
town_name | String |
| No | town name or city |
country_subdivision | String |
| No | country subdivision or state |
ifsc | String |
| No | ifsc |
Branch Search
Branch Search API is used to get detailed information about branch with iso, routing or sort codes
Note Lookup on any one of the request parameter[iso_code, routing_code, sort_code] is allowed
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Intger | - | Yes | Status code |
data | Object | - | Yes |
|
list | Object Array | - | Yes | list contains Object array |
bank_id | String | - | Yes | Bank code |
branch_id | String | - | Yes | Internal Branch code |
branch_full_name | String | 300 | Yes | Bank branch full name |
branch_name | String | 70 | Yes | Branch name |
routing_code | String | 30 | No | Routing code |
sort | String | 15 | No | Sort code |
address | String | 70 | Yes | Bank address |
town_name | String | 35 | No | Bank address town name |
country_subdivision | String | 70 | No | Bank address country sub division like state,city |
country_code | String | 2 | Yes | Bank address country code:ISO 2 Char country code |
iso_code | String | - | Yes | ISO code |
bank_name | String |
| No | bank |
ifsc | String |
| No | ifsc |
bic | String |
| No | nic |
records | Integer | - | Yes | number of fetched records |
total_records | Integer | - | Yes | Total entries available |
total_page | Integre | - | Yes | Total number of pages available according to given page and size params values |
current_page | Integer | - | Yes | Current page number |
Get Agent Credit Balance
Fetches the agent credit balance.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Status code |
data | Object Array | - | Yes |
|
closingBalance | Integer | - | Yes | Closing Balance |
currency | String | 3 | Yes | Currency code
|
Get Rates
Fetches the exchange rates between the sending country and all its possible recipient
countries. When the filter parameter is passed, the API will return only a specific country code and/or currency code rate.
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Status code |
rates | Object Array | - | Yes | Rates array object |
from_currency | String | 3 | Yes | From currency - default currency for the agent |
to_currency | String | 3 | Yes | Receiving currency code; ISO 3 Char currency code |
to_currency_name | String | 60 | Yes | Receiving currency name |
to_country | String | 3 | Yes | Receiving country code |
to_country_name | String | 60 | Yes | Receiving country name |
rate | BigDecimal | (15,8) | Yes | Lulu exchange rate |
receiving_mode | String | 20 | Yes | Receive mode / delivery mode. Example : BANK, CASHPICKUP |
correspondent | String | - | Conditional | Correspondent code / ID |
correspondent_name | String | - | Conditional | Correspondent name |
anywhere | Integer | - | Conditional | Indicates the pick up anywhere is available or not |
Account validation
Validate the account number length
...
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
status | String | 60 | Yes | Status description |
status_code | Integer | - | Yes | Status code |
data | String | - | Yes | Eg value |
message | String | - | No | Eg Value : |
error_code | Integer | - | No | Error code value |
Transaction States and Sub-States
Transaction Activity | State | Sub-State | Description |
CREATE TXN | INITIATED | QUOTE_ACCEPTED | Quote accepted for the given currency pair |
| INITIATED | ORDER_VERIFIED | Order verified for the given details |
| ACCEPTED | ORDER_ACCEPTED | Order accepted for the given verified details |
| REJECTED | ORDER_REJECTED | Order rejected after verification |
CONFIRM TXN | IN_PROGRESS | PAYMENT_PENDING | Payment pending for the transaction |
IN_PROGRESS | BALANCE_IN_SUFFICIENT | Insufficient balance in the prefund account | |
IN_PROGRESS | PAYMENT_AWAIT_CLEARANCE | Awaiting payment clearance | |
IN_PROGRESS | PAYMENT_SETTLED | Payment settled | |
IN_PROGRESS | PAYMENT_REJECTED | Payment rejected | |
IN_PROGRESS | PAYMENT_APPROVED | Payment approved | |
CONFIRM TXN | IN_PROGRESS | AML_PENDING | Pending for AML |
| IN_PROGRESS | AML_COMPLETED | AML completed |
| IN_PROGRESS | AML_MARKED_FOR_EDD | Marked for EDD |
IN_PROGRESS | AML_FAILED | AML failed | |
CONFIRM TXN | IN_PROGRESS | AWAITING_CLEARANCE | Awaiting AML clearance |
IN_PROGRESS | CLEARANCE_ACCEPTED | AML clearance accepted | |
CONFIRM TXN | IN_PROGRESS | TXN_VERIFIED | Transaction verified |
| IN_PROGRESS | TXN_PREPARED | Transaction prepared |
CONFIRM TXN | REJECTED | AML_REJECTED | AML rejected |
EXECUTED | EXECUTED | TXN_RELEASED | Transaction released |
EXECUTED | TXN_TRANSMITTED | Transaction transmitted | |
CREDITED* | COMPLETED | CREDITED | Transaction credited |
COMPLETED | AVAILABLE_PAID | Transaction Available for pickup or Paid | |
| COMPLETED | RECONCILED | Transaction reconciled |
CANCELLATION | INITIATED | CANCELLATION_INITIATED | Initiated transaction cancellation |
CANCELLATION | IN_PROGRESS | CANCELLATION_REQUEST_CREATED | Cancellation request created with payout partner |
IN_PROGRESS | CANCELLATION_REQUEST_CONFIRMED | Cancellation request confirmed by the payout partner | |
REJECTED | CANCELLATION_REQUEST_REJECTED | Cancellation request is rejected by the payout partner | |
ACCEPTED | CANCELLATION_ACCEPTED | Cancellation of transaction accepted | |
COMPLETED | CANCELLATION_COMPLETED | Cancellation of transaction completed |
...
“AVAILABLE_PAID” Sub-State comes for receive mode CASHPICKUP; it means either the amount is ready to be picked up by the beneficiary or already picked up.
General Error Codes
Error | HTTP status code | Error Code | Message | Reason |
---|---|---|---|---|
INVALID_PAYLOAD | 100 | 10000 | "Invalid payload" | The payload passed in the request is invalid |
BAD_REQUEST | 400 | 40000 | "Bad Request" / Payload parameter is missing or corrupt | The request is not correct or is missing required elements like headers parameters etc. |
UNAUTHORIZED | 401 | 40001 | Not authorized/access denied | Not authorized/access denied |
NOT_FOUND | 404 | 40004 | Not found | Data’s or Configurations or Rules are not found |
METHOD_NOT_ALLOWED | 405 | 40005 | "Method not allowed" | The HTTP method used in the request isn't allowed for that activity. |
UNPROCESSABLE CONTENT / ENTITY | 422 | 8076000 | Service disruption during processing request or processor flow | Service disruption during processing request or processor flow |
INTERNAL_SERVICE_ERROR | 500 | 50000 | Unable to service your request at this moment. Kindly retry after sometime | Unable to service your request at this moment. Kindly retry after sometime |
GATEWAY_TIMEOUT | 504 | 50004 | Unable to service your request at this moment. Kindly retry after sometime | Unable to service your request at this moment. Kindly retry after sometime |
Business Error Codes
API | HTTP status code | Error Code | Message | Reason | Reject /Retry |
---|---|---|---|---|---|
Create Quote | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Partner service corridor currencies not found | Partner service corridor currencies not found | ||
404 | 40004 | Bank branch not found | Bank branch not found | ||
404 | 40004 | Partner service corridors not found | Partner service corridors not found | ||
404 | 40004 | Bank not found | Bank not found | ||
404 | 40004 | Quote not found | Quote not found | ||
404 | 40004 | Correspondent service bank not found | Correspondent service bank not found | ||
404 | 40004 | Rates not found | Rates not found | ||
404 | 40004 | Currency not found | Currency not found | ||
404 | 40004 | Charges not found | Charges not found | ||
404 | 40004 | Rebate not found | Rebate not found | ||
404 | 40004 | MTO product not found | MTO product not found | ||
404 | 40004 | Rate / Charges not found | Rate / Charges not found | ||
404 | 40004 | Partner quote or payment expiry limit's not found | Partner quote or payment expiry limit's not found | ||
404 | 40004 | Rate / Charges not found | Rate / Charges not found | ||
Create Transaction | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Sender subscription not found | Sender subscription not found | ||
404 | 40004 | Sender not found | Sender not found | ||
406 | 8076210 | Sender is not acceptable since valid ID not found | Sender is not acceptable since valid ID not found | ||
406 | 8076207 | Transaction is not acceptable since yet to accepted | Transaction is not acceptable since yet to accepted | ||
404 | 40004 | Partner service corridors not found | Partner service corridors not found | ||
404 | 40004 | Partner service corridor currencies not found | Partner service corridor currencies not found | ||
404 | 40004 | Bank branch not found | Bank branch not found | ||
404 | 40004 | Currency not found | Currency not found | ||
406 | 8076205 | Charge's markup/down is not acceptable | Charge's markup/down is not acceptable | ||
404 | 40004 | Partner allowed address type not found | Partner allowed address type not found | ||
406 | 8076209 | Transaction is not acceptable since invalid address type | Transaction is not acceptable since invalid address type | ||
406 | 8076211 | Transaction is not acceptable since exceeded the credit limit | Transaction is not acceptable since exceeded the credit limit | ||
406 | 8076214 | Transaction not acceptable since invalid sender ID information | Transaction not acceptable since invalid sender ID information | ||
406 | 8076201 | Processed transaction for same receiver with same amount | Processed transaction for same receiver with same amount | ||
406 | 8076202 | Transaction is not acceptable since reached sender limit | Transaction is not acceptable since reached sender limit | ||
406 | 8076203 | Transaction not allowed to send amount to same receiver | Transaction not allowed to send amount to same receiver | ||
406 | 8076206 | Transaction is not acceptable since correspondent rate has changed | Transaction is not acceptable since correspondent rate has changed | ||
406 | 8076212 | Quote is not acceptable | Quote is not acceptable | ||
406 | 8076101 | Transaction is not acceptable | Transaction is not acceptable | ||
404 | 40004 | Quote not found | Quote not found | ||
406 | 8076213 | Quote is not acceptable since expired | Quote is not acceptable since expired | ||
400 | 40000 | Mismatch in quote and transaction request | Mismatch in Quote and transaction CorrespondentId | ||
400 | 40000 | Mismatch in quote and transaction request | Mismatch in Quote and transaction CorrLocationId | ||
406 | 8076215 | Transaction is not acceptable since partner transaction reference number already exists | Transaction is not acceptable since partner transaction reference number already exists | ||
406 | 8076208 | Transaction is not acceptable since invalid sender information | Transaction is not acceptable since invalid sender information | ||
Confirm Transaction | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Transaction not found | Transaction not found | ||
406 | 8076306 | Transaction is not acceptable since expired | Transaction is not acceptable since expired | ||
406 | 8076305 | Transaction is not acceptable since already accepted | Transaction is not acceptable since already accepted | ||
404 | 40004 | Transaction sender not found | Transaction sender not found | ||
404 | 40004 | Transaction receiver not found | Transaction receiver not found | ||
404 | 40004 | Partner ledger account not found | Partner ledger account not found | ||
404 | 40004 | Partner call back not found | Partner call back not found | ||
404 | 40004 | Correspondent service bank not found | Correspondent service bank not found | ||
404 | 40004 | Bank branch not found | Bank branch not found | ||
404 | 40004 | Bank not found | Bank not found | ||
404 | 40004 | Purpose of the transaction not found | Purpose of the transaction not found | ||
404 | 40004 | Correspondent service not found | Correspondent service not found | ||
404 | 40004 | Payment mode not found | Payment mode not found | ||
406 | 8076302 | Transaction is not acceptable since clearance not accepted yet | Transaction is not acceptable since clearance not accepted yet | ||
406 | 8076304 | Partner not authorized to generate transaction receipt | Partner not authorized to generate transaction receipt | ||
406 | 8076301 | Transaction is not acceptable since insufficient balance | Transaction is not acceptable since insufficient balance | ||
406 | 8076218 | The correspondent bank details do not match. Please verify the routing configurations and try again | The correspondent bank details do not match. Please verify the routing configurations and try again | ||
Cancel Transaction | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Transaction not found | Transaction not found | ||
406 | 8076403 | Transaction is not acceptable since payment not yet settled | Transaction is not acceptable since payment not yet settled | ||
406 | 8076405 | Cancellation is not acceptable | Cancellation is not acceptable | ||
406 | 8076402 | Cancellation is not acceptable since already in progress | Cancellation is not acceptable since already in progress | ||
406 | 8076401 | Cancellation is not acceptable since already processed | Cancellation is not acceptable since already processed | ||
406 | 8076404 | Cancel reason is not acceptable | Cancel reason is not acceptable | ||
406 | 8076406 | Cancellation is not acceptable since already cancelled | Cancellation is not acceptable since already cancelled | ||
Authorize Transaction | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Transaction not found | Transaction not found | ||
406 | 8076602 | Transaction is not acceptable since external parties not allowed to clearance | Transaction is not acceptable since external parties not allowed to clearance | ||
406 | 8076601 | Transaction is not acceptable since already authorized | Transaction is not acceptable since already authorized | ||
406 | 8076303 | Transaction is not acceptable since awaiting for clearance | Transaction is not acceptable since awaiting for clearance | ||
404 | 40004 | Transaction sender not found | Transaction sender not found | ||
404 | 40004 | Transaction receiver not found | Transaction receiver not found | ||
404 | 40004 | Purpose of the transaction not found | Purpose of the transaction not found | ||
404 | 40004 | Payment mode not found | Payment mode not found | ||
Enquiry Transaction | 404 | 40004 | Partner not found | Partner not found | |
404 | 40004 | Transaction not found | Transaction not found | ||
404 | 40004 | Transaction receiver not found | Transaction receiver not found | ||
404 | 40004 | Transaction sender not found | Transaction sender not found | ||
Update Bank Reference Number | 404 | 40004 | Partner not found | Partner not found | |
400 | 40000 | Payload parameter is missing or corrupt | Payload parameter is missing or corrupt | ||
404 | 40004 | Transaction not found | Transaction not found | ||
406 | 8076207 | Transaction is not acceptable since yet to accepted | Transaction is not acceptable since yet to accepted | ||
406 | 8076603 | Transaction is not acceptable since invalid payload | Transaction is not acceptable since invalid payload | ||
404 | 40004 | Payment mode not found | Payment mode not found | ||
406 | 8076604 | Transaction is not acceptable since BRN update already processed | BRN update already happened | ||
406 | 8076605 | Transaction is not acceptable since Transaction already cancelled | Cancelled transaction | ||
406 | 8076606 | Transaction is not acceptable since bank reference number already exists | Bank reference number is unique for a partner |
Policies
Date-Time Formats
All date time formats in the request and response are based on ISO 8601 format
Date [yyyy-MM-dd]
eg: "1990-08-22"
...
Date-Time in local timezone [yyyy-MM-ddTHH:mm:ss.sssZ] and 24 hour format (00-23)
eg:"2022-02-23T00:08:43.323+04:00"
Amounts
Every currency has its own least currency unit supported and decimals that the currency supports. All the amount formats in the request and response expect and return with the supported decimal rule applied. The rounding of amounts over the least currency unit and the rounding method is applied based on the setup and market standards.
Bank Details
For the receiving mode BANK. The mandatory data in bank details object depends on the receiving country. The bank/branch lookup is supported in three cases by iso_code, routing_code, or sort_code.
Below are the details needed for each receiving country.
...
Country | account_number | IBAN | routing_code | iso_code | sort_code | Comments | Correspondent Validations |
---|---|---|---|---|---|---|---|
BD | Mandatory | Not Required | ACH routing code/Branch code | 11 digit BIC (or) Swift code. | - | Pass either ACH routing code/Branch code (or) iso_code | receiver.first_name (mandatory) should not exceed 40 characters receiver.last_name (mandatory) should not exceed 40 characters DUTCH BANGLA BANK |
EG | Not Required | Mandatory | - | 11 digit BIC (or) Swift code. | - | - | receiver.mobile_number (mandatory) should start with +20 followed by 10 digits receiver.receiver_address.address_line (mandatory) receiver.middle_name (mandatory)
|
ID | Mandatory | Not Required | Not Required | 11 digit BIC (or) Swift code | - | BIC/Swift | receiver.mobile_number (mandatory) receiver.receiver_address.address_line (mandatory) |
IN | Mandatory | Not Required | IFSC code. | 11 digit BIC (or) Swift code. | - | Pass either IFSC code (or) iso_code | receiver.receiver_address.address_line (mandatory) a-z A-Z 0-9, should not exceed 35 characters Receiver.receiver_address.street_name (if passed) a-z A-Z 0-9, should not exceed 35 characters Receiver.receiver_address.town_name (mandatory) a-z A-Z 0-9 State Bank of India a-z A-Z 0-9 |
LK | Mandatory | Not Required | Branch Ref Number/DP Code | 11 digit BIC (or) Swift code. | - | Pass either Branch Ref Num/DP code (or) iso_code | receiver.receiver_address.address_line (mandatory) |
NP | Mandatory | Not Required |
| 11 digit BIC (or) Swift code. |
|
| receiver.first_name (mandatory) should not exceed 40 characters receiver.last_name (mandatory) should not exceed 40 characters receiver.receiver_address.town_name (mandatory) should not exceed 20 characters |
PH | Mandatory | Not Required | ACH routing code | Swift code | - | Pass either ACH routing code (or) swift | receiver.mobile_number (mandatory) receiver.receiver_address.address_line (mandatory) receiver.receiver_address.street_name (if passed) receiver.first_name (mandatory) should not exceed 40 characters receiver.last_name (mandatory) should not exceed 40 characters |
PK | Not Required | Mandatory (Example: PK12ABCD1234567891234567) | Not Required | 11 digit BIC (or) Swift code | - | - | receiver.receiver_address.address_line (mandatory) receiver.nationality (mandatory) Combined length of receiver.first_name, receiver.middle_name, receiver.last_name cannot be more than 100 HABIB BANK LTD receiver.nationality cannot be other than PK |
UK | Not Required | Mandatory | - | 11 digit BIC (or) Swift code | - | Pass IBAN & Swift code | |
Others | Required | Required | - | 11 digit BIC (or) Swift code | - | Pass either account_number or IBAN |
|
Request Header
Every partner should send X-REQUEST-ID in the header to track a particular request.
...
X-REQUEST-ID max is 60 characters.
API Response Time
Access & Privileges
No | API Name | Description | Max Time (MS..) | Avg Time (MS..) |
---|---|---|---|---|
1 | Access Token | API to be used to get API access tokens from DPS identity & security engine | 1000 | 400 |
Transaction APIs
No | API Name | Description | Max Time (MS..) | Avg Time (MS..) |
---|---|---|---|---|
1 | Create Quote | API to be used to create a quote | 60000 | 700 |
2 | Create Transaction | API to be used to accept quote and validate the transaction | 60000 | 350 |
3 | Confirm Transaction | API to be used to execute the transaction for last mile | 30000 | 100 |
4 | Enquire Transaction | API to be used to enquire transaction | 30000 | 200 |
Reference APIs
No | API Name | Description | Max Time (MS..) | Avg Time (MS..) |
---|---|---|---|---|
1 | Get Codes | API to be used to get the master data which will be supplied to other APIs | 30000 | 300 |
2 | Get Service Corridor | API to be used to get the service details, corridor details, currency details | 30000 | 100 |
3 | Get Rates | API to be used to get the exchange rates between the sending country and all its possible receive countries. | 60000 | 100 |
4 | Bank Master | API to be used to get the banks for a particular country | 60000 | 300 |
5 | Branch Master | API to be used to get the branch details for a particular bank | 60000 | 1500 |