Pay-Out flow diagram

 Your server                          Cashela API
     |                                     |
     | 1. GET /api/v1/pay-out/services     |
     |    GET /api/v1/pay-out/countries    |
     |    GET /api/v1/pay-out/payers       |
     |------------------------------------>|
     |<------------------------------------| catalogs
     |                                     |
     | 2. POST /api/v1/pay-out/quotations  |
     |------------------------------------>|
     |<------------------------------------| quotation ONHOLD (valid 30 min)
     |                                     | + payers_available
     |                                     |
     | 3. POST /api/v1/pay-out/            |
     |    transactions/{reference}         |
     |------------------------------------>| funds reserved in your wallet
     |<------------------------------------| transaction PROCESSING (or FAILED)
     |                                     |
     | 4. notification to callback_url     |
     |<------------------------------------| after execution
     |                                     |
     |          ... delivery ...           |
     |                                     |
     | 5. notification to callback_url     |
     |<------------------------------------| COMPLETED or FAILED
     |                                     |
     | 6. GET /api/v1/pay-out/             |
     |    transactions/{reference}         |
     |------------------------------------>|
     |<------------------------------------| current status

Steps

1. Catalogs. Find the services, countries and payers for the destination. Catalogs change rarely; cache them and refresh periodically.
2. Quotation. Create a quotation with your external_identifier. Show the amounts, rate and fee to your user. Optionally, call POST /api/v1/pay-out/calculate first to show an estimate without creating a quotation.
3. Execution. Within 30 minutes, execute the transaction with the quotation reference, a payer from payers_available, the beneficiary details and your callback_url. Check status in the response: business checks such as an insufficient balance return 200 with status: "FAILED".
4. Notification after execution. Cashela notifies your callback_url with the resulting status.
5. Final notification. When the payout is delivered or fails, Cashela notifies COMPLETED or FAILED. On COMPLETED the reserved funds are settled; on FAILED they return to your available balance.
6. Status check. Query the transaction whenever you need the current status. It is the source of truth.

Statuses

Quotation:    ONHOLD ──(30 min)──> EXPIRED
                │
                └─ execute ──> Transaction: PROCESSING ──> COMPLETED
                                     │             └────> FAILED
                                     └─ business check fails ──> FAILED

Status	Applies to	Meaning
ONHOLD	Quotation	Created and waiting for execution.
EXPIRED	Quotation	Not executed within 30 minutes. Create a new one.
PROCESSING	Transaction	Funds reserved and delivery started.
COMPLETED	Transaction	Delivered. Final.
FAILED	Transaction	Failed before or during processing. Final.

Handling common situations

Situation	What you see	What to do
The quotation expired	422 Quotation has expired.	Create a new quotation with a new external_identifier.
Not enough balance	200 with status: "FAILED" and Insufficient wallet balance.	Fund your wallet and start again with a new quotation.
Network error while executing	No response	Send the same request again with the same body: you get the existing transaction, never a second payout.
Same external_identifier, different body	409	Use a new external_identifier for a new payout.
A notification did not arrive	Nothing at your callback_url	Query the transaction, or re-send the notification.
503 Exchange rate is currently unavailable for this destination.	On quotation	Retry later.

Checklist

• You store your external_identifier and the Cashela reference of every payout.
• You execute quotations before expiration_date.
• You check status in every execute response, not only the HTTP status.
• You verify the signature of every notification and answer 2xx.
• Your notification handler is idempotent.
• You send an X-Trace-Id and log it.