Create Beneficiary
Method is used to add a new beneficiary for the user. For some of the banks this is required to transfer funds from the user's account to the beneficiary's.
Pre-Conditions
You have obtained user's permanent access token from
Exchange Token
endpointTo read more about authentication process and access token please refer to Authentication Documentation
Note
Please note that this endpoint is only required if you use
Create Transfer
instead ofAutoFlow
endpoint and sender bank requires beneficiary.If you are still using
Create Transfer
endpoint, we recommend you switch toAuto Flow
Request
https://api.dapi.com/v2/payment/beneficiaries/create
Headers
Parameter | Type | Description |
---|---|---|
Authorization REQUIRED | String | Set type to bearer token and the value to the accessToken obtained using the Exchange Token request. |
Body Parameters
Parameter | Type | Description |
---|---|---|
appSecret REQUIRED | String | Private token generated at application creation. |
userSecret REQUIRED | String | Encrypted version of the userKey. |
name REQUIRED | String | Name of the beneficiary. |
nickname REQUIRED | String | Nickname of the beneficiary. |
accountNumber REQUIRED | String | Account number of the beneficiary. |
type REQUIRED | Enum | Type of beneficiary. - same - beneficiary's bank is the same as the sender's - local - beneficiary's bank is in the same country>br>- intl - beneficiary's bank is in a different countryFor further explanation see Beneficiary Types |
address REQUIRED | Object<Address> | An object containing the address information of the beneficiary. |
country REQUIRED | String | Name of the country in all uppercase letters (e.g. “AE”). |
sortCode OPTIONAL | String | Financial institution’s sort code. |
branchAddress REQUIRED | String | Address of the financial institution’s specific branch. |
bankName REQUIRED | String | Name of the financial institution. |
branchName REQUIRED | String | Name of the financial institution’s specific branch. |
phoneNumber REQUIRED | String | Beneficiary's phone number. |
iban REQUIRED | String | Beneficiary's IBAN number. |
swiftCode REQUIRED | String | Beneficiary's financial institution's SWIFT code. |
Address schema
Parameter | Type | Description |
---|---|---|
line1 REQUIRED | String | Street name and number. Note: value should not contain any commas or special characters. |
line2 REQUIRED | String | City name. Note: value should not contain any commas or special characters. |
line3 REQUIRED | String | Country name. Note: value should not contain any commas or special characters. |
Request Example
{
"appSecret": "{{app_secret}}",
"userSecret": "{{user_secret}}",
"type": "local",
"swiftCode": "NBSHAEAS",
"sortCode": " 123456",
"bankName": "Sharjah Islamic Bank",
"name": "AbdulRahman Darooqi Farooqi",
"nickname": "AbdulRahman SIB",
"iban": "AE360410000033417426040",
"accountNumber": "",
"country": "AE",
"branchName": "American university of sharjah",
"branchAddress": "AUS",
"address": {
"line1": "AUS",
"line2": "University City",
"line3": "Sharjah"
}
}
Response
Note
Your responses may differ from those listed below on a case-by-case basis.
Parameter | Type | Description |
---|---|---|
operationID | String | Unique ID generated to identify a specific operation. |
success | Boolean | Returns true if request is successful and false for all else. |
status | Enum | The status of the job.done - Operation Completed failed - Operation Failed user_input_required - Pending User Input initialized - Operation In Progress*For further explanation see Operation Statuses |
userInputs | Array<UserInputs> | Specifies the type of further information required from the user before the job can be completed. Is only returned if operation status is `user_input_required |
type | Enum | Type of error encountered Is only returned when operation was not successful |
msg | String | Detailed description of the error Is only returned if the request was not successful |
Response Example
{
"operationID": "3b74fcb5-56c2-4664-a010-39769ebfbcec",
"success": true,
"status": "done"
}
Successful Request/Response
Successful Request
{
"appSecret": "{{app_secret}}",
"userSecret": "{{user_secret}}",
"type": "local",
"swiftCode": "NBSHAEAS",
"sortCode": " 123456",
"bankName": "Sharjah Islamic Bank",
"name": "AbdulRahman Darooqi Farooqi",
"nickname": "AbdulRahman SIB",
"iban": "AE360410000033417426040",
"accountNumber": "",
"country": "AE",
"branchName": "American university of sharjah",
"branchAddress": "AUS",
"address": {
"line1": "AUS",
"line2": "University City",
"line3": "Sharjah"
}
}
Successful Response
{
"operationID": "3b74fcb5-56c2-4664-a010-39769ebfbcec",
"success": true,
"status": "done"
}
Request / Response - When User Input Required
Request - When User Input Required
{
"appSecret": "{{app_secret}}",
"userSecret": "{{user_secret}}",
"type": "local",
"swiftCode": "NBSHAEAS",
"sortCode": " 123456",
"bankName": "Sharjah Islamic Bank",
"name": "AbdulRahman Darooqi Farooqi",
"nickname": "AbdulRahman SIB",
"iban": "AE360410000033417426040",
"accountNumber": "",
"country": "AE",
"branchName": "American university of sharjah",
"branchAddress": "AUS",
"address": {
"line1": "AUS",
"line2": "University City",
"line3": "Sharjah"
}
}
Response - When User Input Required
{
"operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
"success": true,
"status": "user_input_required",
"userInputs": [
{
"answer": "",
"id": "otp",
"index": 0,
"query": "Please enter a Smart Pass Token from your ENBD mobile application"
}
]
}
For more information on handling user input, please see User Inputs.
Failed Request / Response
Failed Request
{
"appSecret": "{{app_secret}}",
"userSecret": "{{user_secret}}",
"type": "local",
"bankName": "Sharjah Islamic Bank",
"name": "AbdulRahman Darooqi Farooqi",
"nickname": "AbdulRahman SIB",
"iban": "AE360410000033417426040",
"country": "AE",
"branchName": "American university of sharjah",
"branchAddress": "AUS",
"address": {
"line1": "AUS",
"line2": "University City",
"line3": "Sharjah"
}
}
Failed Response
{
"msg": "Invalid access token",
"type": "UNAUTHORIZED",
"success": false,
"status": "failed"
}
Failed Request / Response - Invalid Key
Failed Request - Invalid Key
{
"appSecret": "Invalid_Key",
"userSecret": "Invalid_secret",
"type": "local",
"bankName": "Sharjah Islamic Bank",
"name": "AbdulRahman Darooqi Farooqi",
"nickname": "AbdulRahman SIB",
"iban": "AE360410000033417426040",
"country": "AE",
"branchName": "American university of sharjah",
"branchAddress": "AUS",
"address": {
"line1": "AUS",
"line2": "University City",
"line3": "Sharjah"
}
}
Failed Response - Invalid Key
{
"msg": "Invalid access token",
"type": "UNAUTHORIZED",
"success": false,
"status": "failed"
}
Note
For more information and detailed breakdown of possible errors, please see Errors.
Updated 9 months ago