¿Qué son los Pagos?
Los pagos son dispersiones salientes que te permiten enviar fondos desde tu saldo pre-financiado de KillB a cualquier beneficiario — cuentas bancarias, billeteras cripto o alias de pago locales. Son la forma más simple de distribuir dinero a escala: sin paso de cotización, sin URL de pago, sin esperar acción del usuario final. Tú tienes el saldo; KillB lo enruta al destino.Los pagos son una función B2B diseñada para empresas que necesitan dispersar fondos a muchos destinatarios (nómina, pagos a proveedores, liquidaciones de marketplace, distribuciones cripto, etc.).
Pagos vs. Ramps
Tanto los pagos como los ramps mueven dinero, pero sirven propósitos diferentes:| Pagos | Off-Ramps | |
|---|---|---|
| Dirección | Pre-fund → Beneficiario | Billetera cripto → Cuenta fiat |
| Quién inicia | Tu backend | Tu usuario final |
| ¿Cotización requerida? | No | Sí |
| ¿URL de pago? | No | Sí |
| Caso de uso | Dispersiones masivas, nómina, liquidaciones | Retiros de usuario |
| Fuente del saldo | Cuenta pre-financiada | Billetera cripto del usuario |
Cómo Funciona
Prerrequisitos
Cada pago requiere:- Una cuenta pre-financiada activa — tiene el saldo a dispersar
- Saldo suficiente — igual o mayor al monto del pago
- Datos válidos del beneficiario — correspondientes a los campos requeridos del rail de pago elegido
Configurar Cuentas Pre-Financiadas
Aprende cómo crear y fondear tus cuentas pre-financiadas
Ciclo de Vida del Pago
Estados
| Estado | Fase | Significado |
|---|---|---|
CREATED | Inicial | El pago ha sido recibido y persistido, en espera de entrar a la cola |
CASH_IN_PENDING | Cash In | Colección de fondos entrantes en cola |
CASH_IN_PROCESSING | Cash In | Recolectando fondos del saldo pre-financiado |
CASH_IN_COMPLETED | Cash In | Fondos recolectados exitosamente |
KYT_OUT_PENDING | KYT Out | Transacción saliente en cola para verificación de cumplimiento |
KYT_OUT_PROCESSING | KYT Out | Revisión de cumplimiento en progreso (saliente) |
KYT_OUT_COMPLETED | KYT Out | Verificación de cumplimiento saliente aprobada |
CASH_OUT_PENDING | Cash Out | Dispersión al beneficiario en cola |
CASH_OUT_PROCESSING | Cash Out | Fondos enviados al proveedor de pagos |
CASH_OUT_COMPLETED | Cash Out | Proveedor de pagos confirmó la entrega |
COMPLETED | Terminal | Pago totalmente liquidado |
REVIEW_NEEDED | Revisión | Transacción marcada para revisión manual de cumplimiento |
CANCELED | Terminal | Pago cancelado antes del procesamiento |
FAILED | Estado de Error | Operación fallida. Terminal durante Cash In; inicia flujo de reembolso si ocurre en fase posterior. |
REJECTED | Estado de Error | Pago bloqueado por revisión de cumplimiento. Siempre activa el flujo de reembolso, ya que solo ocurre después del Cash In. |
ERROR | Estado de Error | Error interno del sistema. Terminal durante Cash In; inicia flujo de reembolso si ocurre en fase posterior. |
REFUND_PENDING | Reembolso | Reembolso al saldo pre-financiado en cola |
REFUND_PROCESSING | Reembolso | Reembolso en progreso |
REFUNDED | Terminal | Fondos devueltos al saldo pre-financiado |
Tipos de Beneficiario Soportados
| Tipo | Región | Descripción |
|---|---|---|
BANK | Colombia | Transferencia a cuenta bancaria vía Bank Transfer |
BREB | Colombia | Alias registrado (teléfono, email, cédula) |
Idempotencia
Para evitar dispersiones duplicadas en reintentos de red, envía un header únicoIdempotency-Key en cada solicitud de creación de pago. Si se recibe la misma clave dos veces, KillB devuelve el pago original en lugar de crear uno nuevo.
Preguntas Frecuentes
¿Qué pasa con mi saldo si un pago falla?
¿Qué pasa con mi saldo si un pago falla?
Depende de en qué fase ocurre el fallo:
- Durante Cash In — No se recolectaron fondos, por lo que no se debita nada de tu saldo pre-financiado.
- Después de Cash In (KYT Out, Cash Out) — Los fondos ya fueron recolectados. El pago transiciona al flujo de reembolso (
REFUND_PENDING→REFUND_PROCESSING→REFUNDED), devolviéndolos a tu saldo pre-financiado.
¿Puedo cancelar un pago?
¿Puedo cancelar un pago?
Los pagos en estado
CASH_IN_PENDING pueden ser cancelables — contacta al soporte. Una vez que el pago pasa a CASH_IN_PROCESSING, la cancelación ya no es posible ya que los fondos están en tránsito.¿Cuál es la diferencia entre ERROR, FAILED y REJECTED?
¿Cuál es la diferencia entre ERROR, FAILED y REJECTED?
Cada estado refleja un origen de fallo distinto:
ERROR— Error interno del sistema en KillB. No se dispersaron fondos.FAILED— El banco del beneficiario rechazó la transferencia por datos de cuenta inválidos o incorrectos proporcionados por el remitente.REJECTED— El pago fue bloqueado por una revisión de cumplimiento en KillB. Los fondos son devueltos a tu saldo pre-financiado a través del flujo de reembolso.
¿Qué es REVIEW_NEEDED?
¿Qué es REVIEW_NEEDED?
Un pago entra en
REVIEW_NEEDED cuando una verificación KYT (Know Your Transaction) marca la transacción para revisión manual. No se requiere acción de tu parte — el pago se reanudará automáticamente al completarse la revisión, o transitará a REJECTED si es bloqueado.¿Cuándo ocurre el estado REFUNDED?
¿Cuándo ocurre el estado REFUNDED?
Un pago alcanza
REFUNDED cuando FAILED o ERROR ocurre después de la fase de Cash In (KYT Out o Cash Out), o cuando el pago es REJECTED por cumplimiento. Como los fondos ya fueron recolectados, el pago avanza automáticamente por REFUND_PENDING → REFUND_PROCESSING → REFUNDED.Si FAILED o ERROR ocurre durante Cash In, no se recolectaron fondos y no se emite ningún reembolso.¿Cuánto tiempo tarda un pago?
¿Cuánto tiempo tarda un pago?
Las transferencias Bank Transfer y BREB típicamente se liquidan en minutos a pocas horas hábiles dependiendo del banco y los horarios de corte.
¿Cómo funciona la idempotencia?
¿Cómo funciona la idempotencia?
Envía un header único
Idempotency-Key en las solicitudes de creación de pagos. Si se recibe la misma clave dos veces (ej. en un reintento), KillB devuelve el pago original en lugar de crear una dispersión duplicada.Mejores Prácticas
- Verifica el saldo primero — siempre llama a
GET /api/v2/customers/balancesantes de crear un pago para evitar fallos por saldo insuficiente - Usa
Idempotency-Key— siempre envía una clave única por dispersión para reintentar de forma segura sin duplicados - Suscríbete a webhooks — configura webhooks de eventos
PAYOUTpara actualizaciones de estado en tiempo real - Monitorea los pagos REJECTED — registra los datos completos del beneficiario en caso de rechazo para identificar y corregir datos inválidos de cuenta
- Reconcilia diariamente — obtén todos los pagos del día anterior y compáralos con tu libro mayor interno
Guías Relacionadas
Crear un Pago
Guía de implementación paso a paso
Seguimiento de Estado
Monitorea pagos con webhooks y polling
Cuentas Pre-Financiadas
Fondea tus cuentas pre-financiadas
Webhooks
Notificaciones de eventos en tiempo real