Manage Beneficiaries

A beneficiary is a saved payment destination — a bank account, mobile wallet, or payment identifier — that your merchant sends funds to during off-ramp or global fiat-to-fiat payment operations. Adding a beneficiary involves two steps: first, retrieve the field template for the payment method you want to use, then submit the filled-in template to register the destination. Once saved, a beneficiary can be reused for repeated payouts without re-entering account details each time.

Step 1: Get Payment Method Templates

Before adding a beneficiary, retrieve the template for your chosen payment method. The template tells you exactly which fields you need to populate for that payment method. Endpoint

GET https://api.velafi.com/v2/payments/templates

Headers

X-BH-TOKEN: <your-token>

Request Parameters

number

required

The numeric ID of the payment method. Each payment method (e.g. SPEI for Mexico, CVU for Argentina, SEPA, WIRE/ACH) has its own ID. See the table below for common IDs.

Common Payment Method IDs

Payment ID	Name	Type	Country / Network
`105`	SPEI (Finco Pay)	Automatic	Mexico
`72`	SPEI (Tesored)	Automatic	Mexico
`63` (Sandbox: `18`)	CBU/CVU (Momentum)	Automatic	Argentina
`137`	3.0 Transfer (QR)	Automatic	Argentina
`90`	Pix (Genial)	Automatic	Brazil
`92`	Pix - Woovi (Avenia)	Automatic	Brazil
`68`	Automatic ACH	Automatic	Colombia
`69`	Bre-B	Automatic	Colombia
`95`	Bank Transfer	Automatic	Peru
`81` (Sandbox: `532`)	ACH Reference (Lead Bank)	Automatic	USA
`83` (Sandbox: `534`)	FedWire Reference (Lead Bank)	Automatic	USA
`85`	SEPA (Bridge)	Automatic	Europe
`120`	Wire (CPN)	Automatic	Global
`124`	SEPA (CPN)	Automatic	Global
`127`	FEDWIRE (CPN)	Automatic	USA

Example Template Responses

Mexico — SPEI (Finco Pay)
Argentina — CVU/CBU (Momentum)
SEPA (Bridge)
WIRE / ACH (Lead Bank)

GET /v2/payments/templates?paymentId=105

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "Account Type": "",
    "Account Number": "",
    "Beneficiary Name": "",
    "Bank Code": ""
  }
}

Account Type: clabe (virtual account) or debit (card account). Bank Code: Required only when Account Type is debit.

GET /v2/payments/templates?paymentId=63

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "CVU/CBU Number": "",
    "cuit": "",
    "Bank name": ""
  }
}

GET /v2/payments/templates?paymentId=85

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "Bank Name": "",
    "Account Owner Name": "",
    "Account Owner Type": "",
    "Bank Country/Region": "",
    "Account Number": "",
    "Bic": "",
    "firstName": "",
    "lastName": "",
    "businessName": ""
  }
}

Account Owner Type: Business or Individual. If Business: businessName is required. If Individual: firstName and lastName are required. Bank Country/Region: ISO 3166-1 alpha-2 country code.

GET /v2/payments/templates?paymentId=81

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "Bank Name": "",
    "Account Owner Name": "",
    "Account Owner Type": "",
    "Bank Country/Region": "",
    "Account Number": "",
    "Routing Number": "",
    "Street Line1": "",
    "Street Line2": "",
    "City": "",
    "State": "",
    "Postal Code": "",
    "firstName": "",
    "lastName": "",
    "businessName": ""
  }
}

Account Owner Type: Business or Individual. Bank Country/Region: ISO 3166-1 alpha-2. State: ISO 3166-2 state/province code.

Step 2: Add a Beneficiary

Once you have the template for your target payment method, fill in the fields and submit a POST request to register the beneficiary under a merchant. Endpoint

POST https://api.velafi.com/v2/payments

Headers

X-BH-TOKEN: <your-token>
Content-Type: application/json

Request Parameters

number

required

The ID of the merchant this beneficiary belongs to.

number

required

The ID of the payment method. Must match an existing payment method ID in the system.

string

required

The full name of the beneficiary’s country (e.g. Mexico, Argentina, Brazil).

string

required

The fiat currency for this beneficiary (e.g. MXN, ARS, USD, EUR).

object

required

The filled-in payment template fields as a key-value object. The keys and value formats must match the template returned by GET /v2/payments/templates.

string

The real name of the account holder. Optional but recommended for compliance records.

string

An optional free-text note to attach to this beneficiary record.

Example Requests

Mexico MXN — SPEI (Finco Pay)

{
  "merchantId": 123,
  "paymentId": 105,
  "country": "Mexico",
  "fiat": "MXN",
  "realName": "John Doe",
  "fieldJson": {
    "Account Type": "clabe",
    "Account Number": "123456789012345678",
    "Beneficiary Name": "John Doe",
    "Bank Code": ""
  },
  "remark": "Primary MXN beneficiary"
}

