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

# Beneficiaries

> Store and manage recipient profiles for recurring payouts

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.

<Accordion title="Type Definitions">
  ```typescript theme={null}
  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;
  }
  ```
</Accordion>

***

## List beneficiaries

```
GET /beneficiaries/list
```

<ParamField query="per_page" type="number">
  Results per page (default: 15).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/beneficiaries/list' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

***

## Create beneficiary

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

```
POST /beneficiaries
```

<ParamField body="name" type="string" required>
  Recipient's full name (individual) or legal business name.
</ParamField>

<ParamField body="email" type="string" required>
  Recipient's email address.
</ParamField>

<ParamField body="type" type="string" required>
  `"individual"` or `"business"`.
</ParamField>

<ParamField body="country" type="string" required>
  Destination country in ISO 3166-1 alpha-3 format (e.g. `CHL`, `MEX`, `BRA`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

***

## Supported payout countries

```
GET /payment-methods/payout/countries
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payout/countries' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": [
      { "name": "Chile", "code": "CHL" },
      { "name": "Mexico", "code": "MEX" },
      { "name": "Brazil", "code": "BRA" }
    ]
  }
  ```
</ResponseExample>

***

## 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}
```

<ParamField query="country" type="string" required>
  Destination country in ISO 3166-1 alpha-3 format (e.g. `CHL`, `MEX`, `BRA`).
</ParamField>

<RequestExample>
  ```bash Mexico theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payout?country=MEX' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success (Mexico) theme={null}
  {
    "status": "success",
    "data": [
      {
        "id": 30,
        "method_name": "SPEI",
        "country": "MEX",
        "currency": "MXN",
        "base_currency": "MXN"
      }
    ]
  }
  ```
</ResponseExample>

***

## 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}
```

<ParamField path="payment_method_id" type="number" required>
  The integer payment method ID from the `/payment-methods/payout` response.
</ParamField>

<RequestExample>
  ```bash SPEI (Mexico, id=30) theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/beneficiary/form/show/30' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## 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
```

<ParamField body="beneficiary_id" type="string" required>
  The beneficiary to attach the payment method to.
</ParamField>

<ParamField body="payment_method_id" type="number" required>
  The integer payment method ID from `/payment-methods/payout`.
</ParamField>

<ParamField body="account_details" type="object" required>
  Key-value pairs of the required fields for this payment method (returned by `GET /beneficiary/form/show/{id}`).
</ParamField>

<RequestExample>
  ```bash Mexico SPEI theme={null}
  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"
      }
    }'
  ```

  ```bash Chile bank transfer theme={null}
  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"
      }
    }'
  ```
</RequestExample>

***

## List payment methods

```
GET /beneficiaries/payment-methods/all
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/all' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## Update payment method

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

<ParamField path="id" type="string" required>
  The payment method record ID.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</RequestExample>

***

## Delete payment method

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

<ParamField path="id" type="string" required>
  The payment method record ID.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE 'https://api.yativo.com/api/v1/beneficiaries/payment-methods/delete/pm-3a4b5c6d' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>