Fiat Payouts API

Rolling out. Local-currency payout rails are being enabled progressively through licensed payout partners. In production these endpoints return 503 provider_unavailable until your organization's payout corridor is switched on. The contract below is stable — integrate against it now. See the flow of funds.

A fiat payout sends local currency to a beneficiary through a licensed payout partner. It is funded from your organization's USDC balance — the same balance your collections settle into. Caibo screens the payout, converts from your balance, and the partner credits the beneficiary's local account.

The supported destination countries and the beneficiary fields each one requires are returned by the catalog (GET /v1/countries, GET /v1/payment-methods) — they are not hard-coded here.

Create a fiat payout

POST /v1/fiat-payouts — Scope: payouts:write

Creates a fiat payout and starts its lifecycle: it is screened, then (if it clears and is within the auto-approval limit) sent to the payout partner for delivery.

Headers

Body parameters

beneficiary.account is intentionally open: a country may require account_number + institution + document_id, another an IBAN or a CLABE. Query the catalog for the exact required fields per country before you build the form.

Request

curl https://api.caiboglobal.com/v1/fiat-payouts \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f" \
  -d '{
    "amount": "250000.00",
    "currency": "COP",
    "country": "CO",
    "beneficiary": {
      "name": "Maria Gomez",
      "account": {
        "type": "bank_account",
        "institution": "007",
        "account_number": "1234567890",
        "document_id": "CC-79000000"
      }
    },
    "metadata": { "invoice_id": "INV-2043" }
  }'

The example country/currency above is illustrative. Use the values returned by GET /v1/countries for corridors enabled on your organization.

Response — 201 Created

Returns the fiat payout. beneficiary.account.account_number is masked in responses. If the amount exceeds your auto-approval limit, the status is pending_approval and the HTTP status is 202 Accepted instead of 201.

{
  "id": "fpo_9a8b7c6d5e4f",
  "object": "fiat_payout",
  "status": "processing",
  "mode": "live",
  "amount": "250000.00",
  "currency": "COP",
  "country": "CO",
  "beneficiary": {
    "name": "Maria Gomez",
    "account": { "type": "bank_account", "institution": "007", "account_number": "******7890" }
  },
  "screening_status": "clear",
  "tracking": { "reference": "CAI-FP-9A8B7C6D", "estimated_settlement": "2026-07-23T18:00:00Z" },
  "metadata": { "invoice_id": "INV-2043" },
  "created_at": "2026-07-23T14:03:00Z"
}

Behavior

• Funded from your balance. The payout draws from your organization's USDC balance (the settlement rail). If the balance is below the required amount, it returns 402 insufficient_balance.
• Screening runs first, in-line. The beneficiary is screened before anything is sent. A flagged beneficiary yields 403 screening_blocked and a payout with status blocked; no funds move. See Compliance & screening.
• Auto-approval. Amounts within your organization's auto-approval limit send immediately; larger ones return 202 with status pending_approval and wait for a manual approval.
• Idempotent. Reusing the Idempotency-Key with the same body returns the original payout; with a different body it returns 409 idempotency_conflict.
• Webhooks. A successful create fires fiat_payout.processing and finally fiat_payout.completed (or fiat_payout.failed with a refund). A blocked payout fires fiat_payout.blocked.

Errors

Fiat payout state machine

A fiat payout moves through the same shape as a stablecoin payout: screened, then delivered.

pending ──▶ screening ──▶ processing ──▶ completed   (beneficiary credited)
                │              │
                ▼              ▼
             blocked        failed  (funds refunded to your balance)

(cancel is possible up to — but not during — processing) ──▶ cancelled

Webhooks

Register for these on your webhook endpoints. Each delivery is signed with Caibo-Signature; verify it as described in the Webhooks guide.

{
  "event": "fiat_payout.completed",
  "object": "fiat_payout",
  "id": "fpo_9a8b7c6d5e4f",
  "status": "completed",
  "amount": "250000.00",
  "currency": "COP",
  "country": "CO",
  "mode": "live",
  "created_at": "2026-07-23T14:03:00Z"
}

The webhook payload is a snapshot. For anything critical, re-fetch the fiat payout with GET /v1/fiat-payouts/{id} to confirm its current state.

Retrieve a fiat payout

GET /v1/fiat-payouts/{id} — Scope: payouts:read

Fetches a single fiat payout by id. Returns 404 resource_missing if it doesn't exist or isn't yours.

curl https://api.caiboglobal.com/v1/fiat-payouts/fpo_9a8b7c6d5e4f \
  -H "X-API-Key: $CAIBO_API_KEY"

Errors

List fiat payouts

GET /v1/fiat-payouts — Scope: payouts:read

Returns your organization's fiat payouts, newest first, cursor-paginated.

Query parameters

Request

curl "https://api.caiboglobal.com/v1/fiat-payouts?limit=25&status=completed" \
  -H "X-API-Key: $CAIBO_API_KEY"

Response — 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "fpo_9a8b7c6d5e4f",
      "object": "fiat_payout",
      "status": "completed",
      "mode": "live",
      "amount": "250000.00",
      "currency": "COP",
      "country": "CO",
      "created_at": "2026-07-23T14:03:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "fpo_9a8b7c6d5e4f"
}

Errors