Execute Payout

Executes payout with confirmed amount from a pending transaction.

Authentication:

• REQUIRED: Basic Auth only. Body-based credentials are deprecated and not supported.

Key requirements:

• customer_id is required and must:

• be provided in request body,

• not contain /,

• exist under your account’s registered_customers, and

• match the customer_id bound to the transaction.

• Sender profile for execute is sourced from the registered customer record. You do not need to send sender in executePayout.

Flow:

1. X-Idempotency-Key header is required (unique per logical payout).

2. HMAC (when configured): If your account has signing_secret, send HMAC-SHA256 over JSON body (excluding signature) via X-Signature or body signature.

3. If idempotency key already has a successful stored 202 response, that response is replayed (with ownership/customer validation).

4. Loads transaction, validates account ownership, customer_id ownership, and PENDING status. An EXPIRED transaction returns 400 QUOTATION_EXPIRED (start again from decodeQr); any other non-PENDING status returns 400 TRANSACTION_NOT_PENDING. These checks run before schema validation and before any balance is locked.

5. Amount/currency lock: if transaction already has saved amount/currency, amount_confirmed and currency must match exactly.

6. partner_transaction_id: can be set once if empty; otherwise must be omitted or the same value.

7. Validates required fields from missing_fields: pass each one in the body (for example recipient_name when recipient.name was listed, and the amount as amount_confirmed). If any listed field is still missing you get 400 MISSING_REQUIRED_FIELDS with the field list, before any balance is locked.

8. API returns 202 Accepted (with status PROCESSING). Final status is completed by inbound webhook updates.

Request body:

• Required: tx_id, customer_id, amount_confirmed, currency

• Optional: partner_transaction_id

• Optional: recipient_name (only when decodeQr listed recipient.name in missing_fields; also accepted as recipient.name or nested recipient.name)

• sender is not required for execute (derived from registered customer profile).

Response (202 Accepted):

• status, tx_id, customer_id, message, exchange_rate, fee, percentage_fee, fixed_fee, amount, amount_usd, currency

• Optional: recipient, partner_transaction_id, updated_at

Precision:

• exchange_rate: 10 decimal places

• USD fields (fee, percentage_fee, fixed_fee, amount_usd): 2 decimal places

Error:

• Returns 404 if customer_id is not found under your account.

• Returns 403 when transaction ownership does not match account/customer.

LATAM: Payment lock is refreshed at execute to obtain a fresh payment lock code before settlement.