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 endpoint.
To read more about authentication process and access token, please refer to Authentication.

❗️
Note
Please note that this endpoint is only required if you use the Create Transfer instead of the AutoFlow endpoint and the sender bank requires a beneficiary.
If you are still using the Create Transfer endpoint, we recommend you switch to Auto 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 country For 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 Multi-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"
}

📘
Note
For more information and detailed breakdown of possible errors, please see Error Codes.