Create a quotation

A quotation fixes the amounts, the exchange rate and the fee of a payout and lists the payers that can deliver it. You execute it later with Execute a transaction. A quotation is valid for 30 minutes.

Endpoint

POST/api/v1/pay-out/quotations

Authentication: HTTP Basic with your API key and secret. See Authentication.

Body

Field	Type	Required	Description
`external_identifier`	string	Yes	Your unique ID for this payout, up to 255 characters. It becomes the quotation `reference` and is the idempotency key (see below).
`mode`	string	Yes	`SOURCE_AMOUNT`: you set the amount to send. `DESTINATION_AMOUNT`: you set the amount the beneficiary receives.
`transaction_type`	string	Yes	`C2C`, `C2B`, `B2C` or `B2B`.
`service_id`	integer	Yes	Service ID provided by Cashela for your integration.
`pay_out_service_id`	integer	No	Limit the quote to one service. Use an `id` from Payout services.
`payer_id`	integer	No	Limit the quote to one payer. Use an `id` from Payers.
`source.currency`	string	Yes	Currency you send from (ISO 4217). It must be the currency of one of your active wallets.
`source.country_iso_code`	string	Yes	3-letter code of the sending country, for example `USA`.
`source.amount`	number	With `SOURCE_AMOUNT`	Amount to send.
`destination.currency`	string	Yes	Currency the beneficiary receives, for example `COP`.
`destination.country_iso_code`	string	Yes	3-letter destination country code, for example `COL`.
`destination.amount`	number	With `DESTINATION_AMOUNT`	Amount the beneficiary receives.

Amounts are positive numbers with at most two decimals, from 0.01 to 99999999.99. Currency and country codes are case-insensitive.

Example

curl -X POST "https://sandbox-api.cashela.com/api/v1/pay-out/quotations" \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Trace-Id: 6f1d2c4e-8b0a-4a57-9c1e-2f3a4b5c6d7e" \
  -d '{
    "external_identifier": "payout-2026-000123",
    "mode": "SOURCE_AMOUNT",
    "transaction_type": "C2C",
    "service_id": 1,
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "currency": "COP", "country_iso_code": "COL" }
  }'

{
  "success": true,
  "data": {
    "id": 98765,
    "reference": "payout-2026-000123",
    "external_identifier": "payout-2026-000123",
    "status": "ONHOLD",
    "status_message": null,
    "idempotency": { "key": "payout-2026-000123", "external_identifier": "payout-2026-000123" },
    "mode": "SOURCE_AMOUNT",
    "transaction_type": "C2C",
    "source": { "amount": 100, "currency": "USD", "country_iso_code": "USA" },
    "destination": { "amount": 395000, "currency": "COP", "country_iso_code": "COL" },
    "sent_amount": { "amount": 100, "currency": "USD" },
    "wholesale_fx_rate": 3950,
    "fee": { "amount": 3.5, "currency": "USD" },
    "creation_date": "2026-10-19T12:00:00.000000Z",
    "expiration_date": "2026-10-19T12:30:00.000000Z",
    "payers_available": [
      { "id": 123, "name": "Example Bank", "currency": "COP", "country": "COL", "service": { "id": 2, "name": "Bank deposit" } }
    ],
    "next_action": { "type": "execute_transaction", "endpoint": "..." }
  },
  "message": "Quotation created successfully."
}

Amounts, rates and IDs are illustrative. A successful call answers 200.

Response fields

Field	Type	Description
`id`	integer	Cashela quotation ID.
`reference`	string	Quotation reference. It is your `external_identifier`. Use it in the transaction path.
`external_identifier`	string	Your ID, echoed.
`status`	string	`ONHOLD` while it can be executed, `EXPIRED` after 30 minutes. Once executed it follows the transaction (`PROCESSING`, `COMPLETED`, `FAILED`).
`status_message`	string or null	Detail of the status, if any.
`idempotency`	object	The `Idempotency-Key` header you sent (or your `external_identifier` when you sent none) and your `external_identifier`.
`mode`	string	Mode you requested.
`transaction_type`	string	Transaction type you requested.
`source`	object	Amount sent, currency and country.
`destination`	object	Amount the beneficiary receives, currency and country.
`sent_amount`	object	Amount sent and its currency.
`wholesale_fx_rate`	number	Exchange rate applied to the quotation.
`fee`	object	Fee and its currency (the source currency).
`creation_date`	string	When the quotation was created.
`expiration_date`	string	When it expires (30 minutes after creation).
`payers_available`	array	Payers that can deliver this payout: `id`, `name`, `currency`, `country`, `service`. Pick one for the transaction.
`next_action.type`	string	Always `execute_transaction`.

Idempotency

The quotation is identified by your external_identifier:

Sending the same body again with the same external_identifier returns the existing quotation. No new quotation is created.
Sending a different body with an external_identifier you already used returns 409 A quotation already exists for this external_identifier or idempotency key with a different payload.
If the existing quotation has expired, the replay returns it with status EXPIRED. Create a new quotation with a new external_identifier.

Errors

Status	Message (examples)	What to do
`422`	`Validation failed.` with `errors`	Fix the fields listed in `errors`. A `source.currency` that is not one of your wallet currencies fails here.
`422`	`No eligible PayOut candidate was found for the requested destination.`	No payer serves this country, currency and filters. Check the catalogs.
`422`	`No PayOut quote could be calculated for the requested operation.`	No payer could quote this amount. Try another amount or payer, or contact Cashela.
`422`	`The selected pay_out_service_id is not valid.`	Use an `id` from Payout services.
`409`	`A quotation already exists for this external_identifier ...`	See Idempotency.
`503`	`Exchange rate is currently unavailable for this destination.`	Retry later.

Authentication errors are listed in the overview.

Get a quotation

GET/api/v1/pay-out/quotations/{reference}

Returns the same object as the create call. {reference} is the quotation reference (your external_identifier). An unknown reference returns 404 Quotation not found for this partner.

curl "https://sandbox-api.cashela.com/api/v1/pay-out/quotations/payout-2026-000123" \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Accept: application/json"

Preview without saving

POST /api/v1/pay-out/calculate takes the same body as a quotation (external_identifier is optional) and returns the quotes that the payers can offer, without creating a quotation. Use it to show an estimate before the user commits.

The response has status: "calculated", a selected_quote (the one Cashela would pick) and available_quotes. In each quote, read:

Field	Description
`pay_out_payer_id`	Payer of this quote.
`payer_name`	Payer name.
`amounts.send_amount`	Amount sent.
`amounts.receiving_amount`	Amount the beneficiary receives.
`amounts.amount_paid`	Amount taken from your wallet.
`fee.estimated_fee`	Fee.
`rate.platform_rate`	Exchange rate.

A preview does not reserve the rate. Create a quotation to fix it.

Next step

Execute the transaction with the quotation reference and one of the payers_available.