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

Request

https://api.dapi.com/v2/wire/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.
routingNumber REQUIRED	`String`	Routing 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. “UNITED ARAB EMIRATES”).
sortCode OPTIONAL	`String`	Financial institution’s sort code.
branchAddress REQUIRED	`String`	Address of the financial institution’s specific branch.
branchName REQUIRED	`String`	Name of the financial institution’s specific branch.

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",
    "sortCode": " 123456",
    "bankName": "Wells Fargo",
    "name": "John Doe",
    "nickname": "John WF",
    "sortingNumber": "334757",
    "accountNumber": "33417426040",
    "country": "UNITED STATES",
    "branchName": "Wells Fargo",
    "branchAddress": "New York",
    "address": {
        "line1": "Baker Street",
        "line2": "New York",
        "line3": "United States"
    }
}

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",
    "sortCode": " 123456",
    "bankName": "Wells Fargo",
    "name": "John Doe",
    "nickname": "John WF",
    "sortingNumber": "334757",
    "accountNumber": "33417426040",
    "country": "UNITED STATES",
    "branchName": "Wells Fargo",
    "branchAddress": "New York",
    "address": {
        "line1": "Baker Street",
        "line2": "New York",
        "line3": "United States"
    }
}

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",
    "sortCode": " 123456",
    "bankName": "Wells Fargo",
    "name": "John Doe",
    "nickname": "John WF",
    "sortingNumber": "334757",
    "accountNumber": "33417426040",
    "country": "UNITED STATES",
    "branchName": "Wells Fargo",
    "branchAddress": "New York",
    "address": {
        "line1": "Baker Street",
        "line2": "New York",
        "line3": "United States"
    }
}

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 the OTP sent to your phone number."
    }
    ]
}

For more information on handling user input, please seeUser Inputs.

Failed Request / Response

Failed Request

{
    "appSecret": "{{app_secret}}",
    "userSecret": "{{user_secret}}",
     "type": "local",
    "sortCode": " 123456",
    "bankName": "Wells Fargo",
    "name": "John Doe",
    "nickname": "John WF",
    "sortingNumber": "334757",
    "accountNumber": "33417426040",
    "country": "UNITED STATES",
    "branchName": "Wells Fargo",
    "branchAddress": "New York",
    "address": {
        "line1": "Baker Street",
        "line2": "New York",
        "line3": "United States"
    }
}

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",
    "sortCode": " 123456",
    "bankName": "Wells Fargo",
    "name": "John Doe",
    "nickname": "John WF",
    "sortingNumber": "334757",
    "accountNumber": "33417426040",
    "country": "UNITED STATES",
    "branchName": "Wells Fargo",
    "branchAddress": "New York",
    "address": {
        "line1": "Baker Street",
        "line2": "New York",
        "line3": "United States"
    }
}

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