Pay-Out overview

The Pay-Out API lets your business send money to beneficiaries abroad. You quote a payout, choose a payer (the bank, wallet or cash network that delivers the money), and execute it. The amount is taken from your Cashela wallet; no card or bank payment is involved.

How it works

Discover where you can send money: countries, services and payers.
Quote: create a quotation. It fixes the amounts, the rate and the fee for 30 minutes and lists the payers that can deliver it.
Execute: execute the transaction with the beneficiary details and one of the payers from the quotation. When Pay-Out is active for your account, Cashela reserves the amount in your wallet and starts the payout.
Track: receive a signed notification at your callback_url and query the transaction status at any time.

See the flow diagram for the full sequence.

Availability

Pay-Out is available per account, under activation: Cashela enables it for your account once your onboarding is complete. Until it is active, quoting and discovery work, but executing a transaction answers 503 with the code PARTNER_PAYOUT_DISBURSEMENT_UNAVAILABLE. No funds are reserved and the quotation stays valid until it expires, so you can retry the same call once Cashela confirms activation. See Errors.

Before you start

A Cashela Business account.
An API key and API secret created in the Developer Portal of your Cashela Business dashboard. See Get started. The key must have pay-out access; if it does not, the API answers 403 Insufficient permissions. and you should contact Cashela.
An active wallet in the currency you will send from, with enough balance. The source.currency of a quotation must be one of your wallet currencies.

Authentication

Pay-Out uses the same HTTP Basic authentication as Pay-In: username = your api_key, password = your api_secret. See Authentication for details, IP whitelists and authentication errors.

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

Response	Meaning
`401` `Unauthorized.`	Missing or wrong credentials, credentials of the other environment, or a disabled or revoked key.
`403` `IP address is not allowed.`	The key has an IP whitelist and the request came from another address.
`403` `Insufficient permissions.`	The key is not allowed to use Pay-Out.
`403` `The partner account is not active.`	Your business account is not active. Contact Cashela.
`429`	Too many requests. Wait the seconds in the `Retry-After` header.

Environments

Environment	Base URL
Sandbox	`https://sandbox-api.cashela.com`
Production	`https://production-api.cashela.com`

Use the key from the matching card (Sandbox or Production) of the Developer Portal. All Pay-Out paths start with /api/v1/pay-out/.

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/pay-out/countries`	Destination countries
`GET`	`/api/v1/pay-out/services`	Payout services
`GET`	`/api/v1/pay-out/payers`	Payers
`POST`	`/api/v1/pay-out/calculate`	Preview a quote without saving it
`POST`	`/api/v1/pay-out/quotations`	Create a quotation
`GET`	`/api/v1/pay-out/quotations/{reference}`	Get a quotation
`POST`	`/api/v1/pay-out/transactions/{reference}`	Execute a transaction
`GET`	`/api/v1/pay-out/transactions/{reference}`	Get a transaction
`POST`	`/api/v1/pay-out/transactions/{reference}/callback`	Re-send the notification

Request and response format

Send JSON with Content-Type: application/json and Accept: application/json. Every response uses the same envelope:

{
  "success": true,
  "data": { },
  "message": "Quotation created successfully."
}

Errors return success: false and a message. Validation errors return 422 with the invalid fields in errors:

{
  "success": false,
  "message": "Validation failed.",
  "errors": {
    "source.currency": ["The source currency is not available in the authenticated owner main wallets."]
  }
}

Send an optional X-Trace-Id header (a UUID works well) on every request and log it; quote it to support together with your external_identifier.

Idempotency

Your external_identifier is the idempotency key of a payout:

Creating a quotation again with the same external_identifier and the same body returns the existing quotation instead of creating a new one.
Executing the same quotation again with the same body returns the existing transaction.
Reusing an external_identifier with a different body returns 409.

You can also send an Idempotency-Key header; it is stored with the quotation and the transaction and returned in the idempotency object.