Beneficiaries

Beneficiaries are saved recipient profiles. Create them once, attach their bank details as a payment method, and reference them by ID in every transfer — no need to re-enter account details for each payment.

Type Definitions

interface Beneficiary {
  beneficiary_id: string;
  name: string;
  email: string;
  type: "individual" | "business";
  country: string;           // ISO 3166-1 alpha-3
  created_at: string;
}

interface CreateBeneficiaryRequest {
  name: string;              // Full name or legal business name
  email: string;
  type: "individual" | "business";
  country: string;           // ISO 3166-1 alpha-3
}

interface BeneficiaryPaymentMethod {
  id: string;
  beneficiary_id: string;
  payment_method_id: number;
  account_details: Record<string, string>;
  created_at: string;
}

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

List beneficiaries

GET /beneficiaries/list

number

Results per page (default: 15).

curl -X GET 'https://api.yativo.com/api/v1/beneficiaries/list' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": [
    {
      "beneficiary_id": "ben-7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "name": "Maria Gonzalez",
      "email": "maria.gonzalez@example.com",
      "type": "individual",
      "country": "CHL",
      "created_at": "2026-04-02T10:00:00.000000Z"
    },
    {
      "beneficiary_id": "ben-8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
      "name": "Tech Solutions SA",
      "email": "payments@techsolutions.mx",
      "type": "business",
      "country": "MEX",
      "created_at": "2026-03-20T09:00:00.000000Z"
    }
  ],
  "pagination": {
    "total": 18,
    "per_page": 15,
    "current_page": 1,
    "last_page": 2
  }
}

Create beneficiary

Create a beneficiary profile. Bank account details are saved separately via the payment methods endpoint below.

POST /beneficiaries

string

required

Recipient’s full name (individual) or legal business name.

string

required

Recipient’s email address.

string

required

"individual" or "business".

string

required

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

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-beneficiary-001' \
  -d '{
    "name": "Maria Gonzalez",
    "email": "maria.gonzalez@example.com",
    "type": "individual",
    "country": "CHL"
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Beneficiary created successfully",
  "data": {
    "beneficiary_id": "ben-7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "name": "Maria Gonzalez",
    "email": "maria.gonzalez@example.com",
    "type": "individual",
    "country": "CHL",
    "created_at": "2026-04-02T10:00:00.000000Z"
  }
}

Supported payout countries

GET /payment-methods/payout/countries

curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payout/countries' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "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 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Save payment method

Attach bank account details to a beneficiary. Use the form fields returned above to know exactly which keys are required.

POST /beneficiaries/payment-methods

string

required

The beneficiary to attach the payment method to.

number

required

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

object

required

Key-value pairs of the required fields for this payment method (returned by GET /beneficiary/form/show/{id}).

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: save-pm-001' \
  -d '{
    "beneficiary_id": "ben-7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "payment_method_id": 30,
    "account_details": {
      "clabe": "012345678901234567"
    }
  }'

curl -X POST 'https://api.yativo.com/api/v1/beneficiaries/payment-methods' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: save-pm-002' \
  -d '{
    "beneficiary_id": "ben-7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "payment_method_id": 21,
    "account_details": {
      "account_number": "12345678",
      "bank_code": "001",
      "account_type": "checking"
    }
  }'

List payment methods

GET /beneficiaries/payment-methods/all

curl -X GET 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/all' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Update payment method

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

string

required

The payment method record ID.

curl -X PUT 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/update/pm-3a4b5c6d' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: update-pm-001' \
  -d '{
    "account_details": {
      "clabe": "018345678901234567"
    }
  }'

Delete payment method

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

string

required

The payment method record ID.

curl -X DELETE 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/delete/pm-3a4b5c6d' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

List beneficiaries

Create beneficiary

Supported payout countries

Payout methods by country

Payment method form fields

Save payment method

List payment methods

Update payment method

Delete payment method

​List beneficiaries

​Create beneficiary

​Supported payout countries

​Payout methods by country

​Payment method form fields

​Save payment method

​List payment methods

​Update payment method

​Delete payment method

List beneficiaries

Create beneficiary

Supported payout countries

Payout methods by country

Payment method form fields

Save payment method

List payment methods

Update payment method

Delete payment method