Referência da API/Pagamentos e saques

Pagamentos e saques

Um pagamento move fundos do seu saldo para um destinatário por um canal. Passe um destinatário salvo ou um telefone, e-mail ou carteira inline. source_amount ou destination_amount. A cotação é opcional; sem ela o pagamento é precificado na execução. Um saque é um pagamento para uma conta bancária em nome da sua empresa e exige verificação do negócio. Falhas transitórias são repetidas até três vezes; falhas de validação, destino, saldo e limite não.

Ciclo de vida do pagamento

Status	Significado
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.

Parâmetros

Idempotency-Keyheaderstringopcional

Campo	Tipo	obrigatório	Observações
recipient_id	string	opcional
recipient	InlineRecipient	opcional
channel	string	obrigatório
quote_id	string	opcional
source_amount	Amount	opcional	Decimal string. Up to two decimals for fiat, six for USDC.
destination_amount	Amount	opcional	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	opcional
memo	string	opcional	Travels with the payment where the rail supports it.
message	string	opcional	Claim links only. Shown to the recipient.

Requisição

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

Resposta 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"
}

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

Exemplos: 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.

Parâmetros

idpathstringobrigatório

List payouts

GET/payouts

Parâmetros

statusqueryenum: pending, submitted, delivering, awaiting_claim, claimed, succeeded, failed, refunded, canceledopcional
channelquerystringopcional
sincequerystringopcional
limitqueryintegeropcional
cursorquerystringopcional

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.

Parâmetros

Idempotency-Keyheaderstringopcional

Campo	Tipo	obrigatório	Observações
currency	enum: USD, EUR, MXN	obrigatório
payout_destination_id	string	obrigatório
source_amount	Amount	opcional	Decimal string. Up to two decimals for fiat, six for USDC.
destination_amount	Amount	opcional	Decimal string. Up to two decimals for fiat, six for USDC.
reference	string	opcional

Requisição

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

Erros: 403 verification_required

Exemplos: 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

Parâmetros

idpathstringobrigatório

Resposta 200

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

Obtenha acesso

Construa contra o sandbox esta semana.

Conte-nos os corredores de que precisa e quem você paga. As chaves de sandbox são emitidas por uma pessoa.