Transferencias

Cotiza y solicita retiros a beneficiarios y billeteras; aprobación y doble firma.

Con las transferencias retiras tu saldo a beneficiarios bancarios o a billeteras. La liquidación de tu saldo es en USDT.

Estados de una transferencia
  • pending_approval → dispatching: Aprobada
  • pending_approval → rejected: Rechazada
  • dispatching → processing: Aceptada por el proveedor
  • dispatching → pending: En revisión del proveedor
  • dispatching → dispatch_unknown: Resultado no confirmado
  • dispatching → failed: Fallida
  • dispatch_unknown → dispatching: Verificar
  • dispatch_unknown → processing: Aceptada por el proveedor
  • dispatch_unknown → pending: En revisión del proveedor
  • dispatch_unknown → failed: Fallida
  • pending → processing: Aceptada por el proveedor
  • pending → failed: Fallida
  • processing → completed: Completada
  • processing → failed: Fallida

Flujo

  1. Consulta tu saldo y la configuración (GET /balance, GET /payouts/config).
  2. Da de alta el beneficiario o la billetera de destino.
  3. Cotiza con GET /payouts/quote.
  4. Crea la transferencia con POST /payouts y una Idempotency-Key.
  5. Sigue su estado por webhook (payout.*) o con GET /payouts/{id}.
curl -X GET "$CLOBEPAY_API_BASE/balance" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

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

Aprobación y doble firma

  • Las transferencias creadas por API entran en pending_approval, igual que las del panel.
  • Las de más de 1,000 USD requieren doble firma del comercio, sin excepción.
  • Crear transferencias exige el scope payouts:write, que debes incluir al crear la llave, y tiene un límite de 10 por minuto.

Eventos

payout.created, payout.pending_approval, payout.approved, payout.rejected, payout.processing, payout.completed y payout.failed. Ver Webhooks.

Campos en la referencia de Transferencias.