Create Beneficiary V2
curl --request POST \
--url https://sandbox.api.engagexpay.com/v2/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [
{
"number": "021000021"
}
],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
'const url = 'https://sandbox.api.engagexpay.com/v2/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: 'cust_123456',
country: 'USA',
currency: 'USD',
account_holder: {
type: 'INDIVIDUAL',
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890'
},
account_holder_address: {
street_line_1: '456 Main Street',
city: 'Brooklyn',
state: 'US-NY',
postcode: '11201',
country: 'USA',
street_line_2: 'Apt 5B'
},
receiver_meta_data: {
transaction_purpose_id: 1,
occupation_remarks: 'Software Engineer',
nationality: 'USA',
transaction_purpose_remarks: 'Monthly salary payment',
occupation_id: 5,
relationship_remarks: 'Long-term contractor',
govt_id_number: 'JG1121316A',
govt_id_issue_date: '2024-12-30',
govt_id_expire_date: '2027-12-30'
},
developer_fee: {fixed: 5, percentage: 2.5},
deposit_instruction: {currency: 'USDC', rail: 'POLYGON'},
refund_instruction: {
wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
currency: 'USDC',
rail: 'POLYGON'
},
bank_account: {bank_name: 'Chase Bank', number: '1234567890'},
bank_routing: [{number: '021000021'}],
bank_address: {
street_line_1: '123 Bank Street',
city: 'New York',
state: 'US-NY',
postcode: '10001',
country: 'USA',
street_line_2: 'Suite 100'
},
counter_party: 'FIRST_PARTY'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.engagexpay.com/v2/beneficiaries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
.asString();import requests
url = "https://sandbox.api.engagexpay.com/v2/beneficiaries"
payload = {
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [{ "number": "021000021" }],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.engagexpay.com/v2/beneficiaries"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"id": "ben_123456",
"status": "active"
}
}{
"errors": [
{}
],
"message": "Validation failed!"
}{
"message": "Authentication failed"
}{
"message": "A beneficiary with the same account details already exists.",
"error": {
"beneficiary_id": "d9868585-78ba-4723-b0af-8f5b1cc5f9e2"
}
}{
"message": "<string>",
"errors": [
{}
]
}Create Beneficiary
Create Beneficiary V2
Create a new beneficiary account for payments and transfers
POST
/
v2
/
beneficiaries
Create Beneficiary V2
curl --request POST \
--url https://sandbox.api.engagexpay.com/v2/beneficiaries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [
{
"number": "021000021"
}
],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
'const url = 'https://sandbox.api.engagexpay.com/v2/beneficiaries';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
customer_id: 'cust_123456',
country: 'USA',
currency: 'USD',
account_holder: {
type: 'INDIVIDUAL',
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890'
},
account_holder_address: {
street_line_1: '456 Main Street',
city: 'Brooklyn',
state: 'US-NY',
postcode: '11201',
country: 'USA',
street_line_2: 'Apt 5B'
},
receiver_meta_data: {
transaction_purpose_id: 1,
occupation_remarks: 'Software Engineer',
nationality: 'USA',
transaction_purpose_remarks: 'Monthly salary payment',
occupation_id: 5,
relationship_remarks: 'Long-term contractor',
govt_id_number: 'JG1121316A',
govt_id_issue_date: '2024-12-30',
govt_id_expire_date: '2027-12-30'
},
developer_fee: {fixed: 5, percentage: 2.5},
deposit_instruction: {currency: 'USDC', rail: 'POLYGON'},
refund_instruction: {
wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
currency: 'USDC',
rail: 'POLYGON'
},
bank_account: {bank_name: 'Chase Bank', number: '1234567890'},
bank_routing: [{number: '021000021'}],
bank_address: {
street_line_1: '123 Bank Street',
city: 'New York',
state: 'US-NY',
postcode: '10001',
country: 'USA',
street_line_2: 'Suite 100'
},
counter_party: 'FIRST_PARTY'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://sandbox.api.engagexpay.com/v2/beneficiaries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
.asString();import requests
url = "https://sandbox.api.engagexpay.com/v2/beneficiaries"
payload = {
"customer_id": "cust_123456",
"country": "USA",
"currency": "USD",
"account_holder": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890"
},
"account_holder_address": {
"street_line_1": "456 Main Street",
"city": "Brooklyn",
"state": "US-NY",
"postcode": "11201",
"country": "USA",
"street_line_2": "Apt 5B"
},
"receiver_meta_data": {
"transaction_purpose_id": 1,
"occupation_remarks": "Software Engineer",
"nationality": "USA",
"transaction_purpose_remarks": "Monthly salary payment",
"occupation_id": 5,
"relationship_remarks": "Long-term contractor",
"govt_id_number": "JG1121316A",
"govt_id_issue_date": "2024-12-30",
"govt_id_expire_date": "2027-12-30"
},
"developer_fee": {
"fixed": 5,
"percentage": 2.5
},
"deposit_instruction": {
"currency": "USDC",
"rail": "POLYGON"
},
"refund_instruction": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"currency": "USDC",
"rail": "POLYGON"
},
"bank_account": {
"bank_name": "Chase Bank",
"number": "1234567890"
},
"bank_routing": [{ "number": "021000021" }],
"bank_address": {
"street_line_1": "123 Bank Street",
"city": "New York",
"state": "US-NY",
"postcode": "10001",
"country": "USA",
"street_line_2": "Suite 100"
},
"counter_party": "FIRST_PARTY"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.api.engagexpay.com/v2/beneficiaries"
payload := strings.NewReader("{\n \"customer_id\": \"cust_123456\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"account_holder\": {\n \"type\": \"INDIVIDUAL\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n },\n \"account_holder_address\": {\n \"street_line_1\": \"456 Main Street\",\n \"city\": \"Brooklyn\",\n \"state\": \"US-NY\",\n \"postcode\": \"11201\",\n \"country\": \"USA\",\n \"street_line_2\": \"Apt 5B\"\n },\n \"receiver_meta_data\": {\n \"transaction_purpose_id\": 1,\n \"occupation_remarks\": \"Software Engineer\",\n \"nationality\": \"USA\",\n \"transaction_purpose_remarks\": \"Monthly salary payment\",\n \"occupation_id\": 5,\n \"relationship_remarks\": \"Long-term contractor\",\n \"govt_id_number\": \"JG1121316A\",\n \"govt_id_issue_date\": \"2024-12-30\",\n \"govt_id_expire_date\": \"2027-12-30\"\n },\n \"developer_fee\": {\n \"fixed\": 5,\n \"percentage\": 2.5\n },\n \"deposit_instruction\": {\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"refund_instruction\": {\n \"wallet_address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\",\n \"currency\": \"USDC\",\n \"rail\": \"POLYGON\"\n },\n \"bank_account\": {\n \"bank_name\": \"Chase Bank\",\n \"number\": \"1234567890\"\n },\n \"bank_routing\": [\n {\n \"number\": \"021000021\"\n }\n ],\n \"bank_address\": {\n \"street_line_1\": \"123 Bank Street\",\n \"city\": \"New York\",\n \"state\": \"US-NY\",\n \"postcode\": \"10001\",\n \"country\": \"USA\",\n \"street_line_2\": \"Suite 100\"\n },\n \"counter_party\": \"FIRST_PARTY\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"id": "ben_123456",
"status": "active"
}
}{
"errors": [
{}
],
"message": "Validation failed!"
}{
"message": "Authentication failed"
}{
"message": "A beneficiary with the same account details already exists.",
"error": {
"beneficiary_id": "d9868585-78ba-4723-b0af-8f5b1cc5f9e2"
}
}{
"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.
V3 is the current version of this endpoint. Use Create Beneficiary V3
for new integrations. V2 stays available for existing integrations.
Rules
- Beneficiary creation requires the customer to be in the
APPROVEDstatus. - Two beneficiaries with the same destination are not allowed.
- The minimum amount for USD beneficiaries is 50 USD.
De-Duplication Logic
For bank accounts, the system checks:bank_account.scheme, bank_account.number, bank_routing.scheme, bank_routing.number.
For e-wallets: e_wallet.scheme, e_wallet.number.
Country-Specific Validation
GBR (United Kingdom)
- Bank account number: Must match
^[0-9]{4,9}$for bothLOCALandSWIFTschemes.
Authorizations
Bearer token authentication. Obtain token from Issue a Token endpoint
Body
application/json
- Bank Account
- E Wallet
Example:
"cust_123456"
Pattern:
^[A-Z]{3}$Example:
"USA"
Example:
"USD"
- Individual
- Business
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Indicates whether the beneficiary is a first-party or third-party account. Optional.
Available options:
FIRST_PARTY, THIRD_PARTY Example:
"FIRST_PARTY"
Show child attributes
Show child attributes
Response
Beneficiary created successfully
Show child attributes
Show child attributes
⌘I