Skip to main content
POST
Execute Payout
Execute a payout to credit a Quickei user’s wallet. Your merchant wallet is debited and the recipient’s wallet is credited instantly.

Parameters

You can execute a payout in two ways: using a quote_id from a previous quote, or by providing the lookup and amount parameters directly.
string
The quote ID from the Quote endpoint. If provided, the payout uses the locked exchange rate and fees from the quote. When using quote_id, you do not need to provide lookup_token, amount, sender_currency, or receiver_currency.
string
The token from the Lookup endpoint identifying the recipient. Required if quote_id is not provided.
number
Amount to send from your merchant wallet. Must be greater than 0. Required if quote_id is not provided.
string
ISO 4217 currency code of your merchant wallet (e.g. EUR). Max 10 characters. Required if quote_id is not provided.
string
ISO 4217 currency code of the recipient’s wallet (e.g. XAF). Max 10 characters. Required if quote_id is not provided.
string
required
Your internal reference for this payout (max 255 characters). Must be unique per merchant account.
string
required
A unique key (max 64 characters) to prevent duplicate payouts. If a payout with the same key already exists, the original payout is returned.
string
Optional description visible in the transaction history (max 500 characters).
Using a quote_id locks in the exchange rate and fees from the quote.

Without Quote ID (Direct)

If you skip the quote step, Quickei calculates the rate and fees at execution time.

Success Response 200

string
Unique payout identifier (format: PO + 8 random alphanumeric characters). Use this to check status via GET /payout/{id}.
string
Your internal reference as provided in the request.
number
The amount sent (before fees).
string
The sender currency code.
number
Total fee charged (fixed + percentage).
number
Total debited from your merchant wallet (amount + fee).
number
Applied exchange rate from sender to receiver currency.
number
Amount credited to the recipient’s wallet.
string
The recipient’s currency code.
string
Payout status: completed, pending, or failed.
string
Quickei internal transaction ID.
string
ISO 8601 timestamp when the payout was created.
string
ISO 8601 timestamp when the payout was processed. null if still pending.

Idempotency

The idempotency_key prevents duplicate payouts. If you send the same key twice:
  • The original payout is returned with "duplicate": true
  • No additional funds are moved
  • The response status is 200
Always include an idempotency_key. Without it, the request will be rejected (it is required). The reference must also be unique per merchant account — a duplicate reference will be rejected even with a new idempotency key.

Error Responses

Payouts are atomic. If any step fails (debit, credit, or ledger entry), the entire transaction is rolled back. Your merchant wallet is not debited and the recipient receives nothing. You can safely retry with the same idempotency_key.