Changelog

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 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

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 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"
}
📘

Note

For more information and detailed breakdown of possible errors, please seeError Codes.