Beneficiarios
La cuenta a la que pagas. La registras una vez y le pagas cuantas veces quieras.
POST/v1/beneficiaries
| 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
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.
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.
Respuesta
{
"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.