Pagos
El recurso payout, sus estados, cómo cancelarlo y qué hacer cuando falla.
| Campo | Qué es |
|---|---|
beneficiary_id | Obligatorio. A quién pagas; el método y la moneda salen del beneficiario. |
quote_id | Una cotización 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.
{
"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
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 |
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.
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
| 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
POST/v1/payouts/{id}/cancelPuedes 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
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
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.