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
endpointTo 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 countryFor 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 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.
Updated 10 months ago