Skip to main content
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. 
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
​
per_page
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
​
name
string
required
Recipient’s full name (individual) or legal business name.
​
email
string
required
Recipient’s email address.
​
type
string
required
"individual" or "business".
​
country
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}
​
country
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}
​
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
​
beneficiary_id
string
required
The beneficiary to attach the payment method to.
​
payment_method_id
number
required
The integer payment method ID from /payment-methods/payout.
​
account_details
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"
    }
  }'

​
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}
​
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}
​
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'