API reference

Send a payout

Send money to your beneficiaries from your payout balance. Separate environment from pay-in: you fund it, optionally swap to local currency, and send the payout.

POST/api/v1/me/payout/send

Step-by-step guideStep 1 of 3

Select a stage to see what happens.

Your integration

Request readyIllustrative example

POST/me/payout/send

Authorization: Bearer ••••••••
Accept: application/json

Prepare the request

Use credentials for the selected environment and complete the required parameters.

Illustrative flow · no data is sent

How this endpoint works

Creates one payout under a required Idempotency-Key. The Bearer token identifies the shop; amount is in the method currency. Returns processing, completed or failed. Signed provider notifications and status reconciliation update the payout. A partial return sets partially_refunded and exposes cumulative refundedAmount; only that returned principal is credited. A full return credits the remaining principal and original fee once. Only explicit sbx_po_* methods are synthetic and do not debit funds.

Server-side authentication

Authentication guide

Request parameters

Expand a field to see its format and requirements.

payoutMethodIdinteger

Recommended: stable numeric ID from GET /api/v1/me/payout/methods. Send this or legacy methodId; both must agree if provided.

methodIdstring | integer

Compatibility alias: the old catalog id or the numeric payoutMethodId. Existing integrations continue working.

amountnumberRequired

Amount in the method's currency. >0, ≤ your balance in that currency.

recipientobject

Destination data (account, name, …).

Integration details

Currency, behavior and additional notes for this operation.

Context and key considerations

The payout environment is independent from pay-in. Use the numeric payoutMethodId from the authenticated methods catalog. Pay-in IDs are different. The flow:

Fund — POST /api/v1/me/payout/transfer moves USD from your pay-in balance to payout (atomic).
Swap (optional) — POST /api/v1/me/payout/swap converts USD→local currency at the current rate.
Send — POST /api/v1/me/payout/send debits your balance in the method's currency and creates the payout.

Check your balance per currency at GET /api/v1/me/payout/balance and the rails at GET /api/v1/me/payout/methods.

Validations and errors:

payout_dispatch_failed (422) — a confirmed rejection reversed the debit. Save details.payoutId and details.failureReason. The key remains bound to that failed payout. After confirming its final status, use a new key for a new, corrected payout.
payout_method_unavailable (422) — the methodId doesn't exist. List the methods at GET /api/v1/me/payout/methods.
currency_not_funded (422) — you have no balance in the method's currency. Do a USD→that-currency swap first.
balance_insufficient (422) — the amount exceeds your balance in that currency. The response carries details.availableUsd and details.shortfallUsd.
amount_invalid (422) · invalid_request (400) · rate_limited (429).

Idempotency-Key is required (1–200 characters). Store one key per intended payment and reuse the exact body for retries. A timeout or server error does not prove failure: retain the key and query GET /api/v1/me/payout/request with that header. A 404 can mean the original request is still in flight; retry with the same key. Never generate a new key to resolve an unknown result. A changed committed body returns 409. Keys are isolated by merchant, authenticated shop and environment.

Beneficiary data (recipient) — discover the fields per method. Each method in GET /api/v1/me/payout/methods now carries recipientFields — the EXACT fields to send for that rail (key, label, required, type, and options for bank selectors). Read it and you never guess. The shapes by rail:

