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 History:
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 |
CLASSIFICATION: PUBLIC
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.
Connections to be over HTTPS with minimum TLS 1.2
The connecting application and servers to be whitelisted (IP, Domain, etc)
The connecting application should get authenticated and get access tokens using the credentials provided by the payment processor for accessing any API or application
The connecting application should periodically plan and published payment processor with its traffic and quota expected
The connecting application should refrain from any unwanted or repetitive calls that are prone to get the account to go to lock state
Access Token API
Get Token API to be used to get API access tokens from DPS identity & security engine using the credential provided to the sending institute by the payment processor. An access token is a key to the gateway to access any other API. The API will return the access token if the user is successfully authenticated and have the authorization to access these services. Every access token is tagged with validity and the expiry duration is echoed in the response for the calling application to manage the state accordingly. Token if used after its validity period restrict access to any services and a new token to be generated in this case.
API | /auth/realms/cdp/protocol/openid-connect/token |
Method | POST |
Headers | Content-Type : application/x-www-form-urlencoded |
Payload | --data-urlencode 'grant_type=password' \ --data-urlencode 'client_id=<<client_id>>' \ --data-urlencode 'client_secret=<<secret>>' \ --data-urlencode 'username=<<username>>' \ --data-urlencode 'password=<<password>>' |
Response | { "access_token": "<<access_token_value>>", "expires_in": 900, "refresh_expires_in": 1800, "refresh_token": "<<refresh_token_value>>", "token_type": "Bearer", "not-before-policy": 0, "session_state": "-----", "scope": "-----" } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/x-www-form-urlencoded |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
grant_type | String | 10 | Yes | Grant type. Will up provided |
scope | String | 60 | Yes | Scope name. Will be provided |
client_id | String | 60 | Yes | Client Id. Will be provided |
client_secret | String | 60 | Yes | Client secret. Will be provided |
username | String | 60 | Yes | Admin user name |
password | String | 60 | Yes | Admin password |
Response
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.
Create Quote API is to create and lock the exchange rate and fee for a payment transaction. This API expects details of the payment order like send-to-receive currency pair & its countries, amount wished to send or amount wished to be received by the beneficiary, and the mode of receipt of the payment. This API responds with the exchange rate for the currency pair, fee for processing the transaction, tax (if applicable) with the send or receive amounts calculated. The response also contains an identifier for the Quote received “Quote ID“ which can be used for subsequent API calls to instruct the system to refer to previously reserved quotes. Every quote comes with an expiry timestamp which is invalid if used after this period. The price guarantee identifier denotes if the quote is just indicative or reserved.
Create Transaction API is to create a payment order. This API expects sender details, sender source of the fund, receiver/beneficiary details, receiving mode & purpose, receiving institute, and reference to Quote (Quote ID from the previous message). On the receipt of details in this API, the data is validated against the payload structure & datatype definition, quote validity, agent fund availability, corridor & delivery mode wise mandates, and is also screened through the world-check’s watchlist data in the designated system. If there is no immediate rejection or failure on the above checks & balances, a transfer reference number is generated and stored.
If the sending institute agreed to the agency model (white-labelled model), customer registration is a pre-requisite and the create transaction API message can just carry the customer registration number within the sender block.
If the sending institute agreed to the payment services model, the customer registration is not mandated and for the create transaction API, it should carry the detailed sender information.
If the agent is agreed with a quote outside this model, then the quote object is also expected with this message.
This API returns failure if any validation or balance check fails.
Confirm Transaction API is the payment order authorization API from the sending institute to the processing institute. When the sending institute invokes this API, the payment processor passes this message through the AML screening & monitoring checks in the designated systems. On the successful AML checks, the payment order is then taken by the payment processor to the correspondent partners and subsequently, the value of the transaction is deducted against the balance of the agent held in the system.
Enquiry API can be used by the sending institute to pool the transaction status for any progress on its status on a periodic interval.
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.
API | /api/v1_0/ras/quote |
Authorization | Bearer Token |
Method | Post |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Payload (Bank Transfer) | { "sending_country_code": "AE", "sending_currency_code": "AED", "receiving_country_code": "PK", "receiving_currency_code": "PKR", "sending_amount": 100, "receiving_mode": "BANK", "type": "SEND", "instrument": "REMITTANCE" } |
Payload (Bank Transfer with Bank details For Pakistan) | { "sending_country_code": "AE", "sending_currency_code": "AED", "receiving_country_code": "PK", "receiving_currency_code": "PKR", "sending_amount": 100, "receiving_mode": "BANK", "iso_code": "ALFHPKKA068", "type": "SEND", "instrument": "REMITTANCE" } |
Payload (Bank Transfer with Bank details For India) | { "sending_country_code": "AE", "sending_currency_code": "AED", "receiving_country_code": "PK", "receiving_currency_code": "PKR", "sending_amount": 100, "receiving_mode": "BANK", "routing_code": "FDRL0001883", "iso_code": "ALFHPKKA068", "type": "SEND", "instrument": "REMITTANCE" } |
Payload (Cash Pick up) | { "sending_country_code": "OM", "sending_currency_code": "OMR", "receiving_country_code": "IN", "receiving_currency_code": "INR", "sending_amount": 101, "receiving_mode": "CASHPICKUP", "type": "SEND", "instrument": "REMITTANCE", "correspondent": "RR", "correspondent_id": "INOPCP", "correspondent_location_id": "OP" }
|
Payload (MTO Mobile Cash) | { "sending_country_code": "AE", "sending_currency_code": "AED", "receiving_country_code": "IN", "receiving_currency_code": "INR", "sending_amount": 101, "receiving_mode": "MOBILECASH", "type": "SEND", "instrument": "REMITTANCE", "correspondent": "RR", "correspondent_id": "INOPCP", "correspondent_location_id": "OP" } |
Payload (Mobile Wallet) | { "sending_country_code": "AE", "sending_currency_code": "AED", "receiving_country_code": "EG", "receiving_currency_code": "EGP", "sending_amount": 101, "receiving_mode": "MOBILEWALLET", "type": "SEND", "instrument": "REMITTANCE", "correspondent": "LR", } |
Response | { "status": "success", "status_code": 200, "data": { "quote_id": "1279123122023835", "created_at": "2023-08-08T09:23:31.152+04:00", "created_at_gmt": "2023-08-08T05:23:31.152Z", "expires_at": "2023-08-08T09:53:31.152+04:00", "expires_at_gmt": "2023-08-08T05:53:31.152Z", "receiving_country_code": "PK", "receiving_currency_code": "PKR", "sending_country_code": "AE", "sending_currency_code": "AED", "sending_amount": 100, "receiving_amount": 7576.39, "total_payin_amount": 107.35, "fx_rates": [ { "rate": 75.76388942, "base_currency_code": "AED", "counter_currency_code": "PKR", "type": "SELL" }, { "rate": 0.0131989, "base_currency_code": "PKR", "counter_currency_code": "AED", "type": "SELL" }, { "rate": 3.673, "base_currency_code": "USD", "counter_currency_code": "AED", "type": "SELL" }, { "rate": 282.83, "base_currency_code": "USD", "counter_currency_code": "PKR", "type": "SELL" } ], "fee_details": [ { "type": "COMMISSION", "model": "OUR", "currency_code": "AED", "amount": 7, "description": "Commission" }, { "type": "TAX", "model": "OUR", "currency_code": "AED", "amount": 0.35, "description": "Tax" } ], "settlement_details": [ { "charge_type": "COMMISSION", "value": 2.8, "currency_code": "AED" }, { "charge_type": "TREASURYMARGIN", "value": 0.008, "currency_code": "AED" }, { "charge_type": "INPUTTAX", "value": 0.14, "currency_code": "AED" } ], "correspondent_rules": [ { "field": "purpose_of_txn", "rule": "it is mandatory" }, { "field": "receive_amount", "rule": "cannot be null" }, { "field": "receiving_currency_code", "rule": "it is mandatory" }, { "field": "receiver.bank_details.account_number", "rule": "it is mandatory" }, { "field": "receiver.first_name", "rule": "it is mandatory and should consists of alphabets and not exceed 60 characters" }, { "field": "receiver.last_name", "rule": "it is mandatory and should consists of alphabets and not exceed 60 characters" }, { "field": "receiver.mobile_number", "rule": "it is mandatory and should start with +20 followed by 10 digits" }, { "field": "sender.first_name", "rule": "it is mandatory and should consists of alphabets and not exceed 60 characters" }, { "field": "sender.last_name", "rule": "it is mandatory and should consists of alphabets and not exceed 60 characters" }, { "field": "sender.sender_id.id", "rule": "it is mandatory and should not exceed 50 characters" }, { "field": "transaction.quote_id", "rule": "it is mandatory" }, { "field": "receiving_mode", "rule": "cannot be null" } ], "price_guarantee": "FIRM" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
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 | - | Conditional | Amount in Send currency. (When sending amount is passed, then receive amount is No) |
receiving_amount | BigDecimal | - | No | Amount in Receive currency. (If both sending and receiving amount passed, then will consider sending amount.) |
receiving_mode | String | 20 | Yes | Receive mode / delivery mode. Example: Bank Account credit, Cash Pickup. |
iso_code | String | 11 | No | Bank ISO code |
routing_code | String | 34 | No | Routing code. For India, it is IFSC code |
type | String | - | Yes | SEND or RECEIVE |
instrument | String | 60 | Yes | Specify the instrument type like Remittance, Bill Payment |
payment_mode | String | 2 | Conditional | It is mandatory when payment is collected by Lulu |
correspondent | String | 2 | Conditional | Correspondent name. It is mandatory for Cash Payout |
correspondent_id | String | 100 | Conditional | Correspondent ID. It is mandatory for Cash Payout |
correspondent_location_id | String | 100 | Conditional | Correspondent location ID. It is mandatory for Cash Payout |
service_type | String | 3 | Mandatory | C2C, C2B Default: C2C |
Response
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.
API | /api/v1_0/ras/createtransaction | |
Authorization | Bearer Token | |
Method | POST | |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> | |
Payload (Bank transfer) | { "type": "SEND", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "instrument": "REMITTANCE", "message": "Agency transaction", "sender": { "customer_number": "1000001220000001" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "last_name": "Anija Lastname", "middle_name": " ", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "street_name": "TCRTESTESTETSTETSTDTST", "building_number": "JIJIJJ", "post_code": "9054", "pobox": "658595", "town_name": "THRISSUR", "country_subdivision": "KOKOKOKOKK", "country_code": "PK" } ], "receiver_id": [], "nationality": "PK", "relation_code": "32", "bank_details": { "account_type_code": "1", "account_number": "67095294579", "iso_code": "ALFHPKKA068", "iban" : "PK36ALFH67095294579" } }, "transaction": { "quote_id": "{{quote_id}}" } } | |
Payload (Cash Pickup) | { "type": "SEND", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "instrument": "REMITTANCE", "message": "Agency transaction", "sender": { "customer_number": "1000001220000001" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "last_name": "Anija Lastname", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "town_name": "THRISSUR", "country_code": "IN" } ], "nationality": "IN", "relation_code": "32" }, "transaction": { "quote_id": "{{quote_id}}" } } | |
Payload (MTO Mobile Cash) | { "type": "SEND", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "instrument": "REMITTANCE", "message": "Agency transaction", "sender": { "customer_number": "1000001220000001" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "last_name": "Anija Lastname", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "town_name": "THRISSUR", "country_code": "IN" } ], "nationality": "IN", "relation_code": "32" }, "transaction": { "quote_id": "{{quote_id}}" } } | |
Payload (Mobile Wallet) | { "type": "SEND", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "instrument": "REMITTANCE", "message": "Agency transaction", "sender": { "customer_number": "1000001220000001" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "last_name": "Anija Lastname", "middle_name": " ", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "street_name": "TCRTESTESTETSTETSTDTST", "building_number": "JIJIJJ", "post_code": "9054", "pobox": "658595", "town_name": "THRISSUR", "country_subdivision": "KOKOKOKOKK", "country_code": "PK" } ], "receiver_id": [], "nationality": "PK", "relation_code": "32", "mobileWallet_details": { "iso_code": "BMISEGCXXXX", "wallet_id": "95867415081", } }, "transaction": { "quote_id": "{{quote_id}}" } } | |
Payload (Bank transfer) - MarkUp/MarkDown | { "type": "SEND", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "instrument": "REMITTANCE", "message": "Agency transaction", "sender": { "customer_number": "7841001220007002" }, "receiver": { "agent_receiver_number":"123456789", "mobile_number": "+919586741508", "first_name": "Anija FirstName", "last_name": "Anija Lastname", "bank_details": { "account_type_code": "1", "iso_code": "ALFHPKKA021", "iban": "PK12ABCD1234567891234567" } }, "transaction": { "quote_id": "{{quote_id}}", "fx_rates": [ { "rate": 70.19313243, "base_currency_code": "AED", "counter_currency_code": "PKR", "type": "SELL" } ], "fee_details": [ { "type": "COMMISSION", "currency_code": "AED", "amount": 11, "description": "commission" } ] } } | |
Response | { "status": "success", "status_code": 200, "data": { "transaction_ref_number": "1276122106615570", "transaction_date": "2022-03-04T09:06:25.045+04:00", "transaction_gmt_date": "2022-03-04T05:06:25.045Z", "expires_at": "2022-03-04T11:06:25.045+04:00", "expires_at_gmt": "2022-03-04T07:06:25.045Z" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
type | String | - | Yes | SEND or 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 |
service_type | String | 3 | Yes | C2C, C2B Default: C2C |
sender | Object | - | Yes | Sender object |
agent_customer_number | String | 60 | No | Agent stored customer id |
customer_number | String | 16 | Yes | Lulu customer number |
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 | Conditional | Receiver first name Mandatory if service type = C2C |
last_name | String | 60 | Conditional | Receiver last name Mandatory if service type = C2C |
middle_name | String | 60 | No | Receiver middle name |
date_of_birth | Date | - | No | YYYY-MM-DD format |
gender | String | 1 | No | Receiver gender name |
nationality | String | 2 | Conditional | Receiver nationality code; ISO 2 Char country code |
relation_code | String | - | Yes | Relation type like Friend, Brother |
name | String | 120 | Conditional | Receiver name Mandatory if service type = C2B |
type_of_business | String | 20 | Optional | Master data available in Codes API |
receiver_address | List | 1 | Conditional |
|
address_type | String | 20 | Yes | Receiver address type like Present, Permanent |
address_line | String | 70 | Conditional | Receiver address line |
street_name | String | 70 | Conditional | Receiver street name |
building_number | String | 16 | Conditional | Receiver building number |
post_code | String | 16 | No | Receiver postal area code. Example: Zipcode, Pincode |
pobox | String | 12 | No | Receiver post box number |
town_name | String | 35 | Conditional | Receiver town name |
country_subdivision | String | 35 | Conditional | Receiver country sub division |
country_code | String | 2 | Yes | Receiver country code; ISO 2 Char country code |
receiver_id | List | 1 | Conditional |
|
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 | Conditional | Receiver bank account number. Non Mandatory for IBAN countries |
iso_code | String | 11 | Yes | Receiver bank ISO code |
bank_id | String | 6 | No | Receiver bank id (Lulu bank id) |
branch_id | String | 6 | No | Receiver bank branch id (Lulu bank branch id) |
iban | String | 34 | Conditional | Mandatory for IBAN countries |
routing_code | String | 34 | Conditional | Mandatory for non IBAN/Swift/BIC countries |
sort_code | String | 13 | Conditional |
|
mobileWallet_details | Object | - | Conditional | Mandatory for Wallet transfer |
wallet_id | String | 16 | yes | Receiver Wallet Id |
iso_code | String | 11 | Yes | Receiver bank ISO code |
bank_id | String | 6 | No | Receiver bank id (Lulu bank id) |
branch_id | String | 6 | No | Receiver bank branch id (Lulu bank branch id) |
iban | String | 34 | Conditional | Mandatory for IBAN countries |
routing_code | String | 34 | Conditional | Mandatory for non IBAN/Swift/BIC countries |
sort_code | String | 13 | Conditional | |
transaction | Object | - | Yes |
|
quote_id | String | 16 | Conditional | Mandatory when transaction details are not passed |
agent_transaction_ref_number | String | 60 | No | Agents unique transaction reference number |
receiving_mode | String | 20 | No | Receive mode / delivery mode. Example: BANK, CASHPICKUP. |
sending_country_code | String | 2 | No | Send country; ISO 2 Char country code |
sending_currency_code | String | 3 | No | Send currency; ISO 3 Char currency code |
receiving_country_code | String | 2 | Conditional | Beneficiary receive country; ISO 2 Char country code |
receiving_currency_code | String | 3 | Conditional | Beneficiary receive currency; ISO 3 Char currency code |
sending_amount | BigDecimal | - | No | Amount in Send currency. (When sending amount is passed, then receive amount is No) |
receiving_amount | BigDecimal | - | Conditional | Amount in Receive currency. (If both sending and receiving amount passed, then will consider sending amount.) |
payment_mode | String | 2 | Conditional | It is mandatory when payment is collected by Lulu |
fx_rates | List | - | No |
|
rate | BigDecimal | (15,8) | Yes | customer transaction 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 | - | No |
|
type | String | - | Yes | fee type like COMMISSION |
currency_code | String | 3 | Yes | fee Currency code; ISO 3 Char currency code depending on the model |
amount | BigDecimal | - | Yes | fee amount |
description | String | 60 | Yes | Description of the fee |
ordering_institution | Object |
| No |
|
name | String | 60 | Conditional | Ordering institution name |
institution_address | Object |
| No |
|
address_type | String | 20 | No | address type like Present, Permanent |
address_line | String | 70 | No | address line |
street_name | String | 70 | No | street name |
building_number | String | 16 | No | building number |
post_code | String | 16 | No | postal area code. Example: Zipcode, Pincode |
pobox | String | 12 | No | post box number |
town_name | String | 35 | Conditional | town name |
country_subdivision | String | 35 | No | country sub division |
country_code | String | 2 | Conditional | country code; ISO 2 Char country code |
Response
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.
API | /api/v1_0/ras/confirmtransaction |
Authorization | Bearer Token |
Method | Post |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Payload | { "transaction_ref_number": "1276122106256978", "bank_ref_number": "1230118129780478", "customer_bank_name": "FEDERAL BANK LTD", "deposit_account_id": "12432123123534" } |
Response | { "status": "success", "status_code": 200, "data": { "state": "IN_PROGRESS", "sub_state": "PAYMENT_SETTLED", "transaction_ref_number": "1276122106256978" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
bank_ref_number | String | 16 | Conditional | Bank reference number. Mandatory if payment collected by D9PS |
customer_bank_name | String | 60 | No | bank name |
deposit_account_id | String | 18 | No | deposit account id |
Response
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.
API | /api/v1_0/ras/authorize-clearance |
Authorization | Bearer Token |
Method | Post |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> Authorization: <<token>> |
Payload | { "transaction_ref_number": "5714122126296994", } |
Response | { "status": "success", "status_code": 200, "data": { "state": "IN_PROGRESS", "sub_state": "CLEARANCE_ACCEPTED", "transaction_ref_number": "5714122126296994" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
Response
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.
API | /api/v1_0/ras/enquire-transaction?transaction_ref_number=<<reference_no>> |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Param | None |
Response (Bank Transfer) | { "status": "success", "status_code": 200, "data": { "state": "IN_PROGRESS", "sub_state": "AML_PENDING", "transaction_gmt_date": "2022-03-23T09:18:42.73Z", "transaction_date": "2022-03-23T13:18:42.73+04:00", "type": "SEND", "instrument": "REMITTANCE", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "message": "Agency transaction", "sender": { "mobile_number": "+971523236963", "customer_number": "1000001220000001", "email": "liyas@one.com", "first_name": "MANU", "last_name": "GARCIA", "date_of_birth": "1973-07-12", "country_of_birth": " ", "gender": "M", "nationality": "PH", "profession_code": "550", "employer": "LULU", "visa_type_Code": "101" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "middle_name": " ", "last_name": "Anija Lastname", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "street_name": "TCRTESTESTETSTETSTDTST", "building_number": "JIJIJJ", "post_code": "9054", "pobox": "658595", "town_name": "THRISSUR", "country_subdivision": "KOKOKOKOKK", "country_code": "PK" } ], "nationality": "PK", "relation_code": "32", "bank_details": { "account_type": "1", "account_num": "67095294579", "iso_code": "ALFHPKKA068", "bank_id": "11232", "branch_id": "184377", "iban": "PK36ALFH67095294579" } }, "transaction": { "quote_id": "1276122108299334", "receiving_mode": "BANK", "payment_mode": "", "sending_country_code": "AE", "receiving_country_code": "PK", "sending_currency_code": "AED", "receiving_currency_code": "PKR", "sending_amount": 100, "receiving_amount": 4144.75, "total_payin_amount": 107.35, "fx_rates": [ { "rate": 41.44832037, "base_currency_code": "AED", "counter_currency_code": "PKR", "type": "SELL" }, { "rate": 0.02412643, "base_currency_code": "PKR", "counter_currency_code": "AED", "type": "SELL" } ], "fee_details": [ { "type": "COMMISSION", "model": "OUR", "amount": 7, "description": "Commission", "currency_code": "AED" }, { "type": "TAX", "model": "OUR", "amount": 0.35, "description": "Tax", "currency_code": "AED" } ], "settlement_details": [ { "charge_type": "COMMISSION", "value": 0, "currency_code": "AED" }, { "charge_type": "TREASURYMARGIN", "value": 0, "currency_code": "AED" }, { "charge_type": "INPUTTAX", "value": 0.0, "currency_code": "AED" } ] } } } |
Response (Cash Pickup) | { "status": "success", "status_code": 200, "data": { "state": "IN_PROGRESS", "sub_state": "AML_PENDING", "transaction_gmt_date": "2022-03-23T09:18:42.73Z", "transaction_date": "2022-03-23T13:18:42.73+04:00", "type": "SEND", "instrument": "REMITTANCE", "source_of_income": "SLRY", "purpose_of_txn": "SAVG", "message": "Agency transaction", "sender": { "mobile_number": "+971523236963", "customer_number": "1000001220000001", "email": "liyas@one.com", "first_name": "MANU", "last_name": "GARCIA", "date_of_birth": "1973-07-12", "country_of_birth": " ", "gender": "M", "nationality": "PH", "profession_code": "550", "employer": "LULU", "visa_type_Code": "101" }, "receiver": { "mobile_number": "+919586741508", "first_name": "Anija FirstName", "middle_name": " ", "last_name": "Anija Lastname", "date_of_birth": "1990-08-22", "gender": "F", "receiver_address": [ { "address_type": "PRESENT", "address_line": "TCR", "street_name": "TCRTESTESTETSTETSTDTST", "building_number": "JIJIJJ", "post_code": "9054", "pobox": "658595", "town_name": "THRISSUR", "country_subdivision": "KOKOKOKOKK", "country_code": "PK" } ], "nationality": "PK", "relation_code": "32", "cashpickup_details": { "correspondent": "RR", "correspondent_id": "INOPCP", "correspondent_location_id": "OP" } }, "transaction": { "quote_id": "1276122108299334", "receiving_mode": "CASHPICKUP", "payment_mode": "", "sending_country_code": "AE", "receiving_country_code": "PK", "sending_currency_code": "AED", "receiving_currency_code": "PKR", "sending_amount": 100, "receiving_amount": 4144.75, "total_payin_amount": 107.35, "fx_rates": [ { "rate": 41.44832037, "base_currency_code": "AED", "counter_currency_code": "PKR", "type": "SELL" }, { "rate": 0.02412643, "base_currency_code": "PKR", "counter_currency_code": "AED", "type": "SELL" } ], "fee_details": [ { "type": "COMMISSION", "model": "OUR", "amount": 7, "description": "Commission", "currency_code": "AED" }, { "type": "TAX", "model": "OUR", "amount": 0.35, "description": "Tax", "currency_code": "AED" } ] } } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
Response
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.
API | /api/v1_0/ras/brn-update |
Authorization | Bearer Token |
Method | Post |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Payload | { "transaction_ref_number": "1276122106256978", "bank_ref_number": "1230118129780478", "customer_bank_name": "FEDERAL BANK LTD", "deposit_account_id": "12432123123534", "payment_initiated": "initiated", "customer_name": "TEST_CUSTOMER", "payment_id": "PAYMENT003", "amount": "50", "match_type": "MATCH", "is_reconciled": "TRUE" } |
Response | { "status": "success", "status_code": 200, "data": { "state": "IN_PROGRESS", "sub_state": "PAYMENT_AWAIT_CLEARANCE" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
bank_ref_number | String | 16 | Yes | Bank reference number |
customer_bank_name | String | 60 | No | bank name |
deposit_account_id | String | 18 | No | deposit account id |
payment_initiated | String |
| Conditional |
|
customer_name | String |
| Conditional | customer name |
payment_id | String | 60 | Conditional | payment id |
amount | BigDecimal | (15,8) | Conditional | Amount |
match_type | String |
| Conditional | MATCH, UNMATCH, PARTIAL |
is_reconciled | String |
| Yes | TRUE/FALSE |
Response
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.
API | /api/v1_0/ras/canceltransaction |
Authorization | Bearer Token |
Method | Post |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Payload | { "transaction_ref_number": "1276122106256978", "cancel_reason" : "R7", "remarks":"Incorrect Recipient" } |
Response (Success) | { |
Response (When payment is not settled yet) | { |
Response (When AML is pending) | { |
Response (Cancellation in progress) | { |
Response (Transaction is Credited,Reconciled or Cancellation is completed) | { |
Response (Invalid cancel reason code passed)
| { |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
cancel_reason | String | 60 | Yes | Get this ENUM values from Get codes API by key : cancel_reason_codes_list |
remarks | String | 40 | Yes | Additional message |
Response
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.
API | /api/v1_0/ras/transaction-receipt?transaction_ref_number=<<reference_no>> |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Param | transaction_ref_number |
Response | { "status": "success", "status_code": 200, "data": { */ Base64 data*/ } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
Response
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.
API | /api/v1_0/paas/status-update |
Authorization | Bearer Token |
Method | PUT |
Headers | Content-Type:application/json sender : <<sender_name>> company: <<company_code>> branch: <<branch_code>> |
Payload | { "transaction_ref_number": 1276122106256978, "status": "CREDITED" } |
Response | { "status": "success", "status_code": 200, "data": { "status": "ACKNOWLEDGED" } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
sender | String | 60 | Yes | Agent / Partner name. |
channel | String | 30 | Yes | Ripple / Direct |
company | String | 6 | Yes | Will be shared |
branch | String | 6 | Yes | Will be shared |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
status | String | 60 | Yes | Transaction status to be updated.
|
Response
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:
SHA512-hashOf({"transaction_ref_number":"5712122130661730","state":"COMPLETED","sub_state":"CREDITED"}<<secret>>)
Then attach value in the header “hash”. When receiving a callback Partner will compute the hash with the incoming request payload and secret then compare with the value in the header. The request should be considered valid only if both values match.
IP to be whitelist 20.207.110.226 from partner end.
API | <<PARTNER_ENDPOINT_WITH_CONTEXT>> |
Authorization | IP Whitelisting |
Method | Post |
Headers | Content-Type:application/json hash:<<hash value>> |
Payload | { "transaction_ref_number": "5712122130661730", "state": "COMPLETED", "sub_state": "CREDITED", } |
Response | { "state": "ACKNOWLEDGED" } |
Header
Name | Data Type | Max Length | Mandatory | Description |
hash | String | 128 | No | SHA512 hash in hexadecimal |
Payload
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
transaction_ref_number | String | 16 | Yes | Transaction reference number. Unique number to identify the transaction. |
state | String | 60 | Yes | Status code |
sub_state | String | 120 | Yes | Sub state code |
Response
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
state | String | - | Yes | State value should always be “ACKNOWLEDGED”. |
How Retry Works:
Max Retry Count : 4
Retry | Interval(mins) |
1 | 5 |
2 | 10 |
3 | 60 |
4 | 60 |
If partner shared API gives response like,
Timeout: if API call receives timeout or other than http status (200 OK) then activates the retry mechanism.
Once reached maximum retry count for the specific transaction substate, push will be stopped against transaction substate. Always get the latest information from transaction enquiry API.
NOT ACKNOWLEDGED but received SUCCESS (200 OK): No retry will happen such transaction status.
Those transactions status push will not be processed anymore, get the latest information from transaction enquiry API.
Reference 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.
Code type: RELATIONSHIPS,PURPOSE_OF_TRANSACTIONS, PROFESSIONS, ACCOUNT_TYPES, PAYMENT_MODES, VISA_TYPES, INSTRUMENTS, RECEIVING_MODES, FEE_TYPES, ADDRESS_TYPES, TRANSACTION_STATES, INCOME_TYPES, INCOME_RANGE_TYPES, WIRE_BANKS, TXN_COUNT_MONTHS, TXN_VOLUME_MONTHS, CORRESPONDENTS, CANCEL_REASON_CODES,SOURCE_OF_INCOMES, DOCUMENT_TYPES, PROOF_CONTENT_TYPES, BUSINESS_TYPES
API | /raas/masters/v1/codes?code=<type> |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Request Param | code : PURPOSE_OF_TRANSACTIONS service_type : C2C |
Response | { "status": "success", "status_code": 200, "data": { "purposes_of_transactions": [ { "code": "FAMA", "name": "Family Maintenance" }, { "code": "MDCS", "name": "Medical expenses" }, { "code": "LOAR", "name": "REPAYMENT OF LOAN" }, { "code": "SAVG", "name": "Savings" } ] } } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
Content-Type | String | 36 | Yes | application/json |
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
code | String | 60 | No | Eg : INCOME_TYPES |
Payload
None
Response
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.
API | /raas/masters/v1/service-corridor |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | None |
Request param | receiving_mode : <<receiving_mode>> receiving_country_code : <<receiving_country_code>> |
Response | { "status": "success", "status_code": 200, "data": [ { "instrument": "REMITTANCE", "transaction_type": "SEND", "receiving_mode": "BANK", "sending_country": "UNITED ARAB EMIRATES", "sending_country_code": "AE", "receiving_country": "Philippines", "receiving_country_code": "PH", "limit_currency": "Philippine Peso", "limit_currency_code": "PHP", "limit_min_amount": 1, "limit_per_transaction": 4600000, "send_min_amount": 50, "send_max_amount": 300000, "corridor_currencies": [ { "correspondent": "LR", "anywhere": 0, "sending_currency": "UAE Dirham", "sending_currency_code": "AED", "receiving_currency": "Philippine Peso", "receiving_currency_code": "PHP", "correspondent_name": "LuluRemittance" } ] } ] } |
Header
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
sender | String | 60 | No | Agent / Partner name. |
channel | String | 30 | No | Ripple / Direct |
company | String | 6 | No | Will be shared |
branch | String | 6 | No | Will be shared |
Payload
None
Request param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
receiving_mode | String | - | No | Default value is BANK Eg : BANK / CASHPICKUP |
receiving_country_code | String | 2 | No | Country code in iso format Eg : IN |
Response
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.
API | /raas/masters/v1/banks |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type : application/json |
Request param | page : <<page no>> size : <<size of page>> bank_name:<<bank_name>> |
Response | { "status": "success", "status_code": 200, "data": { "records": 100, "list": [ { "bank_id": "10098", "bank_name": "ERNAKUILAM DIST CO OPERATIVE BANK" } ], "total_records": 1, "total_page": 1, "current_page": 1 } }
|
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
receiving_country_code | String | 2 | Yes | Country code in iso format Eg : IN |
correspondent | String | 2 | No | Default value is LR, value based on the correspondent Eg : LR ,RR etc. |
receiving_mode | String | - | No | Default value is BANK Eg : BANK ,CASHPICKUP |
bank_id | String | - | Optional | bank_id is a optional parameter in this API.If bank_id pass the response will be based on this bank_id |
page | Integer | - | No | If the API consumer wants a the result paginated, they can use the Page parameter to specify the page Number of the paginated result Eg : 1 |
size | Integer | 5000 | No | If the API consumer wants a the result paginated, they can use the Size parameter to specify the size (number of rows) of each page of the paginated result. Eg : 10 |
bank_name | String | 120 | No | bank_name is a optional parameter in this API. if a Bank Name is passed the response will contains the list of Banks which contains the word/words. Eg : BANK OF |
Response
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.
API | /raas/masters/v1/banks/{bank_id} |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type : application/json |
Request Param | correspondent : <<correspondent >> |
Response | { "status": "success", "status_code": 200, "data": { "bank_id": "10011", "bank_name": "HDFC BANK", "bank_country_code": "IN", "bank_account_number_length": "14,15,16", "bank_address": " " } }
|
URL Path Params
Name | Data Type | Mandatory | Description | Sample Value |
---|---|---|---|---|
bank_id | String | Yes | ID of the bank | 14223 |
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
correspondent | String | 2 | No | Default value is LR, value based on the correspondent Eg : LR, RR etc. |
Response
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.
API | /raas/masters/v1/banks/{bank_id}/branches |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | none |
Request Params | page : <<page>> branch_name_part : <<branch_name_part>> |
Response | { "status": "success", "status_code": 200, "data": { "records": 5, "list": [ { "bank_id": "10011", "branch_id": "499733", "branch_name": "ITWARI", "routing_code": "HDFC0004034", "iso_code": "HDFCINBBXXX", "sort": " ", "bank_name":"", "bank_branch_name":"", "ifsc":"", "bic":"", "address":"", "town_name":"", "country_subdivision":"", "country_code":"" } ], "total_records": 1, "total_page": 1, "current_page": 1 } }
|
Header
Request
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
correspondent | String | 60 | Yes | Default value is LR, value based on the correspondent Eg : LR ,RR etc. |
receiving_country_code | String | 30 | Yes | country code |
receiving_mode | String | 6 | Yes | Default value is BANK Eg : BANK ,CASHPICKUP |
branch_id | String | - | Optional | If branch_id pass the result should fully based on this branch_id |
size | Integer | 5000 | Yes | If the API consumer wants a the result paginated, they can use the Page parameter to specify the page Number of the paginated result Eg : 1 |
page | Integer | - | Yes | If the API consumer wants a the result paginated, they can use the Page parameter to specify the page size (number of rows )of the paginated result |
branch_name_part | String | 120 | No | branch_name_part is a optional parameter in this API. if a Branch Name is passed the response will contains the list of Branches of the Bank which contains the word/words. Eg : ROAD BRANCH |
Payload
none
Response
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
API | /raas/masters/v1/banks/{bank_id}/branches/{branch_id} |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type : application/json |
Request param | correspondent : <<correspondent>> |
Response | { "status": "success", "status_code": 200, "data": { "bank_id": "10011", "branch_id": "6799597", "branch_name": "GOLA ROAD PATNA", "branch_full_name": "GOLA ROAD PATNA, ,HDFC0008115", "address": " ", "country_code": "IN", "routing_code": "HDFC0008115", "bic": " ", "iso_code": " ", "sort": " ", "bank_name":"", "town_name":"", "country_subdivision":"", "ifsc":"" } }
|
URL Path Params
Name | Data Type | Mandatory | Description | Sample Value |
---|---|---|---|---|
bank_id | String | Yes | ID of the bank | 14223 |
branch_id | String | Yes | ID of the bank-branch | 520170 |
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
correspondent | String | - | No | Correspondent default value is LR Sample value : LR |
Response
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
API | /raas/masters/v1/branches/lookup |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | none |
Request Params | page : <<page>> size : <<size>> sort_code : <<sort_code>> routing_code : <<routing_code>> receiving_mode : <<receiving_mode>> receiving_country_code : <<receiving_country_code>> correspondent : <<correspondent>> |
Response | { "status": "success", "status_code": 200, "data": { "records": 2, "list": [ { "bank_id": "11232", "branch_id": "509162", "branch_name": "IB-KHUSHAB", "branch_full_name": "IB-KHUSHAB,KHUSHAB,5549", "address": " ", "town_name": "KHUSHAB", "country_subdivision": "PUNJAB", "country_code": "PK", "routing_code": "5549", "iso_code": "ALFHPKKAXXX", "sort": ".", "bank_name":"", "ifsc":"", "bic":"" }, { "bank_id": "11232", "branch_id": "509985", "branch_name": "IBG GULBAHAR COLONY", "branch_full_name": "IBG GULBAHAR COLONY, ,5596", "address": " MAIN GULBAHAR ROAD", "country_code": "PK", "routing_code": "5596", "iso_code": "ALFHPKKAXXX", "sort": ".", "bank_name":"", "ifsc":"", "bic":"" } ], "total_records": 780, "total_page": 390, "current_page": 1 } }
|
Response(Error case) | { "status": "failure", "status_code": 404, "error_code": 40004, "message": "Bank branch's not found" |
Header
Payload
none
Request Params
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
page | Integer | - | No | If the API consumer wants a the result paginated, they can use the Page parameter to specify the page number of the paginated result Sample value: 1 |
size | Integer | 5000 | No | If the API consumer wants a the result paginated, they can use the Size parameter to specify the size (number of rows) of each page of the paginated result. Sample value : 10 |
correspondent | String | 2 | No | Correspondent Sample value: LR/OR |
receiving_mode | String | - | No | Receiving Mode Sample value: BANK |
iso_code | String | - | No | ISO coderouting_code |
routing_code | String | - | No | Routing codesort_code |
sort_code | String | 15 | No | Sort code |
receiving_country_code | String | 2 | Yes | Country code in iso format Sample value : IN |
Response
Name | Data Type | Max Length | Mandatory | Description |
---|
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.
API | /raas/masters/v1/accounts/balance |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | None |
Parameter | payment_mode |
Response | { "status": "success", "status_code": 200, "data": [ { "closingBalance": 103151529, "currency": "AED" } ] }
|
Header
Payload
None
Parameter
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
payment_mode | String | 2 | Conditional | AP, BT, LE, CO etc. |
Response
Name | Data Type | Max Length | Mandatory | Description |
---|
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.
API | /raas/masters/v1/rates |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Request Param | correspondent : <<correspondent>> receiving_mode :<<receiving_mode>> include_correspondents : <<include_correspondents>> receiving_country_code : <<receiving_country_code>> receiving_currency_code : <<receiving_currency_code>> service_type : <<service_type>> |
Response | { "status": "success", "status_code": 200, "data": { "rates": [ { "rate": 157.97164409, "to_currency_name": "PHILIPPINE PESO", "to_currency": "PHP", "from_currency": "AED", "to_country_name": "Philippines", "to_country": "PH", "receiving_mode": "BANK" }, { "rate": 80.22623799, "to_currency_name": "PAKISTANI RUPEE", "to_currency": "PKR", "from_currency": "AED", "to_country_name": "Pakistan", "to_country": "PK", "receiving_mode": "BANK" }, { "rate": 22.67208167, "to_currency_name": "INDIAN RUPEE", "to_currency": "INR", "from_currency": "AED", "to_country_name": "India", "to_country": "IN", "receiving_mode": "BANK" }, { "rate": 8.42089024, "to_currency_name": "EGYPTIAN POUND", "to_currency": "EGP", "from_currency": "AED", "to_country_name": "Egypt", "to_country": "EG", "receiving_mode": "BANK" } ] } } |
Request Param | correspondent : <<correspondent>> receiving_mode :<<receiving_mode>> include_correspondents : <<include_correspondents>> receiving_country_code : <<receiving_country_code>> receiving_currency_code : <<receiving_currency_code>> |
Response | { "status": "success", "status_code": 200, "data": { "rates": [ { "rate": 80.22623799, "correspondent": "LR", "anywhere": 0, "to_currency_name": "PAKISTANI RUPEE", "to_currency": "PKR", "from_currency": "AED", "to_country_name": "Pakistan", "to_country": "PK", "receiving_mode": "BANK", "correspondent_name": "LuluRemittance" } ] } } |
Header
Payload
None
Request Param
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
receiving_currency_code | String | 3 | Conditional | Receiving currency code; ISO 3 Char currency code |
receiving_country_code | String | 2 | Conditional | Receiving country code |
include_correspondents | String | - | Optional | if include_correspondents=True ,response will contain correspondent details. |
receiving_mode | String | 20 | Conditional | Receive mode / delivery mode. Example : BANK, CASHPICKUP |
correspondent | String | 2 | Yes | Correspondent.Example: LR , RR |
Response
Name | Data Type | Max Length | Mandatory | Description |
---|
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
API | /raas/masters/v1/accounts/validation |
Authorization | Bearer Token |
Method | GET |
Headers | Content-Type:application/json |
Payload | None |
Parameter | correspondent : <<correspondent>> receiving_country_code : <<receiving_country_code>> receiving_mode : <<receiving_mode>> iso_code : <<iso_code>> routing_code : <<routing_code>> sort_code : <<sort_code>> iban : <<iban>> bank_id : <<bank_id>> branch_id : <<branch_id>> first_name : <<first_name>> middle_name : <<middle_name>> last_name : <<last_name>> account_number : <<account_number>> |
Response | { "status": "success", "status_code": 200, "data": "Validation successful" }
|
Failed Response | { "status": "failure", "status_code": 406, "error_code": 8073102, "message": "Bank account number length is not acceptable. Allowed length is anyOf:14,15,16" }
|
Header
Payload
None
Parameter
Name | Data Type | Max Length | Mandatory | Description |
---|---|---|---|---|
correspondent | String | - | No | Correspondent |
receiving_country_code | Integer | - | Yes | Receiving country code |
receiving_mode | String | - | Yes | Receiving mode |
iso_code | String | - | No | Iso code |
routing_code | Integer | - | No | Routing code |
sort_code | String | - | No | Sort code |
account_number | String | - | No | Account number |
iban | String | - | No | iban |
bank_id | String | - | No | Internal Id of bank |
branch_id | String | - | No | Internal Id of branch |
first_name | String | - | No | first name |
middle_name | String | - | No | middle name |
last_name | String | - | No | last name |
account_number | String | 34 | No | account number |
Response
Name | Data Type | Max Length | Mandatory | Description |
---|
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 |
* “CREDITED” Sub-State comes for receive mode BANK
“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 GMT [yyyy-MM-ddTHH:mm:ss.sssZ] and 24 hour format (00-23)
eg: "2022-02-22T20:08:43.323Z"
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.
Account type code is mandatory for all the countries. Must be passed with default value as 1 which is "SAVINGS". If not, get from customer and pass it.
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 is alpha numeric. It should be unique per request. Partner should add partner name as prefix in the ID.
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 |
0 Comments