This API is available to Partner Institutions to provide external bank transfers including IPI, UAEFTS and SWIFT to their customers. Partner can initiate an ad-hoc transfer from their customer's account to an external bank account i.e. a non-RAKBANK account, by passing all details of the beneficiary in the request. The API does not require the beneficiary to be pre-registered. The Payment Reference Id will be returned in the response for a successful payment request initiation. The API should be invoked only before the daily cutoff time. Any transfers requests initiated by the customer on the partner App/ Web application after the cut-off time must be held at the client's side and posted at BOD (Beginning Of Day) the next business day. There are also daily transaction limits applicable for the API which needs to be enforced by the client on their App/ Web application. For information on applicable currency-wise cutoff & BOD times and daily transaction limits, see <a href="/faq-page/#external-transfers">FAQ</a>.
The API also allows to fetch the status of the previously created transaction.
Version 1.1.0
- Added mandatory field customer_category and optional fields intermediary_bank_BIC, intermediary_bank_name & remarks in the request.
Allowing retry based on same transaction_id. In case of timeout or 500 errors, you may retry upto 3 times with an interval of 60 seconds between every retry. Please ensure to pass the same transaction_id in the path for retry requests. If the previous transaction with the same transaction_id was posted successfully, then the previous response would be echoed for the retries. If the previous transaction was unsuccessful, then the system will try to reprocess the transaction.
<h3>OAuth Metadata details</h3> OAuth metadata parameter to be passed at the time of generating access token using <a href="/partner-authentication">Partner Authentication API</a> for client credential grant type is mentioned below. For information on OAuth Metadata, see <a href="/security/#oauth-metadata-partnerauth">About the OAuth Metadata</a> <p class="oauth_metadata">oauth_metadata.account_id : {account_id}</p>
| Attachment | Size |
|---|---|
 Postman Collection | 5.54 KB |
