Référence API/Paiements et retraits

Paiements et retraits

Un paiement déplace des fonds de votre solde vers un bénéficiaire sur un canal. Passez un bénéficiaire enregistré ou un téléphone, e-mail ou portefeuille en ligne. source_amount ou destination_amount. Le devis est facultatif ; sans lui, le paiement est tarifé à l’exécution. Un retrait est un paiement vers un compte bancaire au nom de votre entreprise et requiert la vérification de l’entreprise. Les échecs transitoires sont réessayés jusqu’à trois fois ; ceux de validation, de destination, de solde et de limite ne le sont pas.

Cycle de vie du paiement

Statut	Signification
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.

Paramètres

Idempotency-Keyheaderstringfacultatif

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

Requête

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

Réponse 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"
}

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

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

Paramètres

idpathstringobligatoire

List payouts

GET/payouts

Paramètres

statusqueryenum: pending, submitted, delivering, awaiting_claim, claimed, succeeded, failed, refunded, canceledfacultatif
channelquerystringfacultatif
sincequerystringfacultatif
limitqueryintegerfacultatif
cursorquerystringfacultatif

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.

Paramètres

Idempotency-Keyheaderstringfacultatif

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

Requête

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

Erreurs: 403 verification_required

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

Paramètres

idpathstringobligatoire

Réponse 200

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

Obtenir l’accès

Développez sur le sandbox dès cette semaine.

Dites-nous les corridors dont vous avez besoin et qui vous payez. Les clés sandbox sont délivrées par une personne.