Payouts

Quote and request payouts to beneficiaries and wallets; approval and dual signature.

Payouts let you withdraw your balance to bank beneficiaries or wallets. Your balance settles in USDT.

Payout statuses
  • pending_approval → dispatching: Approved
  • pending_approval → rejected: Rejected
  • dispatching → processing: Accepted by the provider
  • dispatching → pending: In provider review
  • dispatching → dispatch_unknown: Result unconfirmed
  • dispatching → failed: Failed
  • dispatch_unknown → dispatching: Verify
  • dispatch_unknown → processing: Accepted by the provider
  • dispatch_unknown → pending: In provider review
  • dispatch_unknown → failed: Failed
  • pending → processing: Accepted by the provider
  • pending → failed: Failed
  • processing → completed: Completed
  • processing → failed: Failed

Flow

  1. Check your balance and configuration (GET /balance, GET /payouts/config).
  2. Register the destination beneficiary or wallet.
  3. Get a quote with GET /payouts/quote.
  4. Create the payout with POST /payouts and an Idempotency-Key.
  5. Track it by webhook (payout.*) or with GET /payouts/{id}.
curl -X GET "$CLOBEPAY_API_BASE/balance" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "sellerId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
  "asset": "USDT",
  "available": "1250.00",
  "held": "0.00",
  "heldCount": 0,
  "pendingSettlement": "50.00",
  "pendingSettlementCount": 1,
  "informational": true,
  "custody": false,
  "asOf": "2026-11-19T18:00:00.000Z",
  "note": "Saldo informado; no representa custodia de fondos."
}

Approval and dual signature

  • Payouts created via API enter pending_approval, just like dashboard payouts.
  • Payouts above 1,000 USD require the merchant’s dual signature, without exception.
  • Creating payouts requires the payouts:write scope, which you include when creating the key, and is limited to 10 per minute.

Events

payout.created, payout.pending_approval, payout.approved, payout.rejected, payout.processing, payout.completed and payout.failed. See Webhooks.

Fields in the Payouts reference.