# Beneficiarios (/docs/beneficiaries)

<Endpoint method="POST" path="/v1/beneficiaries" href="/docs/api/beneficiaries/create-beneficiary" />

| Campo | Obligatorio | Qué es |
| --- | --- | --- |
| `method` | Sí | El método de pago: `bank_transfer`, `pix`, `mobile_payment`… |
| `currency` | Sí | La moneda que recibe. |
| `details` | Sí | Los datos de la cuenta, según `beneficiary_fields` en capabilities. Nunca se devuelven. |
| `customer_id` | Según el país | El remitente. |
| `holder` | No | El nombre del titular, para mostrar. |
| `label` | No | Tu etiqueta, hasta 100 caracteres. |
| `metadata` | No | Tus datos. |

Validamos `details` al registrar. Un dato inválido responde `400 invalid_parameter` con `param: "details.<campo>"`. Si registras dos veces la misma cuenta para el mismo cliente, recibes el beneficiario existente (`200`).

## Datos por país [#datos-por-país]

<Tabs items={["Perú · PEN", "Brasil · PIX", "Venezuela · VES"]}>
<Tab value="Perú · PEN">

Método `bank_transfer`, a una cuenta por su **CCI**.

| Campo | Formato | Ejemplo |
| --- | --- | --- |
| `cci` | 20 dígitos | `00219100123456780123` |
| `document_number` | DNI (8 dígitos) o RUC (11 dígitos que empiezan con 10, 15 o 20) | `45678912` |
| `first_name` | Nombres del titular, como en su documento | `Rosa Elena` |
| `last_name` | Apellidos del titular | `Quispe Mamani` |

Necesita un **remitente** completo: ver [Clientes](/docs/customers).

</Tab>
<Tab value="Brasil · PIX">

Método `pix`.

| Campo | Formato | Ejemplo |
| --- | --- | --- |
| `name` | Nombre del titular, 2 a 140 caracteres | `Ana Souza` |
| `pix_key` | CPF (11 dígitos), CNPJ (14), teléfono `+55…`, correo o clave aleatoria (UUID) | `ana@example.com` |

Los dígitos verificadores de CPF y CNPJ se comprueban.

</Tab>
<Tab value="Venezuela · VES">

Métodos `mobile_payment` (pago móvil) y `bank_transfer`.

| Campo | Método | Formato | Ejemplo |
| --- | --- | --- | --- |
| `phone` | `mobile_payment` | `0412`, `0414`, `0416`, `0422`, `0424` o `0426` + 7 dígitos | `04121234567` |
| `account_number` | `bank_transfer` | 20 dígitos | `01020123450000012345` |
| `bank_code` | Ambos | 4 dígitos | `0102` |
| `document.type` | Ambos | `V`, `E`, `J`, `G`, `P`, `C` o `R` | `V` |
| `document.number` | Ambos | El número del documento | `12345678` |
| `name` | Ambos, opcional | Nombre del titular | `María Pérez` |

```json
{
  "method": "mobile_payment",
  "currency": "VES",
  "details": {
    "phone": "04121234567",
    "bank_code": "0102",
    "document": { "type": "V", "number": "12345678" }
  }
}
```

</Tab>
</Tabs>

<Callout>
Esta tabla es una guía. La fuente de verdad es `beneficiary_fields` en `GET /v1/capabilities?product=payout`: cada campo trae su `pattern`, así que puedes validar en tu formulario lo mismo que valida la API.
</Callout>

## Respuesta [#respuesta]

```json
{
  "id": "ben_01m3sgazybenxvqfw0h5bnszk4",
  "method": "bank_transfer",
  "currency": "PEN",
  "country": "PE",
  "customer_id": "cus_01m3sgb02af7nb0jf73vwv2sd4",
  "holder": "Rosa Elena Quispe Mamani",
  "status": "active",
  "verification_status": "unverified",
  "created_at": "2026-10-18T14:00:05Z",
  "updated_at": "2026-10-18T14:00:05Z"
}
```

`verification_status` pasa a `verified` cuando Caibo verifica la cuenta (`beneficiary.verified`). El país lo fija el método.