Saltar al contenido principal
Cambio incompatible — 2026-11-13. Los saldos BOB, MXN, ARS y CLP, junto con los espejos BANK_*, viven solo en Banking. Los payouts, swaps, transferencias internas, tarjetas, checkout, POS y comisiones de la plataforma rechazan la liquidación fiat con HTTP 400. Las cuentas legacy conservan su default explícito USDT; las cuentas nuevas usan USD como saldo principal. Usa Banking para las operaciones fiat.
Un payout envía dinero en moneda local a una cuenta bancaria del país destino. El monto se convierte al saldo predeterminado de tu cuenta con la tasa de tu cuenta (la de GET /v1/rates) y se descuenta de ese saldo el equivalente reportado más la comisión fija, si está configurada. Las cuentas legacy con default USDT explícito siguen descontando USDT. Así se ve el ciclo completo, incluido qué pasa con tu saldo en cada paso:

1. Descubre los corredores disponibles

Los países, monedas y métodos disponibles los define CBPay. Consúltalos siempre por catálogo:
Corredores y métodos disponibles: La disponibilidad puede variar; el catálogo (GET /v1/payouts/methods) es siempre la fuente de verdad. Si un país tiene un solo método, method es opcional. Todos los métodos se cobran igual: tu tasa + fijo. Para transferencias bancarias necesitas además el catálogo de bancos (de ahí sale el bank_code del beneficiario):

2. Crea el payout

beneficiary es un objeto de pares clave/valor cuyos campos requeridos dependen del corredor (RUT y banco en Chile, CLABE en México, CCI en Perú, llave PIX en Brasil, etc.). El catálogo de métodos documenta los campos de cada uno.
Cada payout guarda al beneficiario como contacto automáticamente ("save_contact": false para no guardarlo). Para repetirle un pago sin re-tipear sus datos, envía "beneficiary_contact_id" en vez de beneficiary — se usa su beneficiario guardado más reciente para ese país y método (422 no_saved_destination si no tiene).
Respuesta 202 Accepted:
En ese momento tu saldo ya refleja el débito: total_debit pasó de available a held (en el saldo del settlement_asset).

Payouts de remesa US/USD

Para un payout wire o swift en USD hacia Estados Unidos, configura options.is_remittance con el string "true" cuando pagas a nombre de un tercero. Esta opción solo se admite en US/USD wire y swift; se rechaza en ach y se ignora en los demás rieles.
Respuesta 202 Accepted:
El operador selecciona el Ultimate Debtor desde la lista bancaria viva antes de liberar el payout. Si no se selecciona un debtor, el payout vuelve a la cola en vez de liberarse sin esa información. El debtor lo elige el operador; el integrador no lo envía. No reenvíes el payout para cambiarlo: lee el recurso existente y conserva la misma idempotency key.
No envíes is_remittance como booleano JSON. El valor aceptado es el string "true". Un payout ach con esta opción devuelve 400; la opción se ignora en rieles distintos de US/USD wire y swift.
bank_reference — el id propio del banco para la transferencia. En US ACH, wire y SWIFT es la referencia CBF que vuelve de inmediato al crear (el payout sigue processing hasta que el banco confirma). En el resto de corredores queda vacio ("") hasta completed. Mientras el payout está en curso viene vacío (""); cuando el payout queda completed, lleva el id de transacción asignado por el banco/rail de destino. Es el valor que el beneficiario puede usar para cruzar el pago con su banco, y también aparece en el webhook payout_status_changed, el comprobante PDF, el export CSV de payouts y la cartola. Las respuestas, CSV, webhooks y comprobantes también incluyen uetr (UETR/SWIFT gpi) e imad (wire/ACH doméstico), vacíos hasta que el banco los reporte; usa el tracker público para el estado vivo y el mismo comprobante.

Pagar desde otro saldo (settlement_asset)

Por defecto el débito sale de USD; usa PUT /v1/settlement para cambiarlo. Para pagar una operación puntual desde otro saldo, agrega settlement_asset al request. Ejemplo: un payout de 100,000 CLP pagado desde el saldo BTC pasa por cuatro transformaciones, todas registradas en la respuesta:
  1. CLP → USDT a tu tasa: 100000 / 950.25 = 105.235465 USDT.
  2. + comisión fija: 105.235465 + 0.30 = 105.535465 USDT (total_debit).
  3. USDT → BTC al precio efectivo de settlement (settlement_rate 109029.34070000): 105.535465 / 109029.3407 = 0.00096795 BTC (redondeo hacia arriba al satoshi).
  4. Débito y hold en BTC: settlement_amount 0.00096795 sale de tu saldo BTC; el beneficiario recibe sus 100,000 CLP igual que siempre.
