Changelog

Create Wire Beneficiary (US only)

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

ParameterTypeDescription
Authorization
REQUIRED
StringSet type to bearer token and the value to the accessToken obtained using the Exchange Token request.

Body Parameters

ParameterTypeDescription
appSecret
REQUIRED
StringPrivate token generated at application creation.
userSecret
REQUIRED
StringEncrypted version of the userKey.
name
REQUIRED
StringName of the beneficiary.
nickname
REQUIRED
StringNickname of the beneficiary.
accountNumber
REQUIRED
StringAccount number of the beneficiary.
routingNumber
REQUIRED
StringRouting number of the beneficiary.
type
REQUIRED
EnumType 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
StringName of the country in all uppercase letters (e.g. “UNITED ARAB EMIRATES”).
sortCode
OPTIONAL
StringFinancial institution’s sort code.
branchAddress
REQUIRED
StringAddress of the financial institution’s specific branch.
branchName
REQUIRED
StringName of the financial institution’s specific branch.

Address schema

ParameterTypeDescription
line1
REQUIRED
StringStreet name and number. Note: value should not contain any commas or special characters.
line2
REQUIRED
StringCity name. Note: value should not contain any commas or special characters.
line3
REQUIRED
StringCountry 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.

ParameterTypeDescription
operationIDStringUnique ID generated to identify a specific operation.
successBooleanReturns true if request is successful and false for all else.
statusEnumThe 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
userInputsArray<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
typeEnumType of error encountered

Is only returned when operation was not successful
msgStringDetailed 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 see User 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 see Errors.