API reference/Payments and withdrawals

Payments and withdrawals

A payout moves funds from your balance to one recipient on one channel. Pass a saved recipient or an inline phone, email or wallet. Either source_amount or destination_amount. A quote is optional; without it the payout is priced at execution. A withdrawal is a payout to a bank account in your own company’s name and requires business verification. Transient failures retry up to three times; validation, destination, balance and limit failures do not.

Payout lifecycle

Status	Meaning
pending	Accepted, not yet handed to a rail
submitted	Funds committed on-chain and handed to the rail
delivering	Rail accepted and is delivering
awaiting_claim	Claim links only: recipient notified, funds held
claimed	Recipient claimed and chose a method
succeeded	Delivered; destination amount and provider reference are final
failed	Not delivered; failure.code explains why
refunded	Delivery failed after funds left; balance restored
canceled	Canceled before submission, or an unclaimed link returned

Create a payout

POST/payouts

One transfer to one recipient on one channel. Pass a saved recipient_id or an inline recipient. Either source_amount or destination_amount. quote_id is optional; without it the payout is priced at execution.

Parameters

Idempotency-Keyheaderstringoptional

Field	Type	required	Notes
recipient_id	string	optional
recipient	InlineRecipient	optional
channel	string	required
quote_id	string	optional
source_amount	Amount	optional	Decimal string. Up to two decimals for fiat, six for USDC.
destination_amount	Amount	optional	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	optional
memo	string	optional	Travels with the payment where the rail supports it.
message	string	optional	Claim links only. Shown to the recipient.

Request

{
  "recipient_id": "rcp_9d1a",
  "channel": "spei_mxn",
  "quote_id": "qt_5m2n",
  "source_amount": "1000.00",
  "reference": "INV-2026-0912",
  "memo": "Freight, week 37"
}

Response 201

{
  "id": "po_1b7e",
  "status": "submitted",
  "channel": "spei_mxn",
  "recipient_id": "rcp_9d1a",
  "source_amount": "1000.00",
  "source_currency": "USDC",
  "destination_amount": "16865.35",
  "destination_currency": "MXN",
  "rate": "16.86535",
  "fees": {
    "provider": "0.50",
    "decaf": "5.00",
    "total": "5.50",
    "currency": "USDC"
  },
  "reference": "INV-2026-0912",
  "estimated_arrival": "2026-09-16T15:20:00Z",
  "provider_reference": null,
  "attempts": 1,
  "created_at": "2026-09-16T15:01:12Z"
}

Errors: 400 validation_error, channel_unavailable, amount_out_of_range; 402 insufficient_balance; 409 idempotency_conflict; 410 quote_expired

Examples: Create a payout

curl -X POST https://sandbox.api.decaf.so/v1/payouts \
  -H "Authorization: Bearer $DECAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"recipient_id":"rcp_9d1a","channel":"spei_mxn","quote_id":"qt_5m2n","source_amount":"1000.00","reference":"INV-2026-0912","memo":"Freight, week 37"}'

Get a payout

GET/payouts/{id}

Includes an attempts array with timing, status and provider error per attempt.

Parameters

idpathstringrequired

List payouts

GET/payouts

Parameters

statusqueryenum: pending, submitted, delivering, awaiting_claim, claimed, succeeded, failed, refunded, canceledoptional
channelquerystringoptional
sincequerystringoptional
limitqueryintegeroptional
cursorquerystringoptional

Withdraw to your own bank

POST/withdrawals

Requires business verification. Uses a saved payout destination in your company name. Provide source_amount or destination_amount.

Parameters

Idempotency-Keyheaderstringoptional

Field	Type	required	Notes
currency	enum: USD, EUR, MXN	required
payout_destination_id	string	required
source_amount	Amount	optional	Decimal string. Up to two decimals for fiat, six for USDC.
destination_amount	Amount	optional	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	optional

Request

{
  "currency": "EUR",
  "payout_destination_id": "pd_3c9f",
  "source_amount": "5000.00"
}

Errors: 403 verification_required

Examples: Withdraw to your own bank

curl -X POST https://sandbox.api.decaf.so/v1/withdrawals \
  -H "Authorization: Bearer $DECAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"currency":"EUR","payout_destination_id":"pd_3c9f","source_amount":"5000.00"}'

Shareable receipt

GET/payouts/{id}/receipt

Parameters

idpathstringrequired

Response 200

{
  "url": "https://decaf.so/r/t_8f2a",
  "confirmed_received_at": null
}

Get access

Build against the sandbox this week.

Tell us the corridors you need and the recipients you pay. Sandbox keys are issued by a person.