Si el payout falla, se reembolsa el settlement_amount exacto a tu saldo BTC — nunca se re-cotiza. Si el precio de ejecución de BTC/GOLD/SILVER/PLATINUM no está disponible en ese momento recibirás 503 pricing_unavailable, y los assets volátiles tienen un límite por operación (422 settlement_limit_exceeded; consúltalo en GET /v1/settlement). Para settlement BOB, MXN o ARS en la misma moneda, consulta Settlement de payouts fiat.

El screening técnico puede quedar pendiente

CBPay screenea al beneficiario antes de debitar tu saldo o llamar al core. Si el servicio de screening está temporalmente no disponible y la cola técnica de screening está disponible, el payout se persiste y el create responde 202 Accepted con el recurso en status: "pending":
Mientras está pendiente no hay débito, hold, asiento en el ledger, despacho al core ni receipt_url. El replay con la misma clave de idempotencia devuelve el mismo payout con idempotency_hit: true; nunca crea una segunda operación. Cuando el worker recibe process, el payout existente sigue el flujo normal de débito y despacho. Un hold válido entra al firewall transaccional. Un rejected posterior termina el payout en failed sin débito. Después de aceptar process, el mismo payout puede permanecer en status: "pending" mientras se reconcilian el débito y el despacho. La API y el webhook payout_status_changed exponen estos códigos de transición durables:
  • compliance_dispatch_pending: el screening pasó, existe el débito/hold y funds_debited: true, pero el despacho al core aún no terminó.
  • compliance_dispatching: el claim de despacho está en curso.
  • core_unreachable: el despacho o la liquidación local es ambiguo y espera conciliación; no crees un segundo payout.
Estas transiciones no son una operación nueva. Conserva la misma idempotency_key, lee el payout y espera el siguiente evento de estado. Cuando el payout termina, completed consume el hold y failed devuelve el débito exacto. Los eventos finales usan el camino durable e incluyen los campos normales del comprobante. La respuesta técnica compliance_check_unavailable sigue aplicando cuando el payout no se puede dejar en la cola pendiente y en los flujos que no tienen esta cola. No reemplaza los contratos actuales de validación, seguridad ni compliance_hold.

Un fallo antes del débito no es un reembolso

Si el screening o un control duro de compliance falla antes de iniciar el camino de débito, el mismo payout puede terminar failed con predebit_failure: true y funds_debited: false. La respuesta y su evento payout_status_changed omiten receipt_url, porque no hubo débito, hold ni comprobante que revertir. Es distinto de un failed posterior al débito, donde el débito exacto se reembolsa antes del evento terminal. Para conocer el origen de la tasa y las cotizaciones FIFO indicativas, revisa Orígenes de tasa de payouts y cotizaciones FIFO.

Argentina: resuelve un alias bancario antes de pagar

Resuelve y confirma el titular antes de crear el payout (10 consultas/minuto/cuenta). Request: GET /v1/payouts/ar-alias/resolve?alias=julieta.fernandez. Respuesta: {"alias":"julieta.fernandez","account_number":"2850590940090418135201","account_type":"CBU","tax_id":"27234567891","holder_name":"Julieta Fernandez"}. Crea POST /v1/payouts con account_number igual al alias original y el tax_id/name devueltos; el dispatch lo vuelve a resolver y registra destination_alias en la evidencia. alias_unresolvable es determinista y beneficiary_lookup_unavailable temporal. Consulta Errores.

3. Recibe el estado final

Suscríbete al evento payout_status_changed (webhooks):
  • completed: el dinero llegó; el hold se consume.
  • failed: se reembolsa el débito completo automáticamente (payout_refund en tu ledger).
status_message es el detalle opcional y normalizado que acompaña a status_code; puede venir vacío cuando el core no tiene un mensaje adicional. También puedes consultar en cualquier momento:

Estados del payout

Consulta e historial

Cada payout se puede leer individualmente y el listado acepta filtros:
from/to van en YYYY-MM-DD (zona horaria de tu organización, ambos inclusive); una fecha inválida responde 400 invalid_range. method filtra por el catálogo activo de payouts y search hace una coincidencia parcial sin distinguir mayúsculas/minúsculas sobre el ID del payout, la referencia bancaria o la clave de idempotencia.
Última modificación el 17 de noviembre de 2026