Argentina ARS — CVU/CBU (Momentum)

{
  "merchantId": 123,
  "paymentId": 63,
  "country": "Argentina",
  "fiat": "ARS",
  "realName": "John Doe",
  "fieldJson": {
    "CVU/CBU Number": "0000000000000000000002",
    "CUIT": "20000000001"
  },
  "remark": "Primary ARS beneficiary"
}

Brazil BRL — Pix (Genial)

{
  "merchantId": 123,
  "paymentId": 90,
  "country": "Brazil",
  "fiat": "BRL",
  "realName": "Tom",
  "fieldJson": {
    "Pix Type": "EMAIL",
    "Pix Key": "tom@example.com"
  },
  "remark": "Primary BRL beneficiary"
}

Pix Type accepted values: CPF (11 digits), CNPJ (14 digits), EMAIL, PHONE (10-11 digits), RANDOM_KEY (with -).

Colombia COP — Automatic ACH

{
  "merchantId": 123,
  "paymentId": 68,
  "country": "Colombia",
  "fiat": "COP",
  "realName": "Tom",
  "fieldJson": {
    "Account Type": "cc",
    "Full Name": "Tom",
    "ID Document Type": "cc",
    "ID Document Number": "123456789",
    "Bank Code": "1007",
    "Bank Account Number": "9876543210"
  },
  "remark": "Primary COP beneficiary"
}

Global USD — Wire (CPN)

{
  "merchantId": 123,
  "paymentId": 120,
  "country": "United States",
  "fiat": "USD",
  "realName": "Tom",
  "fieldJson": {
    "beneficiaryName": "Tom",
    "country": "US",
    "stateProvince": "US-AK",
    "city": "Alaska",
    "street": "789 Main Street",
    "postalCode": "10001",
    "dateOfBirth": "1990-01-01",
    "idNumber": "123456",
    "idExpirationDate": "2099-01-01",
    "useCase": "B2B",
    "reasonForPayment": "PMT001",
    "bankName": "Bank of Example",
    "bankCountry": "US",
    "swiftCode": "EXAMPLUSXXX",
    "accountNumber": "123456"
  },
  "remark": "USD wire beneficiary"
}

Response Fields

number

Response code. 200 indicates the request was processed.

string

Human-readable result message.

object

Show data fields

number

The user payment ID assigned to this beneficiary. Use this ID to reference the beneficiary in payout requests.

number

Validation status of the beneficiary:

1 — Valid and ready to receive payments.
2 — Authenticating (verification in progress).
3 — Authentication failed.

string

Description of the failure when status is 3. Empty on success.

number

When status is 3 due to a duplicate account, this field contains the id of the existing valid beneficiary with the same account number. Use this ID for payouts instead of creating a new record.

Success
Duplicate Account

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "id": 456,
    "status": 1,
    "failReason": "",
    "sameAccountNumberId": 456
  }
}

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "id": 0,
    "status": 3,
    "failReason": "account already exists",
    "sameAccountNumberId": 100
  }
}

Use sameAccountNumberId (100 in this example) as the beneficiary ID for your payout — the account already exists as a valid record.

Managing Beneficiaries

After creating beneficiaries, you can manage them through additional API operations:

Get Beneficiary

Retrieve a saved beneficiary’s details by its user payment ID.

Delete Beneficiary

Remove a beneficiary that is no longer needed.

Set Refund Account

Designate a beneficiary as the default refund destination for a merchant.

Get Payment Templates

Full reference for all payment method templates and field requirements.

Under the same Merchant ID and paymentId, the same receiving account number can only have one record in valid status at a time. If you attempt to add a duplicate, the API returns status: 3 with a sameAccountNumberId pointing to the existing valid record.

Get Started

Core Concepts

Guides

Reference

Manage Beneficiaries

Step 1: Get Payment Method Templates

Request Parameters

Common Payment Method IDs

Example Template Responses

Step 2: Add a Beneficiary

Request Parameters

Example Requests

Response Fields

Managing Beneficiaries

Get Beneficiary

Delete Beneficiary

Set Refund Account

Get Payment Templates

​Step 1: Get Payment Method Templates

​Request Parameters

​Common Payment Method IDs

​Example Template Responses

​Step 2: Add a Beneficiary

​Request Parameters

​Example Requests

​Response Fields

​Managing Beneficiaries

Get Beneficiary

Delete Beneficiary

Set Refund Account

Get Payment Templates

Step 1: Get Payment Method Templates

Request Parameters

Common Payment Method IDs

Example Template Responses

Step 2: Add a Beneficiary

Request Parameters

Example Requests

Response Fields

Managing Beneficiaries