Diagrama de flujo Pay-Out

 Tu servidor                          API Cashela
     |                                     |
     | 1. GET /api/v1/pay-out/services     |
     |    GET /api/v1/pay-out/countries    |
     |    GET /api/v1/pay-out/payers       |
     |------------------------------------>|
     |<------------------------------------| catálogos
     |                                     |
     | 2. POST /api/v1/pay-out/quotations  |
     |------------------------------------>|
     |<------------------------------------| cotización ONHOLD (válida 30 min)
     |                                     | + payers_available
     |                                     |
     | 3. POST /api/v1/pay-out/            |
     |    transactions/{reference}         |
     |------------------------------------>| fondos reservados en tu billetera
     |<------------------------------------| transacción PROCESSING (o FAILED)
     |                                     |
     | 4. notificación a callback_url      |
     |<------------------------------------| tras la ejecución
     |                                     |
     |           ... entrega ...           |
     |                                     |
     | 5. notificación a callback_url      |
     |<------------------------------------| COMPLETED o FAILED
     |                                     |
     | 6. GET /api/v1/pay-out/             |
     |    transactions/{reference}         |
     |------------------------------------>|
     |<------------------------------------| estado actual

Pasos

1. Catálogos. Busca los servicios, países y pagadores del destino. Los catálogos cambian poco; guárdalos en caché y refréscalos de vez en cuando.
2. Cotización. Crea una cotización con tu external_identifier. Muestra a tu usuario los importes, la tasa y la comisión. Si quieres, llama antes a POST /api/v1/pay-out/calculate para mostrar una estimación sin crear una cotización.
3. Ejecución. En menos de 30 minutos, ejecuta la transacción con la reference de la cotización, un pagador de payers_available, los datos del beneficiario y tu callback_url. Revisa status en la respuesta: comprobaciones de negocio como un saldo insuficiente devuelven 200 con status: "FAILED".
4. Notificación tras la ejecución. Cashela notifica a tu callback_url el estado resultante.
5. Notificación final. Cuando el pago se entrega o falla, Cashela notifica COMPLETED o FAILED. Con COMPLETED los fondos reservados se liquidan; con FAILED vuelven a tu saldo disponible.
6. Consulta de estado. Consulta la transacción cuando necesites el estado actual. Es la fuente de verdad.

Estados

Cotización:   ONHOLD ──(30 min)──> EXPIRED
                │
                └─ ejecutar ──> Transacción: PROCESSING ──> COMPLETED
                                     │              └────> FAILED
                                     └─ falla una comprobación ──> FAILED

Estado	Se aplica a	Significado
ONHOLD	Cotización	Creada y pendiente de ejecución.
EXPIRED	Cotización	No se ejecutó en 30 minutos. Crea otra.
PROCESSING	Transacción	Fondos reservados y entrega iniciada.
COMPLETED	Transacción	Entregado. Final.
FAILED	Transacción	Falló antes o durante el procesamiento. Final.

Situaciones habituales

Situación	Qué ves	Qué hacer
La cotización caducó	422 Quotation has expired.	Crea una cotización nueva con un external_identifier nuevo.
Saldo insuficiente	200 con status: "FAILED" e Insufficient wallet balance.	Recarga tu billetera y empieza de nuevo con una cotización nueva.
Error de red al ejecutar	Sin respuesta	Envía otra vez la misma petición con el mismo cuerpo: recibes la transacción existente, nunca un segundo pago.
Mismo external_identifier, cuerpo distinto	409	Usa un external_identifier nuevo para un pago nuevo.
No llegó una notificación	Nada en tu callback_url	Consulta la transacción o reenvía la notificación.
503 Exchange rate is currently unavailable for this destination.	Al cotizar	Reintenta más tarde.

Lista de control

• Guardas tu external_identifier y la reference de Cashela de cada pago.
• Ejecutas las cotizaciones antes de expiration_date.
• Revisas status en cada respuesta de ejecución, no solo el estado HTTP.
• Verificas la firma de cada notificación y respondes 2xx.
• Tu handler de notificaciones es idempotente.
• Envías un X-Trace-Id y lo registras.