> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagos

> Envía fondos desde tu saldo pre-financiado directamente a beneficiarios

## ¿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.

<Info>
  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.).
</Info>

## 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

```mermaid theme={null}
sequenceDiagram
    participant Tu as Tu Backend
    participant KillB
    participant Banco as Banco / Billetera

    Tu->>KillB: POST /api/v2/payouts
    Note over KillB: Debitar saldo pre-financiado
    KillB-->>Tu: { id, status: "CREATED" }
    KillB->>Banco: Enrutar pago por el pipeline
    Banco-->>KillB: Confirmación
    KillB-->>Tu: Webhook: payout.completed
```

## Prerrequisitos

Cada pago requiere:

1. **Una cuenta pre-financiada activa** — tiene el saldo a dispersar
2. **Saldo suficiente** — igual o mayor al monto del pago
3. **Datos válidos del beneficiario** — correspondientes a los campos requeridos del rail de pago elegido

<Card title="Configurar Cuentas Pre-Financiadas" icon="vault" href="/es/guides/pre-fund/pre-fund-accounts">
  Aprende cómo crear y fondear tus cuentas pre-financiadas
</Card>

## Ciclo de Vida del Pago

```mermaid theme={null}
graph LR
    CREATED --> CashIn[Cash In]
    CashIn --> KYTOut[KYT Out]
    KYTOut --> CashOut[Cash Out]
    CashOut --> COMPLETED

    KYTOut -.-> REVIEW_NEEDED
    REVIEW_NEEDED -.-> REJECTED

    KYTOut -.-> FAILED
    KYTOut -.-> ERROR
    CashOut -.-> FAILED
    CashOut -.-> ERROR
    FAILED --> REFUNDED
    ERROR --> REFUNDED
    REJECTED --> REFUNDED

    CashIn -.->|"terminal"| FAILED
    CashIn -.->|"terminal"| ERROR

    style COMPLETED fill:#22c55e,color:#fff
    style REJECTED fill:#f97316,color:#fff
    style FAILED fill:#ef4444,color:#fff
    style ERROR fill:#ef4444,color:#fff
    style REFUNDED fill:#6366f1,color:#fff
    style REVIEW_NEEDED fill:#eab308,color:#000
```

<Warning>
  `FAILED` y `ERROR` durante la fase de **Cash In** son terminales — no se recolectaron fondos, por lo que no se emite ningún reembolso. Para las fases siguientes (KYT Out, Cash Out), estos estados inician el flujo de reembolso. `REJECTED` también activa el flujo de reembolso, ya que solo ocurre después del Cash In.
</Warning>

### 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 único `Idempotency-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.

```bash theme={null}
Idempotency-Key: <tu-referencia-única-de-pago>
```

## Preguntas Frecuentes

<AccordionGroup>
  <Accordion title="¿Qué pasa con mi saldo si un pago falla?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Puedo cancelar un pago?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Cuál es la diferencia entre ERROR, FAILED y REJECTED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Qué es REVIEW_NEEDED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Cuándo ocurre el estado REFUNDED?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Cuánto tiempo tarda un pago?" icon="circle-question">
    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.
  </Accordion>

  <Accordion title="¿Cómo funciona la idempotencia?" icon="circle-question">
    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.
  </Accordion>
</AccordionGroup>

## Mejores Prácticas

* **Verifica el saldo primero** — siempre llama a `GET /api/v2/customers/balances` antes 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 `PAYOUT` para 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

<CardGroup cols={2}>
  <Card title="Crear un Pago" icon="paper-plane" href="/es/guides/payouts/create-payout">
    Guía de implementación paso a paso
  </Card>

  <Card title="Seguimiento de Estado" icon="chart-line" href="/es/guides/payouts/payout-status">
    Monitorea pagos con webhooks y polling
  </Card>

  <Card title="Cuentas Pre-Financiadas" icon="vault" href="/es/guides/pre-fund/pre-fund-accounts">
    Fondea tus cuentas pre-financiadas
  </Card>

  <Card title="Webhooks" icon="bell" href="/es/concepts/webhooks">
    Notificaciones de eventos en tiempo real
  </Card>
</CardGroup>