Payout
Quick Reference
What is a payout
A payout is the outbound flow — money leaving the platform, the inverse of a charge. Instead of collecting money from a payer, you send money from a wallet to a beneficiary. A single endpoint handles every payment rail; the type_payout field selects which one.
| Feature | Detail |
|---|---|
| Direction | Outbound (disbursement) |
| Funding | Debited from a wallet (wallet_uuid) |
| Rails | PIX, TED, SPEI, LATAM bank transfer, cash pickup |
| Markets | Brazil, Mexico, and LATAM (Argentina, Chile, Colombia, Peru, Ecuador, Guatemala, Honduras) |
| Idempotency | Per wallet via transaction_reference |
| Confirmation | Asynchronous via webhook |
Payout rails
type_payout | Destination object | Typical markets |
|---|---|---|
pix | pix_destination | Brazil |
ted | bank_destination | Brazil |
spei | bank_destination | Mexico |
bank_transfer | bank_destination | LATAM |
cash_pickup | cash_destination | Ecuador and cash networks |
How it works
Merchant creates payout
Your server calls POST /api/v1/bank/wallet/payout/ with wallet_uuid, type_payout, value, description, and the matching destination object.
A55 validates and routes
A55 validates the payload, checks the wallet balance, and routes to an eligible provider.
Provider sends the funds
The provider transfers the funds to the beneficiary's account (or generates a pickup code for cash payouts).
Webhook confirms the outcome
A55 sends a webhook to your webhook_url when the payout reaches a final status (realized, returned, error, etc.).
Payout flow
Payout lifecycle
| Status | Description |
|---|---|
| pending | Created, awaiting processing |
| issued | Sent to the provider |
| realized | Confirmed and settled |
| returned | Returned by the receiving bank |
| canceled | Canceled |
| error | Failed during processing |
| expired | Expired |
The synchronous response returns the initial status. A payout typically moves from issued to realized asynchronously. Set webhook_url and rely on the webhook for the final outcome.
Idempotency
Payouts are idempotent per wallet via transaction_reference. If you omit it, A55 generates one. Reusing the same reference for the same wallet is rejected with errors.wallet.payout_already_exists, which protects you from sending a duplicate payout on retries.
Provider routing and failover
A55 selects an eligible provider for the chosen rail and currency based on internal rules (capability, balance, and account configuration). If the first provider fails, the orchestrator can try the next eligible provider automatically before marking the payout as error.
API reference
The full request and response schemas, error codes, and per-rail examples live in the API reference:
| Operation | Endpoint |
|---|---|
| Create payout | POST /api/v1/bank/wallet/payout/ |
| List payouts | GET /api/v1/bank/wallet/payout/ |
| Get payout | GET /api/v1/bank/wallet/payout/{payout_uuid}/{wallet_uuid}/ |
| Payout webhook | Notification to your webhook_url |