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-ConditionsYou have obtained user's permanent access token from
Exchange Token
endpoint.To read more about authentication process and access token, please refer to Authentication.
NotePlease note that this endpoint is only required if you use the
Create Transfer
instead of theAutoFlow
endpoint and the sender bank requires a beneficiary.If you are still using the
Create Transfer
endpoint, we recommend you switch toAuto Flow
.
Request
https://api.dapi.com/v2/payment/beneficiaries/create
Headers
Parameter | Type | Description |
---|---|---|
Authorization REQUIRED |
| Set type to bearer token and the value to the accessToken obtained using the Exchange Token request |
Body Parameters
Parameter | Type | Description |
---|---|---|
appSecret REQUIRED |
| Private token generated at application creation |
userSecret |
| Encrypted version of the userKey |
name |
| Name of the beneficiary |
nickname |
| Nickname of the beneficiary |
accountNumber |
| Account number of the beneficiary |
type |
| Type of beneficiary
For further explanation see Beneficiary Types |
address |
| An object containing the address information of the beneficiary |
country |
| Name of the country in all uppercase letters (e.g. “AE”) |
sortCode |
| Financial institution’s sort code |
branchAddress |
| Address of the financial institution’s specific branch |
bankName |
| Name of the financial institution |
branchName |
| Name of the financial institution’s specific branch |
phoneNumber |
| Beneficiary's phone number |
iban |
| Beneficiary's IBAN number |
swiftCode |
| Beneficiary's financial institution's SWIFT code |
Address schema
Parameter | Type | Description |
---|---|---|
line1 REQUIRED |
| Street name and number Note: value should not contain any commas or special characters |
line2 |
| City name Note: value should not contain any commas or special characters |
line3 |
| 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
NoteYour responses may differ from those listed below on a case-by-case basis.
Parameter | Type | Description |
---|---|---|
operationID |
| Unique ID generated to identify a specific operation |
success |
| Returns |
status |
| The status of the job
|
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 |
| Type of error encountered Is only returned when operation was not successful |
msg |
| 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 seeMulti-Factor Authentication Handling.
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"
}
NoteFor more information and detailed breakdown of possible errors, please seeError Codes.
Updated 9 days ago