Beneficiaries

A beneficiary is a recipient’s saved account details for one payout method, such as a bank account, CLABE or PIX key. Add it once and reference its id in every payout, with no need to re-enter account details.

Type Definitions

interface Beneficiary {
  id: string;                         // use as beneficiary_payment_method_id / payment_method_id
  gateway_id: number;                 // payout method ID
  currency: string;
  nickname: string;
  payment_data: Record<string, unknown>;
  created_at: string;
}

interface PayoutMethod {
  id: number;
  method_name: string;
  country: string;
  currency: string;
  base_currency: string;
}

Supported payout countries

GET /payment-methods/payout/countries

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payout/countries' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "data": [
    { "name": "Chile", "code": "CHL" },
    { "name": "Mexico", "code": "MEX" },
    { "name": "Brazil", "code": "BRA" }
  ]
}

Payout methods by country

Returns available payment rails and their integer IDs for a destination country. The id from this response is used as payment_method_id in subsequent steps.

GET /payment-methods/payout?country={iso3}

string

required

Destination country in ISO 3166-1 alpha-3 format (e.g. CHL, MEX, BRA).

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payout?country=MEX' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "data": [
    {
      "id": 30,
      "method_name": "SPEI",
      "country": "MEX",
      "currency": "MXN",
      "base_currency": "MXN"
    }
  ]
}

Payment method form fields

Retrieve the exact bank detail fields required for a payment method before saving them.

GET /beneficiary/form/show/{payment_method_id}

number

required

The integer payment method ID from the /payment-methods/payout response.

curl -X GET 'https://api.yativo.com/api/v1/beneficiary/form/show/30' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Add beneficiary

Save the recipient’s account details. Use the form fields returned above to know exactly which keys are required.

POST /beneficiaries/payment-methods

integer

required

The payout method ID from /payment-methods/payout.

object

required

The recipient’s account details, using the fields from GET /beneficiary/form/show/{{id}} (e.g. account_number, bank_code, clabe, pix_key).

string

required

Currency of the payout method, e.g. CLP, MXN, BRL.

string

required

A label you’ll recognise the beneficiary by.

string

The customer the account belongs to. Some USD bank account methods require it. When they do and it’s missing, the request returns a validation error naming it.

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "gateway_id": 21,
    "currency": "CLP",
    "nickname": "Carlos Mendez - Banco de Chile",
    "payment_data": {
      "account_number": "12345678",
      "bank_code": "001",
      "account_type": "checking"
    }
  }'

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "gateway_id": 30,
    "currency": "MXN",
    "nickname": "Carlos Mendez - SPEI",
    "payment_data": {
      "clabe": "012345678901234567"
    }
  }'

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "gateway_id": GATEWAY_ID,
    "currency": "USD",
    "nickname": "Carlos Andrade - Banco del Pichincha",
    "payment_data": {
      "method": "bank_transfer",
      "beneficiary_name": "Carlos Andrade Vera",
      "document_type": "IDCD",
      "document_value": "1712345678",
      "bank_code": "010",
      "account_type": "savings",
      "account_number": "2203456789"
    }
  }'

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "gateway_id": 40,
    "currency": "BRL",
    "nickname": "Carlos Mendez - PIX",
    "payment_data": {
      "pix_key": "carlos@example.com",
      "pix_key_type": "email"
    }
  }'

Ecuador (USD)

Find the method with GET /payment-methods/payout?country=ECU&currency=USD. Bank codes are listed in its form (GET /beneficiary/form/show/{payment_method_id}).
document_type is IDCD (cédula), CCPT (passport) or TXID (RUC). account_type is checking or savings.
Payouts are 1.00 to 10,000.00 USD and can include cents.
The payout also names the sender: the customer the payout is for, or your business when there’s no customer.
These transfers are completed manually, so they can take longer. They stay processing until the bank transfer is confirmed.

List beneficiaries

GET /beneficiaries/payment-methods/all

curl -X GET 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/all' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Update beneficiary

PUT /beneficiaries/payment-methods/update/{id}

string

required

The beneficiary id.

curl -X PUT 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/update/pm-3a4b5c6d' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: update-pm-001' \
  -d '{
    "payment_data": {
      "clabe": "018345678901234567"
    }
  }'

Delete beneficiary

DELETE /beneficiaries/payment-methods/delete/{id}

string

required

The beneficiary id.

curl -X DELETE 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/delete/pm-3a4b5c6d' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Supported payout countries

Payout methods by country

Payment method form fields

Add beneficiary

Ecuador (USD)

List beneficiaries

Update beneficiary

Delete beneficiary

​Supported payout countries

​Payout methods by country

​Payment method form fields

​Add beneficiary

​Ecuador (USD)

​List beneficiaries

​Update beneficiary

​Delete beneficiary

Supported payout countries

Payout methods by country

Payment method form fields

Add beneficiary

Ecuador (USD)

List beneficiaries

Update beneficiary

Delete beneficiary