# Pagos (/docs/payouts)

<Endpoint method="POST" path="/v1/payouts" href="/docs/api/payouts/create-payout" />

| Campo | Qué es |
| --- | --- |
| `beneficiary_id` | Obligatorio. A quién pagas; el método y la moneda salen del beneficiario. |
| `quote_id` | Una [cotización](/docs/quotes) vigente. |
| `source_currency`, `amount`, `amount_side` | O, en lugar de `quote_id`, estos tres: el pago se cotiza al crearse. |
| `description` | Hasta 500 caracteres, para ti. |

Lleva siempre un `Idempotency-Key`: repetir la solicitud con la misma clave devuelve el mismo pago y **nunca paga dos veces**.

```json title="201"
{
  "id": "pout_01m3sgb02af7nb0jf73vwv2sd4",
  "status": "processing",
  "method": "bank_transfer",
  "beneficiary_id": "ben_01m3sgazybenxvqfw0h5bnszk4",
  "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",
  "quote_id": "quo_01m3sgaz0000000000000000",
  "created_at": "2026-10-18T14:00:20Z",
  "updated_at": "2026-10-18T14:00:20Z"
}
```

## Estados [#estados]

<Mermaid chart={`stateDiagram-v2
  [*] --> processing
  processing --> completed
  processing --> failed
  processing --> cancelled
  processing --> verification_pending
  verification_pending --> completed
  verification_pending --> failed
  completed --> returned`} />

| `status` | Qué significa | Evento |
| --- | --- | --- |
| `processing` | Aceptado, fondos reservados, en camino. | `payout.created` |
| `verification_pending` | Enviado, pero el resultado aún no es seguro. Los fondos siguen reservados; **nunca se reenvía**. Termina en `completed` o `failed`. | — |
| `completed` | El beneficiario recibió el dinero. | `payout.completed` |
| `failed` | No se pagó; los fondos vuelven a tu saldo disponible. | `payout.failed` |
| `cancelled` | Cancelado antes de salir. | `payout.cancelled` |
| `returned` | Se pagó y luego el banco lo devolvió; mira `refund`. | `payout.returned`, `payout.return_settled` |

<Callout type="warn" title="Mientras no es final, no hagas otro pago">
`processing` y `verification_pending` significan "todavía no". No crees otro pago para lo mismo: el original se está resolviendo y terminará en un estado final. `verification_pending` no tiene evento propio; consulta el pago si tarda.
</Callout>

## Cuando no alcanza el saldo [#cuando-no-alcanza-el-saldo]

El pago se crea igual (`201`) con `status: failed` y `failure_code: insufficient_funds`. No reserva nada y llega solo `payout.failed`, sin `payout.created`. Su `Idempotency-Key` y su cotización quedan usados: para reintentar, usa una clave nueva y una cotización nueva.

## failure_code [#failure_code]

| Código | Qué pasó |
| --- | --- |
| `insufficient_funds` | Tu saldo no alcanzaba. |
| `invalid_instruction` | El banco rechazó los datos: cuenta, banco no soportado o remitente incompleto. |
| `no_route` | No había ruta para pagar. |
| `not_submitted` | No llegó a enviarse. |
| `resolved_not_executed` | Se confirmó que no se ejecutó. |
| `risk_rejected` | Lo rechazó la revisión de riesgo. |
| `cancelled_before_submission` | Se canceló antes de salir. |

Puede aparecer también un código propio del banco. Trata cualquier código que no conozcas como "falló y no se pagó".

## Cancelar [#cancelar]

<Endpoint method="POST" path="/v1/payouts/{id}/cancel" href="/docs/api/payouts/cancel-payout" />

Puedes cancelar mientras el pago está `processing`, no salió al banco, no está en revisión y no es parte de un lote ni de una remesa.

| Respuesta | Qué significa |
| --- | --- |
| `202` | Pedido: `cancellation.status: requested`. Decidimos antes de enviarlo. |
| `200` | Ya está cancelado. |
| `409 payout_not_cancellable` | No se puede; `reasons` dice por qué: `submitted`, `outcome_uncertain`, `already_completed`, `already_failed`, `already_returned`, `in_review`, `managed_by_batch`, `managed_by_remittance`. |

Si el pago salió mientras la cancelación estaba pendiente, `cancellation.status` queda en `refused`.

## Revisión de riesgo [#revisión-de-riesgo]

Un pago puede quedar en revisión (`risk_status: in_review`): sigue en `processing`, con los fondos reservados, y llega `risk.review_required`. Si se aprueba, continúa; si se rechaza, falla con `risk_rejected`.

## Consultar [#consultar]

`GET /v1/payouts/{id}` agrega `beneficiary` (con `account_hint`, los últimos dígitos de la cuenta), `description`, `country` y las fechas `completed_at`, `failed_at`, `returned_at`, `cancelled_at`. La lista se filtra por `status`, `beneficiary_id`, `risk_status` y fechas.