Referencia de la API/Pagos y retiros

Pagos y retiros

Un pago mueve fondos de tu saldo a un destinatario por un canal. Pasa un destinatario guardado o un teléfono, email o billetera en línea. source_amount o destination_amount. La cotización es opcional; sin ella el pago se valora al ejecutarse. Un retiro es un pago a una cuenta bancaria a nombre de tu empresa y requiere verificación del negocio. Los fallos transitorios se reintentan hasta tres veces; los de validación, destino, saldo y límite no.

Ciclo de vida del pago

Estado	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	obligatorio	Notas
recipient_id	string	opcional
recipient	InlineRecipient	opcional
channel	string	obligatorio
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.

Solicitud

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

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

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

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

idpathstringobligatorio

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	obligatorio	Notas
currency	enum: USD, EUR, MXN	obligatorio
payout_destination_id	string	obligatorio
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

Solicitud

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

Errores: 403 verification_required

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

idpathstringobligatorio

Respuesta 200

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

Obtén acceso

Construye contra el sandbox esta semana.

Cuéntanos los corredores que necesitas y a quién pagas. Las claves de sandbox las emite una persona.