Every method has its own contract: use its current recipientFields, including required fields, exact select values and help. Name, ID, phone and email requirements differ between bank and wallet methods. Respect minRequestLocal, maxRequestLocal and amountStep; the balance must cover amount plus your fees.
SPEI (MX): account = CLABE (exactly 18 digits) · bankCode auto-derived from the CLABE (don't send it) · documentType RFC|CURP.
PIX (BR): account = PIX key (CPF, CNPJ, email, phone or EVP) · accountType = the key type · documentId = CPF (11) or CNPJ (14).
Bank — Colombia / Chile / Peru: bankCode is a SELECTOR — send one of the exact codes in the method's recipientFields[bankCode].options (e.g. Colombia Bancolombia 1007, Peru BBVA 0001). Peru account = CCI (20 digits), not the account number. accountType = SAVINGS|CHECKING.
Bank — Argentina: use the account, bank, ID and contact fields returned for your assigned method; alias/CBU/CVU requirements depend on the route.
BreB (Colombia): account is the registered key (up to 64 characters), with name and document fields. No bank or bank-account type is required.
Wallets (Nequi/Yape/Plin/Vita/…): use the method's phone or email format; these are not interchangeable. PayPal uses the beneficiary email. Cash collection requires the beneficiary identity and phone, followed by the collection-instructions endpoint.

Local validation rejects malformed data before debiting. A confirmed provider rejection reverses the debit; an unknown result stays processing while its status is reconciled.

In this guide1 / 4

Confirm QR payouts

For a method whose subtype is qrcode, POST /api/v1/me/payout/qr-preview with { payoutMethodId, account, amount } (the legacy methodId remains accepted). Display the returned preview.name, bank, document, currency and confirmedAmount for confirmation. Use that confirmed amount and send recipient.account unchanged plus recipient.qrToken = preview.token to the send endpoint. The token expires after 60 seconds and is single-use. If the send result is unknown, recover it by the original Idempotency-Key before retrieving another QR.

Testing payouts in sandbox

Sandbox payouts do NOT auto-settle and the Sandbox-Simulate header is pay-in only — it does NOT affect payouts. The POST /api/v1/me/payout/send/{id}/simulate endpoint is the completion signal: you drive each payout to its terminal status yourself. There are two ways to test:

End-to-end flow (fund a real sandbox balance):

Discover — GET /api/v1/me/payout/currencies to see which currencies you can fund + pay out in (each with its rails + `funded` flag). In sandbox this includes the synthetic test currencies.
Fund — POST /api/v1/me/payout/fund-sandbox with { currency, amount } credits your pay-out available balance in that currency with test money (no pay-in / transfer / swap needed). Sandbox only.
Send — POST /api/v1/me/payout/send with a real rail (e.g. 20042) debits that balance and creates the payout in processing.
Complete / fail — POST /api/v1/me/payout/send/{id}/simulate with { action } drives it to completed (or fails it and reverses the debit). This runs the same money logic a real provider webhook would.

bash

# 1) Fund the sandbox pay-out balance (test money — sandbox only):
curl -X POST https://sandbox.key2pay.ai/api/v1/me/payout/fund-sandbox \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "MXN", "amount": 5000 }'
# → { "currency": "MXN", "amount": 5000,
#     "balances": [ { "currency": "USD", "available": 0, "pending": 0, "reserved": 0 },
#                   { "currency": "MXN", "available": 5000, "pending": 0, "reserved": 0 } ] }

# 2) Send a payout from that balance (lands as "processing"):
curl -X POST https://sandbox.key2pay.ai/api/v1/me/payout/send \
  -H "Idempotency-Key: sandbox-payout-order-001" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "methodId": "20042", "amount": 1850,
        "recipient": { "account": "012180012345678901", "name": "Juan Perez", "documentType": "CURP", "documentId": "PEPJ900101HDFRRN09" } }'
# → { "payout": { "id": "po-202606-ab12cd34", "status": "processing", … } }

# 3) Complete it (the completion signal — sandbox payouts don't auto-settle):
curl -X POST https://sandbox.key2pay.ai/api/v1/me/payout/send/po-202606-ab12cd34/simulate \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "completed" }'
# → { "payout": { "id": "po-202606-ab12cd34", "status": "completed",
#       "completedAt": "2026-06-27T18:00:00.000Z", … } }

# Drive a failure instead (reverses the debit back to your balance):
curl -X POST https://sandbox.key2pay.ai/api/v1/me/payout/send/po-202606-ab12cd34/simulate \
  -H "Authorization: Bearer <accessToken>" \
  -d '{ "action": "failed" }'

Quick status testing (no funding): in sandbox, GET /api/v1/me/payout/methods prepends synthetic test rails (90001, 90002, 90003, 90004) — 4 countries. A payout created with an sbx_po_* id is SYNTHETIC: it lands in processing with NO balance debit and no real provider, so you don't even need to fund first. Then move it to any status with POST /api/v1/me/payout/send/{id}/simulate.

Simulate actions: completed / paid → completed · failed / rejected / refunded / returned → failed (the debit is reversed on a real-debited payout) · processing → no-op. Both endpoints are sandbox-only — they return fund_sandbox_only / simulate_sandbox_only (400) in production.

Payout webhooks: a payout reaching a terminal state fires an outbound webhook — payout.completed (beneficiary paid) or payout.failed (debit reversed, payload includes failureReason). These fire on the real provider webhook in production and when you drive a payout via simulate in sandbox, so you can test the full notification end-to-end. Subscribe on POST /webhooks with ["payout.completed","payout.failed"] (or ["*"]). Subscribe to payout.partially_refunded for partial returns; refundedAmount is cumulative. Recover missing or delayed notifications by polling GET /api/v1/me/payout/send/{id}. A missing notification is never a reason to send another payout.

CODE EXAMPLESIllustrative

bash

curl -X POST "https://sandbox.key2pay.ai/api/v1/me/payout/send" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Idempotency-Key: po-001" \
  -H "Content-Type: application/json" \
  -d '{ "payoutMethodId": 20001, "amount": 1850, "recipient": { "account": "012180012345678901", "name": "Juan Perez", "documentType": "CURP", "documentId": "PEPJ900101HDFRRN09" } }'

json

{
  "payout": {
    "id": "po-202606-ab12cd34",
    "payoutMethodId": 20001,
    "methodId": "20001",
    "methodName": "SPEI",
    "currency": "MXN",
    "amount": 1850,
    "status": "processing",
    "environment": "sandbox",
    "createdAt": "2026-06-20T18:00:00.000Z",
    "completedAt": null
  },
  "methodName": "SPEI",
  "logoUrl": "https://api.key2pay.ai/api/payment-method-logo/payout_spei?v=2026-07-04T00:00:00.000Z",
  "iconUrl": "https://api.key2pay.ai/api/payment-method-logo/payout_spei?v=2026-07-04T00:00:00.000Z"
}

Example response. No request was sent.