Errores frecuentes
Rechazo inmediato vs fallo posterior
Si el procesador rechaza el payout al crearlo por una razón de negocio corregible, recibes422 con el objeto en status: failed y el reembolso ya
aplicado. Corrige los datos del beneficiario o de la solicitud y crea un payout
nuevo con una clave nueva. Una falta temporal de fondos del canal o de
tesorería es distinta: la plataforma puede dejar el payout en in_review en
vez de fallarlo de inmediato, así que no crees otro payout hasta conocer el
resultado de la revisión.
Cuando un payout está in_review, el mensaje visible para la cuenta es
intencionalmente genérico: está en revisión y se completará solo cuando se
libere. No corrijas datos del beneficiario por este estado. Si se aprueba la
revisión pero la clave de despacho original ya se consumió, la aprobación
responde reissue_required; solo entonces crea un payout nuevo con una
nueva idempotency_key. CBPay nunca vuelve a emitir la operación por su
cuenta.
Cómo leer status_code en un payout fallido
En un payout fallido terminal, el mensaje para la cuenta indica que no se pudo
completar y que los fondos fueron devueltos. Verifica el reembolso con la
entrada
payout_refund en
movimientos. Un payout que sigue
in_review no es terminal: espera el resultado de la revisión en vez de
asumir que hubo reembolso o un nuevo despacho.
Un payout en
processing no se puede cancelar por API: el canal ya lo tiene.
Un payout en in_review tampoco es un flujo de cancelación del cliente:
espera el resultado de la revisión. En ambos estados, espera el estado final
por webhook o GET. Un fallo terminal devuelve los fondos; una aprobación
que informa reissue_required exige que el cliente cree una operación nueva
con una clave nueva.FAQ
¿Cuándo se debita mi saldo?
¿Cuándo se debita mi saldo?
Al crear: el payout debita y retiene los fondos de inmediato. Si el payout
falla, el monto exacto debitado (comisión incluida) se reembolsa
automáticamente.
¿Puedo cancelar un payout en processing?
¿Puedo cancelar un payout en processing?
No — una vez despachado al riel se resuelve solo a
completed o failed.
Suscríbete a payout_status_changed para el estado final.¿Qué tasa FX usa mi payout?
¿Qué tasa FX usa mi payout?
La tasa cotizada al crear (devuelta como
fx_rate), congelada para esa
operación. Tu spread acordado ya viene dentro de la tasa.¿Puedo pagar desde un saldo distinto de USDT?
¿Puedo pagar desde un saldo distinto de USDT?
Sí — fija un default por cuenta (
PUT /v1/settlement) o sobreescribe por
payout con settlement_asset (USDC, BTC, GOLD). Los reembolsos devuelven
el monto liquidado exacto, jamás se re-cotizan.¿Qué significa status: pending con compliance_pending: true?
¿Qué significa status: pending con compliance_pending: true?
El screening del beneficiario no está disponible temporalmente, pero CBPay
persistió el payout en su cola técnica de screening. No se debitó saldo, no
existe hold ni asiento en el ledger, no se llamó al core y todavía no hay
receipt_url. El replay con la misma idempotency key devuelve el mismo recurso.
Espera el evento payout_status_changed o consulta el payout: continuará con
process, entrará al firewall con un hold válido o terminará failed sin
débito si el resultado es rejected.¿Qué significa compliance_hold (403)?
¿Qué significa compliance_hold (403)?
El payout quedó retenido para revisión y no fue procesado: no se movieron fondos y tu
idempotency_key no se consumió. El portal muestra una línea de
referencia copiable con hora UTC, código del error y request corto. Inclúyela
al contactar a soporte; la razón exacta de compliance no se informa.¿Qué significa status: in_review en un payout?
¿Qué significa status: in_review en un payout?
El payout está en revisión y el mensaje visible para la cuenta es genérico: se
completará solo cuando se libere. Este estado puede proteger un payout cuando
el canal o su tesorería no están disponibles temporalmente. No cambies el
beneficiario ni crees un segundo payout mientras está en revisión. Si la
aprobación responde
reissue_required, crea un payout nuevo con una clave de
idempotencia nueva; CBPay nunca lo vuelve a emitir automáticamente.¿Por qué un payout respondió 503 sin un error del beneficiario?
¿Por qué un payout respondió 503 sin un error del beneficiario?
Algunas condiciones temporales del canal no son causadas por los datos del
beneficiario. Repite el 503 directo con la misma clave de idempotencia. Si el
payout quedó
in_review, espera el resultado de la revisión; solo un
reissue_required explícito autoriza un payout nuevo con una clave nueva.¿Cómo reintento sin riesgo tras un timeout o 5xx?
¿Cómo reintento sin riesgo tras un timeout o 5xx?
Reintenta con la misma
idempotency_key: recibes el payout original
(idempotency_hit: true) — jamás un duplicado. Una clave nueva es un
payout nuevo e independiente.Por qué mi payout US ACH/wire/SWIFT sigue processing?
Por qué mi payout US ACH/wire/SWIFT sigue processing?
Los payouts del riel bancario US los paga el operador a mano. El create
ya trae el CBF en
bank_reference y queda processing hasta que el banco
confirma. Estimaciones: ACH 24 a 48 horas hábiles, wire/Fedwire mismo día hábil (hasta 24 horas), SWIFT 24 a 48 horas hábiles (posiblemente más según el banco receptor). Escucha payout_status_changed; un fallo reembolsa el débito.422 destination_recently_rejected,
consulta Errores y Protección ante rechazo del destino.
Propósito y validación de pagos US/USD
En payouts bancariosUS/USD (ach, wire y swift),
options.purpose es obligatorio. La API acepta la etiqueta visible o su
código, sin distinguir mayúsculas. El catálogo aceptado es:
options.purpose_detail es obligatorio solo cuando purpose es Other y
acepta hasta 140 caracteres. Se rechaza con cualquier otro propósito. Crear
sin purpose ahora responde 400 purpose_required: es un cambio incompatible
para clientes que dependían del antiguo default Invoice_Payment.
beneficiary.account_type es obligatorio tanto para ach como para wire y
debe ser checking o savings (sin distinguir mayúsculas). swift no usa
este campo. Para wire y swift, montos menores a USD 25 responden
422 amount_below_minimum. Países del beneficiario o banco del Anexo B
(CU, IR, KP, SY) responden 422 prohibited_country. Estas validaciones
ocurren antes de debitar.
Los errores normalizados son invalid_beneficiary, invalid_amount,
amount_below_minimum, prohibited_country, purpose_required,
invalid_options y supporting_document_required. Revisa message para
corregir el campo exacto. No repitas una solicitud rechazada sin cambios; ante
timeout o 5xx, reutiliza la misma clave de idempotencia.