# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/beneficiaries" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}'
{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}
{
"id": "bene_9f2c1d7e8a4bx0y1z2a3b4c5"
}
Beneficiaries
Create Beneficiary
Create a beneficiary under an account
POST
/
va
/
v1
/
accounts
/
{account_id}
/
beneficiaries
# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/beneficiaries" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}'
{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}
{
"id": "bene_9f2c1d7e8a4bx0y1z2a3b4c5"
}
Beneficiaries are recipient identities — either an individual or a business — owned by a platform end-customer account. Each beneficiary can hold one or more payment destinations (bank accounts), which are returned nested in the beneficiary object as
Creates a beneficiary under an account. For
payment_destinations[]. Payment destinations are separate resources: the Platform may add them when creating a beneficiary or later through the Payment Destinations endpoints, depending on its onboarding flow.
| Enum | Values |
|---|---|
BeneficiaryType | individual, business |
BeneficiaryStatus | active, disabled |
beneficiary_type, first_name / middle_name / last_name, company_name, status, and verified are immutable after creation — they cannot be changed via PATCH. Use the disable action to change status.individual beneficiaries, first_name and last_name are required; for business beneficiaries, company_name is required. The created beneficiary starts with an empty payment_destinations array — add destinations via the payment-destination endpoints.
Path Parameters
string
required
Id of the parent account (e.g.
acct_...).Request Body
enum
individual | business. Defaults to individual. Immutable after creation.string | null
Honorific or title. Max 20 characters.
string | null
Max 100 characters. Conditional: required when
beneficiary_type is individual. Immutable after creation.string | null
Max 100 characters. Immutable after creation.
string | null
Max 100 characters. Conditional: required when
beneficiary_type is individual. Immutable after creation.string
required
Display name shown in listings and statements. Max 255 characters.
string | null
Max 255 characters. Conditional: required when
beneficiary_type is business. Immutable after creation.string | null
Max 255 characters; must contain
@.string | null
Max 50 characters.
Address
required
Beneficiary address. All sub-fields are required.
Show child attributes
Show child attributes
string
required
Street address.
string
required
Max 100 characters.
string | null
State, province, or region. Max 100 characters. Optional — omit it for countries that have none (Singapore, Hong Kong, Monaco and similar).
string | null
Max 20 characters. Optional — omit it for countries with no postal-code system (Hong Kong, the UAE, Panama, Macau and similar).
string
required
Country code string. Send an ISO 3166-1 alpha-2 value; the shared Address schema does not enforce its length.
PaymentCountry
required
ISO 3166-1 alpha-2 country code; must be on the supported payment-country allowlist.
Response
Returns 200 with the new resource’sid. Use Get Beneficiary to retrieve the full object.
string
Id of the newly created beneficiary (e.g.
bene_...).# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/beneficiaries" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}'
{
"beneficiary_type": "business",
"display_name": "Globex Ltd",
"company_name": "Globex Limited",
"email": "ap@globex.example",
"address": {
"address_line": "5 King St",
"city": "London",
"region": "London",
"postal_code": "EC2V 8AS",
"country": "GB"
},
"country_code": "GB"
}
{
"id": "bene_9f2c1d7e8a4bx0y1z2a3b4c5"
}