FAQs
Click Here for FAQs
Response Codes
Click Here for API Response Codes
Reference Data
Click Here for API Reference Data
Basepath
/v2
Paths
/external_transfers/{transaction_id}
Create Transaction Request
Creates a transaction to initiate payment from a RAKBANK account to an external bank account by providing details of the beneficiary. A payment request is created and a payment ref Id and charges are returned in the response.
Unique Id sent by client. Value should be a unique identifier of the request in UUID format.
{
"maxLength": 50
}Unique transaction ID that is generated by the client. The transaction_id used to create the payment transaction. This must not repeat atleast for a period of six months. Please ensure to pass the same transaction_id in the path for retry requests.
{
"maxLength": 20
}Request details to create a payment transaction.
201 Created
Error
Internal Server Error
/external_transfers/{transaction_id}/transaction_status
Get Transaction status by passing the transaction_id.
Unique Id sent by client. Value should be a unique identifier of the request in UUID format.
{
"maxLength": 50
}Unique transaction ID that is generated by the client. The transaction_id used to create the payment transaction. This must not repeat atleast for a period of six months. Please ensure to pass the same transaction_id in the path for retry requests.
{
"maxLength": 20
}Definitions
Response in case of error
{
"properties": {
"status": {
"type": "string",
"description": "HTTP Status"
},
"response_code": {
"type": "string",
"description": "API specific error code"
},
"property": {
"type": "string"
},
"response_message": {
"type": "string",
"description": "brief type of the error",
"example": ""
},
"description": {
"type": "string",
"description": "detailed description of the error"
}
},
"additionalProperties": false,
"required": [
"response_code",
"status",
"response_message"
]
}
This will contain the details of the external account.
{
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Name of the beneficiary.",
"example": "Gordan"
},
"other_account_id": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Account id of the beneficiary. Will hold IBAN when other_bank_country=AE.",
"example": "963521478"
},
"other_account_currency": {
"type": "string",
"minLength": 1,
"maxLength": 3,
"description": "Currency of the beneficiary account. Same as Remitting curreny.",
"example": "AED"
},
"other_bank_name": {
"type": "string",
"minLength": 1,
"maxLength": 35,
"description": "Bank Name of the beneficiary bank.",
"example": "ICICI"
},
"other_bank_BIC": {
"type": "string",
"minLength": 1,
"maxLength": 12,
"description": "BIC code of the beneficiary bank. Mandatory in the request for within UAE AED transactions, i.e. when other_bank_country=AE and other_account_currency=AED. For all other types of transactions, must be passed if beneficiary bank BIC was provided by the customer.",
"example": "ADCBAEAAXXX"
},
"other_branch_name": {
"type": "string",
"minLength": 1,
"maxLength": 35,
"description": "Branch Name of the beneficiary bank. Mandatory in the request when other_bank_country is not AE. Default value '001' to be sent in the request when other_bank_country=AE and other_account_currency is not AED. Not required when other_bank_country=AE and other_account_currency=AED.",
"example": "PB-POTHUHERA."
},
"other_branch_addr1": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Address of the beneficiary bank.",
"example": "15th Main,"
},
"other_branch_addr2": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"description": "City of the beneficiary bank. Mandatory in the request when other_bank_country is not AE. Default value 'AE' to be sent in the request when other_bank_country=AE and other_account_currency is not AED. Not required when other_bank_country=AE and other_account_currency=AED.",
"example": "Colombo"
},
"other_bank_country": {
"type": "string",
"minLength": 1,
"maxLength": 2,
"description": "ISO 2 character country code of the beneficiary bank."
},
"address": {
"$ref": "#/definitions/address",
"description": "Address of residence or incorporation of the beneficiary."
},
"intermediary_bank_name": {
"type": "string",
"minLength": 1,
"maxLength": 35,
"description": "Intermediary Bank Name.",
"example": "AXIS Bank"
},
"intermediary_bank_BIC": {
"type": "string",
"minLength": 1,
"maxLength": 12,
"description": "Intermediary Bank BIC.",
"example": "AXISINBB"
}
},
"additionalProperties": false,
"required": [
"name",
"other_account_id",
"other_account_currency",
"other_bank_name",
"other_bank_country",
"address"
]
}
This will contain the details of the remitter
{
"properties": {
"customer_id_type": {
"type": "string",
"enum": [
"Account_ID"
],
"description": "Type of the Customer id of the customer who initiates the transaction. Allowed values - Account_ID",
"example": "Account_ID"
},
"customer_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"example": "1234xxxxxx567",
"description": "Customer id of the customer, corresponding to the customer_id_type, who initiates the transaction. Masked value should be passed in the UAT and Production environments. For information on the masking logic to be followed, see Masking Logic"
}
},
"additionalProperties": false,
"required": [
"customer_id",
"customer_id_type"
]
}
Transaction amount details
{
"properties": {
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 3,
"description": "Currency",
"example": "AED"
},
"amount": {
"type": "string",
"pattern": "^((\\d{1}|\\d{2}|\\d{3}|\\d{4}|\\d{5}|\\d{6}|\\d{7}|\\d{8}|\\d{9}|\\d{10}|\\d{11}|\\d{12}|\\d{13}|\\d{14}|\\d{15}|\\d{16})?\\.?(\\d{1}|\\d{2}|\\d{3})?)$",
"minLength": 1,
"maxLength": 20,
"description": "Amount Value",
"example": 2001
}
},
"additionalProperties": false,
"required": [
"currency",
"amount"
]
}
{
"properties": {
"line_1": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Address line 1 of the beneficiary"
},
"line_2": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Address line 2 of the beneficiary"
},
"line_3": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Address line 3 of the beneficiary"
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "City of the beneficiary"
},
"state": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "State of the beneficiary"
},
"district": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "District of the beneficiary"
},
"country": {
"type": "string",
"minLength": 1,
"maxLength": 2,
"description": "Country of residence or incorporation of the Beneficiary. ISO 2 Character Country Code."
}
},
"additionalProperties": false,
"required": [
"country"
]
}
{
"properties": {
"from": {
"$ref": "#/definitions/from"
},
"to": {
"$ref": "#/definitions/to"
},
"value": {
"$ref": "#/definitions/value"
},
"purpose_code": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "code for the Purpose of the remittance. Should be one of the values provided in the Master data.",
"example": "8"
},
"rate": {
"type": "string",
"description": "Fx Rate that will apply for the transfer. This should be the rate returned in Forex Rate & Charges API. However, this will only be an indicative rate. The actual rate applied for the transaction may differ in the scenario where the rate in the system has changed at the time of processing of the transaction, i.e. after the transaction has cleared AML screening.",
"example": "2.957223"
},
"rate_code": {
"type": "string",
"minLength": 1,
"maxLength": 5,
"description": "Fx Rate Code that will apply for the transfer. This should be the rate_code returned in Fx Rate & Charges API.",
"example": "TTS"
},
"charges_type": {
"type": "string",
"enum": [
"BEN",
"SHA",
"OUR"
],
"description": "Charge Type selected by the customer. Valid options: BEN - All charges to Beneficiary, SHA - Share the charges, OUR - All charges to be charged to the customer.",
"example": "BEN"
},
"is_CBWSI_payment": {
"type": "string",
"enum": [
"Y",
"N"
],
"description": "Flag to identify if customer has selected Immediate Payment option for WithinUAE transactions. Valid options: Y - Immediate Payment, N - UAEFTS/SWIFT Payment. Applicable for payments up to AED 10,000 initiated by individual customers, when payments are made to eligible banks only and when Remitting Currency is AED, i.e. other_account_currency=AED, and with an eligible Purpose code. For information on eligible banks and eligilble purpose codes, see FAQ. If not passed, transaction will be routed through UAEFTS. "
},
"remarks": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"minItems": 1,
"maxItems": 3,
"description": "Optional Transaction Remarks line1, line2 and line3.",
"example": [
"line1",
"line2",
"line3"
]
},
"customer_category": {
"type": "string",
"enum": [
"Individual",
"Business"
],
"description": "Category of the customer initiating the transfer. Valid options: Individual - for Individual customers, Business - for business customers.",
"example": "Individual"
}
},
"additionalProperties": false,
"required": [
"from",
"to",
"value",
"purpose_code",
"charges_type",
"customer_category"
]
}
Response object
{
"properties": {
"transaction_id": {
"type": "string",
"maxLength": 20,
"description": "The client's unique id for the transaction.",
"example": "58215225"
},
"payment_ref_id": {
"type": "string",
"maxLength": 25,
"description": "The bank's unique id for the transaction.",
"example": "14091746202"
},
"end_date": {
"type": "string",
"description": "Date when the transaction is executed.",
"example": "2017-09-14",
"format": "date"
},
"total_debit_amount": {
"type": "string",
"minLength": 0,
"maxLength": 20,
"description": "Total amount that will be debited for this transaction, including charges.",
"example": "2020.00"
},
"debit_currency_code": {
"type": "string",
"minLength": 1,
"maxLength": 3,
"description": "Currency code of the total_debit_amount.",
"example": "AED"
},
"transaction_status": {
"description": "Transaction status object.",
"$ref": "#/definitions/transaction_status"
}
},
"additionalProperties": false,
"required": [
"transaction_id",
"payment_ref_id",
"end_date",
"total_debit_amount",
"debit_currency_code"
]
}
Transaction status object. The PUT method will only return the href to the associated transaction_status resource.
{
"properties": {
"status": {
"type": "string",
"maxLength": 5,
"description": "Status of the transaction. This is only returned in the response of GetTransactionStatus operation. | - S = (Success) indicates the reciept of ACK from SWIFT/UAEFTS server, - F = (Failure) indicates the reciept of NACK from SWIFT/UAEFTS server, - P = (Processing) indicates any other status (Eg. Ready, Awaiting Authorization, etc…) from SWIFT/UAEFTS server",
"example": "S"
},
"status_desc": {
"type": "string",
"maxLength": 254,
"description": "Description of the transaction status. This is only returned in the response of GetTransactionStatus operation.",
"example": "Success"
},
"href": {
"type": "string",
"example": "https://testapi.rakbank.ae/rb/api/v1/external_transfers/1232144/transaction_status",
"description": "href value to fetch the transaction status of a specific transaction_id."
}
},
"additionalProperties": false
}