Skip to main content
Beneficiaries are saved recipient profiles. Create them once and reference them by ID in transfers, eliminating the need to re-enter bank details for every payment. 
interface Beneficiary {
  id: string;
  name: string;
  account_number: string;
  bank_code: string;
  bank_name: string;
  country: string;
  currency: string;
  created_at: string;
}

interface CreateBeneficiaryRequest {
  name: string;
  account_number: string;
  bank_code: string;
  country: string;
  currency: string;
}

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

interface PayoutCountry {
  country: string;
  country_name: string;
  currencies: string[];
}

interface PayoutMethod {
  id: string;
  name: string;
  type: string;
  fields: Array<{ key: string; label: string; required: boolean }>;
}

​
List beneficiaries

GET /beneficiaries/list
​
per_page
number
Results per page.
curl -X GET 'https://api.yativo.com/api/beneficiaries/list' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "data": [
    {
      "id": "benef_01HX9KZMB3F7VNQP8R2WDGT4E5",
      "name": "Acme Supplier Ltd",
      "account_number": "001-987654321",
      "bank_name": "BCP",
      "country": "PE",
      "currency": "PEN",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ]
}

​
Add beneficiary

POST /beneficiaries
​
name
string
required
Recipient’s full name or business name.
​
account_number
string
required
The recipient’s bank account number.
​
bank_code
string
required
The bank’s routing or sort code. Use Local Banks to get valid codes.
​
country
string
required
Destination country (ISO 3166-1 alpha-2).
​
currency
string
required
The currency the recipient receives (ISO 4217).
curl -X POST 'https://api.yativo.com/api/beneficiaries' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Supplier Ltd",
    "account_number": "001-987654321",
    "bank_code": "002",
    "country": "PE",
    "currency": "PEN"
  }'

{
  "status": "success",
  "data": {
    "id": "benef_01HX9KZMB3F7VNQP8R2WDGT4E6",
    "name": "Acme Supplier Ltd",
    "account_number": "001-987654321",
    "bank_code": "002",
    "bank_name": "BCP",
    "country": "PE",
    "currency": "PEN",
    "created_at": "2026-03-26T10:00:00Z"
  }
}

​
Supported payout countries

GET /payment-methods/payout/countries

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

​
Payout methods by country

GET /payment-methods/payout?country={iso}
​
country
string
required
Country ISO code.
curl -X GET 'https://api.yativo.com/api/payment-methods/payout?country=MX' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "status": "success",
  "data": [
    {
      "id": "pm_spei",
      "name": "SPEI Transfer",
      "type": "bank_transfer",
      "fields": [
        { "key": "clabe", "label": "CLABE", "required": true },
        { "key": "bank_name", "label": "Bank Name", "required": false }
      ]
    }
  ]
}

​
Payment method fields

Get the required form fields for a specific bank or payment method. 
GET /beneficiary/form/show/{bankId}
​
bankId
string
required
The bank or payment method ID.
curl -X GET 'https://api.yativo.com/api/beneficiary/form/show/pm_spei' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Save payment method

Attach a specific payment method to a beneficiary. 
POST /beneficiaries/payment-methods
​
beneficiary_id
string
required
The beneficiary to attach the payment method to.
​
payment_method_id
string
required
The payment method ID (from /payment-methods/payout).
​
account_details
object
required
Key-value pairs of the required fields for this payment method.
curl -X POST 'https://api.yativo.com/api/beneficiaries/payment-methods' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "beneficiary_id": "benef_01HX9KZMB3F7VNQP8R2WDGT4E6",
    "payment_method_id": "pm_spei",
    "account_details": {
      "clabe": "012345678901234567"
    }
  }'

​
List payment methods

GET /beneficiaries/payment-methods/all

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

​
Delete payment method

DELETE /beneficiaries/payment-methods/delete/{id}
​
id
string
required
The payment method ID to delete.
curl -X DELETE 'https://api.yativo.com/api/beneficiaries/payment-methods/delete/pm_01HX' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'