# Cómo pagar (/docs/pay-out)

Un pago (`payout`) sale de tu saldo y llega a un **beneficiario**: la cuenta de la persona o empresa a la que pagas. El recorrido completo:

<Mermaid chart={`flowchart LR
  A[capabilities] --> B[cliente<br/>remitente]
  B --> C[beneficiario]
  C --> D[cotización]
  D --> E[pago]
  E -.-> F[webhook<br/>payout.completed]`} />

<Steps>
<Step>
### Mira qué pide el país [#mira-qué-pide-el-país]

```bash
curl "$CAIBO_API/v1/capabilities?product=payout&currency=PEN" \
  -H "Authorization: Bearer $CAIBO_API_KEY"
```

`beneficiary_fields` dice qué datos de la cuenta necesitas; `customer_fields`, qué datos del remitente. Ver [Qué puedes hacer](/docs/capabilities).
</Step>

<Step>
### Registra al remitente, si el país lo pide [#registra-al-remitente-si-el-país-lo-pide]

Algunos países piden saber quién envía. El remitente es un [cliente](/docs/customers) tuyo:

```bash
curl "$CAIBO_API/v1/customers" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: cliente-crm-8812" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-8812",
    "type": "individual",
    "country": "PE",
    "display_name": "Carlos Mendoza",
    "profile": {
      "first_name": "Carlos",
      "last_name": "Mendoza Rojas",
      "date_of_birth": "1988-04-12",
      "identity_document_type": "DNI",
      "identity_document": "41234567",
      "identity_document_country": "PE",
      "address": { "city": "Lima", "country": "PE" }
    }
  }'
```
</Step>

<Step>
### Registra al beneficiario [#registra-al-beneficiario]

```bash
curl "$CAIBO_API/v1/beneficiaries" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "bank_transfer",
    "currency": "PEN",
    "customer_id": "cus_01m3sgb02af7nb0jf73vwv2sd4",
    "holder": "Rosa Elena Quispe Mamani",
    "details": {
      "cci": "00219100123456780123",
      "document_number": "45678912",
      "first_name": "Rosa Elena",
      "last_name": "Quispe Mamani"
    }
  }'
```

Lo registras una vez y le pagas las veces que quieras. `details` nunca se devuelve. Ver [Beneficiarios](/docs/beneficiaries).
</Step>

<Step>
### Fija el precio [#fija-el-precio]

```bash
curl "$CAIBO_API/v1/quotes" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: cotizacion-orden-5531" \
  -H "Content-Type: application/json" \
  -d '{ "source_currency": "USDT", "destination_currency": "PEN", "method": "bank_transfer", "amount": "350.00", "amount_side": "destination" }'
```

```json
{
  "id": "quo_01m3sgaz0000000000000000",
  "status": "open",
  "method": "bank_transfer",
  "source": { "currency": "USDT", "principal": "100.000000", "platform_fee": "0.500000", "tenant_markup": "0.000000", "total": "100.500000" },
  "destination": { "amount": "350.00", "currency": "PEN" },
  "rate": "3.500000000000000000",
  "created_at": "2026-10-18T14:00:10Z",
  "expires_at": "2026-10-18T14:01:40Z"
}
```

`amount_side: destination` fija lo que **recibe** el beneficiario; `source`, lo que **sale** de tu saldo. La cotización vale hasta `expires_at`. Ver [Cotizaciones](/docs/quotes).
</Step>

<Step>
### Paga [#paga]

```bash
curl "$CAIBO_API/v1/payouts" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: pago-orden-5531" \
  -H "Content-Type: application/json" \
  -d '{ "beneficiary_id": "ben_01m3sgazybenxvqfw0h5bnszk4", "quote_id": "quo_01m3sgaz0000000000000000", "description": "Orden 5531" }'
```

Responde `201` con `status: processing`: los fondos (`source.total`) quedaron reservados y el pago está en camino.
</Step>

<Step>
### Recibe el resultado [#recibe-el-resultado]

Te llega `payout.completed` cuando el beneficiario recibió el dinero, o `payout.failed` con `failure_code` si no se pudo pagar; en ese caso los fondos vuelven a tu saldo disponible. Ver [Pagos](/docs/payouts).
</Step>
</Steps>

<Callout title="Sin cotización">
También puedes pagar sin cotizar antes: envía `source_currency`, `amount` y `amount_side` en lugar de `quote_id`, y el pago se cotiza al crearse.
</Callout>