Skip to main content
POST
Add a Beneficiary
Add a new beneficiary so that it can later be referenced in off-ramp or global-payment orders. Before calling this endpoint, retrieve the required field structure by calling GET /v2/payments/templates with the target paymentId and populate the fieldJson object accordingly. Under the same merchant ID and paymentId, each unique receiving account may hold only one valid status — attempting to register a duplicate account returns a status: 3 response with sameAccountNumberId pointing to the existing record.

Endpoint

Use https://api-test.velafi.com/v2/payments for sandbox testing.

Request Headers

Request Body Parameters

integer
The numeric ID of the merchant under which to register the beneficiary. Always pass it: the beneficiary is linked to this merchant’s currency account for the payment method. Without it, the request fails with -4010 for manual payment methods and -5070 for automatic ones.
integer
required
The numeric ID of the payment method. Determines which fields are required in fieldJson.
string
required
Full name of the beneficiary’s country (e.g., "Mexico", "Argentina", "Brazil").
string
required
ISO 4217 fiat currency code for this beneficiary (e.g., "MXN", "ARS", "BRL", "USD").
string
required
The legal real name of the account holder.
object
required
Key-value pairs that populate the payment method template. Retrieve the exact required keys by calling GET /v2/payments/templates?paymentId={paymentId}. Use the field’s indexCode as the key when it is non-empty; otherwise use the title string. See Beneficiary Fields by Payment Method for the keys of every enabled payout method.
string
Optional free-text note about this beneficiary (e.g., "Preferred supplier account").

Response Fields

integer
Response status code. 200 indicates success.
string
Human-readable response message.
object
Result data object.

Examples