> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Beneficiaries

> Save payment destinations for off-ramp and global payments by fetching templates, adding beneficiaries, and managing them via the VelaFi API.

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**

```http theme={null}
X-BH-TOKEN: <your-token>
```

### Request Parameters

**paymentId** `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

> [tab] Mexico — SPEI (Finco Pay)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=105
> ```
>
> ```json theme={null}
> {
>   "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`.

> [tab] Argentina — CVU/CBU (Momentum)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=63
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "CVU/CBU Number": "",
>     "cuit": "",
>     "Bank name": ""
>   }
> }
> ```

> [tab] SEPA (Bridge)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=85
> ```
>
> ```json theme={null}
> {
>   "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.

> [tab] WIRE / ACH (Lead Bank)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=81
> ```
>
> ```json theme={null}
> {
>   "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**

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

### Request Parameters

**merchantId** `number` *required*

The ID of the merchant this beneficiary belongs to.

**paymentId** `number` *required*

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

**country** `string` *required*

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

**fiat** `string` *required*

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

**fieldJson** `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`.

**realName** `string`

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

**remark** `string`

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

### Example Requests

> [accordion] Mexico MXN — SPEI (Finco Pay)
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Argentina ARS — CVU/CBU (Momentum)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 63,
>   "country": "Argentina",
>   "fiat": "ARS",
>   "realName": "John Doe",
>   "fieldJson": {
>     "CVU/CBU Number": "0000000000000000000002",
>     "CUIT": "20000000001"
>   },
>   "remark": "Primary ARS beneficiary"
> }
> ```

> [accordion] Brazil BRL — Pix (Genial)
>
> ```json theme={null}
> {
>   "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 `-`).

> [accordion] Colombia COP — Automatic ACH
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Global USD — Wire (CPN)
>
> ```json theme={null}
> {
>   "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

**code** `number`

Response code. `200` indicates the request was processed.

**msg** `string`

Human-readable result message.

**data** `object`

**data fields**

**id** `number`

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

**status** `number`

Validation status of the beneficiary:

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

**failReason** `string`

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

**sameAccountNumberId** `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.

> [tab] Success
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 456,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 456
>   }
> }
> ```

> [tab] Duplicate Account
>
> ```json theme={null}
> {
>   "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:

> [card] [Get Beneficiary](https://docs.velafi.com/api-reference/beneficiary/get-beneficiary.md)
>
> Retrieve a saved beneficiary's details by its user payment ID.

> [card] [Delete Beneficiary](https://docs.velafi.com/api-reference/beneficiary/delete-beneficiary.md)
>
> Remove a beneficiary that is no longer needed.

> [card] [Set Refund Account](https://docs.velafi.com/api-reference/beneficiary/set-refund-account.md)
>
> Designate a beneficiary as the default refund destination for a merchant.

> [card] [Get Payment Templates](https://docs.velafi.com/api-reference/beneficiary/get-payment-templates.md)
>
> Full reference for all payment method templates and field requirements.

> [!NOTE]
>
> 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.


## Related topics

- [API Overview](https://docs.velafi.com/api-reference/overview.md)
- [Add a Beneficiary](https://docs.velafi.com/api-reference/beneficiary/add-beneficiary.md)
- [Delete a Beneficiary](https://docs.velafi.com/api-reference/beneficiary/delete-beneficiary.md)
- [List Beneficiaries](https://docs.velafi.com/api-reference/beneficiary/get-beneficiary.md)
- [Merchants](https://docs.velafi.com/docs/merchants.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.