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:
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
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).202 Accepted:
total_debit pasó de
available a held (en el saldo del settlement_asset).
Payouts de remesa US/USD
Para un payoutwire 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.
202 Accepted:
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:
- CLP → USDT a tu tasa:
100000 / 950.25 = 105.235465 USDT. - + comisión fija:
105.235465 + 0.30 = 105.535465 USDT(total_debit). - USDT → BTC al precio efectivo de settlement (
settlement_rate109029.34070000):105.535465 / 109029.3407 = 0.00096795 BTC(redondeo hacia arriba al satoshi). - Débito y hold en BTC:
settlement_amount0.00096795sale de tu saldo BTC; el beneficiario recibe sus 100,000 CLP igual que siempre.
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 responde202 Accepted con el recurso en status: "pending":
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 yfunds_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.
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 terminarfailed 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 eventopayout_status_changed (webhooks):
completed: el dinero llegó; el hold se consume.failed: se reembolsa el débito completo automáticamente (payout_refunden 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.