Create Beneficiary V3

curl --request POST \
  --url https://sandbox.api.engagexpay.com/v3/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30",
  "counter_party": "THIRD_PARTY",
  "country": "USA",
  "currency": "USD",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "Walter",
    "last_name": "Reed",
    "email": "walter.reed@example.com",
    "phone": "+12125550143"
  },
  "account_holder_address": {
    "street_line_1": "1 Wall Street",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10005",
    "country": "USA"
  },
  "bank_account": {
    "bank_name": "Chase",
    "number": "12345678901",
    "scheme": "LOCAL",
    "type": "CHECKING"
  },
  "bank_routing": [
    {
      "scheme": "FEDWIRE",
      "number": "021000021"
    }
  ],
  "bank_address": {
    "street_line_1": "270 Park Ave",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10017",
    "country": "USA"
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "refund_instruction": {
    "wallet_address": "0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4",
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "developer_fee": {
    "fixed": 0,
    "percentage": 0
  },
  "settlement_config": {
    "auto_settlement": true
  },
  "receiver_meta_data": {
    "transaction_purpose_id": 1,
    "occupation_id": 53,
    "nationality": "USA",
    "relationship": "FRIEND"
  }
}
'

{
  "data": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "errors": [
    {}
  ],
  "message": "Validation failed!"
}

{
  "message": "Authentication failed"
}

{
  "message": "A beneficiary with the same account details already exists.",
  "error": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

POST

beneficiaries

curl --request POST \
  --url https://sandbox.api.engagexpay.com/v3/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "c1f4a8e2-3b57-4d09-9a61-7e2b5c8d4f30",
  "counter_party": "THIRD_PARTY",
  "country": "USA",
  "currency": "USD",
  "account_holder": {
    "type": "INDIVIDUAL",
    "first_name": "Walter",
    "last_name": "Reed",
    "email": "walter.reed@example.com",
    "phone": "+12125550143"
  },
  "account_holder_address": {
    "street_line_1": "1 Wall Street",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10005",
    "country": "USA"
  },
  "bank_account": {
    "bank_name": "Chase",
    "number": "12345678901",
    "scheme": "LOCAL",
    "type": "CHECKING"
  },
  "bank_routing": [
    {
      "scheme": "FEDWIRE",
      "number": "021000021"
    }
  ],
  "bank_address": {
    "street_line_1": "270 Park Ave",
    "city": "New York",
    "state": "US-NY",
    "postcode": "10017",
    "country": "USA"
  },
  "deposit_instruction": {
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "refund_instruction": {
    "wallet_address": "0x3D6b18Ea54c9F27b0A83d1e6C475b920Fa8E13d4",
    "currency": "USDC",
    "rail": "ETHEREUM"
  },
  "developer_fee": {
    "fixed": 0,
    "percentage": 0
  },
  "settlement_config": {
    "auto_settlement": true
  },
  "receiver_meta_data": {
    "transaction_purpose_id": 1,
    "occupation_id": 53,
    "nationality": "USA",
    "relationship": "FRIEND"
  }
}
'

{
  "data": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "errors": [
    {}
  ],
  "message": "Validation failed!"
}

{
  "message": "Authentication failed"
}

{
  "message": "A beneficiary with the same account details already exists.",
  "error": {
    "beneficiary_id": "0254b433-e47d-412e-844b-b735c4bbba74"
  }
}

{
  "message": "<string>",
  "errors": [
    {}
  ]
}

Any fiat transactions submitted between 9:30 AM and 5:30 PM ET on a weekday are processed the same day. Transactions submitted outside these hours or on weekends will be settled the next business day.

The beneficiary will be ready for transactions only when its status is APPROVED and active is true.
Check all the supported fiat and crypto rails and currencies, along with the valid combinations, in Supported rails and currencies.
The rails and currencies of deposit_instruction and refund_instruction have to be the same.
The available rails and currencies depend on the configuration set up for you. Contact support to know more.
receiver_meta_data.intermediary_routing_number is required for SWIFT payouts.
USD ACH payouts are coming soon.
The minimum amount for USD beneficiaries is 50 USD.

When settlement_config.auto_settlement is true, send funds with a maximum of two decimal places. Anything beyond two decimal places is not counted during conversion.

De-Duplication Logic

Destination Type	Fields Checked
Bank Account	`bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`
E-Wallet	`e_wallet.scheme`, `e_wallet.number`

Authorizations

Authorization

string

header

required

Bearer token authentication. Obtain token from Issue a Token endpoint

Body

application/json

Bank Account
E Wallet

customer_id

string<uuid>

required

Example:

"6fa1ccd4-ffbd-4b20-a113-ccc286b35443"

counter_party

enum<string>

required

Available options:

FIRST_PARTY,

THIRD_PARTY

Example:

"FIRST_PARTY"

country

string

required

Payout country of the beneficiary. Check the supported payout countries in Coverage and capabilities.

Pattern: ^[A-Z]{3}$

Example:

"BGD"

currency

enum<string>

required

Payout currency of the beneficiary.

Available options:

USD,

BDT,

XAF,

NGN,

PKR

Example:

"BDT"

account_holder

Individual · object

required

Individual
Business

Show child attributes

account_holder_address

object

required

Show child attributes

receiver_meta_data

object

required

Show child attributes

developer_fee

object

required

Show child attributes

bank_account

object

required

Show child attributes

bank_address

object

required

Show child attributes

bank_routing

object[]

required

For country-specific routing validation rules, see Bank Account and Routing Validation Rules.

Show child attributes

deposit_instruction

object

required

Token and network the customer deposits on to fund this beneficiary. The currency and rail must match refund_instruction. Availability depends on the payout currency, and not every token is issued on every network. See Supported rails and currencies for valid combinations.

Show child attributes

refund_instruction

object

required

The currency and rail must match deposit_instruction.

Show child attributes

settlement_config

object

Optional. Omit it and auto_settlement is set to true, so the beneficiary settles automatically.

Show child attributes

Response

Beneficiary created successfully

data

object

Show child attributes

⌘I

Authentication

Customers

Beneficiaries

Virtual Accounts

Transactions

Balances

Fees & FX Rates

Catalogue

Webhooks

Create Beneficiary V3

De-Duplication Logic

Authorizations

Body

Response

​De-Duplication Logic

Authorizations

Body

Response

De-Duplication Logic