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

# Dispersar dinero (Payouts)

> Envía dinero a cuentas bancarias de terceros con diferentes velocidades de transferencia.

## ¿Qué vas a lograr?

Al terminar esta guía podrás enviar dinero desde tu cuenta OnePay a cuentas bancarias de terceros. OnePay ofrece tres velocidades de transferencia según tus necesidades.

## Prerrequisitos

* Cuenta de OnePay verificada con llaves API
* Saldo disponible en tu cuenta OnePay
* Datos bancarios del destinatario

## Tipos de dispersión

| Tipo        | Velocidad          | Destinatarios                         | Descripción                     |
| ----------- | ------------------ | ------------------------------------- | ------------------------------- |
| **ACH**     | 1-3 días hábiles   | Personas naturales y jurídicas        | Transferencia estándar bancaria |
| **TURBO**   | Menos de 2 horas\* | Personas naturales y jurídicas        | Transferencia rápida            |
| **INSTANT** | Inmediata          | Solo personas naturales con Transfiya | Transferencia instantánea       |

<Note>
  \*El tiempo de las transferencias TURBO puede variar según el banco del destinatario y la hora de la transacción.
</Note>

## Diagrama de flujo

```mermaid theme={null}
sequenceDiagram
    participant Tu App
    participant OnePay API
    participant Banco destino
    participant Webhook

    Tu App->>OnePay API: POST /customers
    OnePay API-->>Tu App: customer_id
    Tu App->>OnePay API: GET /accounts/banks
    OnePay API-->>Tu App: Lista de bancos
    Tu App->>OnePay API: POST /accounts
    OnePay API-->>Tu App: account_id
    Tu App->>OnePay API: POST /cashouts
    OnePay API-->>Tu App: cashout (pending)
    OnePay API->>Banco destino: Procesa transferencia
    Banco destino-->>OnePay API: Confirmación
    OnePay API->>Webhook: cashout.processed
```

## Paso a paso

<Steps>
  <Step title="Crear el cliente destinatario">
    Registra a la persona o empresa que recibirá el dinero:

    ```bash theme={null}
    curl https://api.onepay.la/v1/customers \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -H "x-idempotency: dest-001" \
      -d '{
        "user_type": "natural",
        "first_name": "Carlos",
        "last_name": "Ramírez",
        "email": "carlos@ejemplo.com",
        "phone": "+573109998877",
        "document_type": "CC",
        "document_number": "1234567890"
      }'
    ```
  </Step>

  <Step title="Consultar bancos disponibles">
    ```bash theme={null}
    curl https://api.onepay.la/v1/accounts/banks \
      -H "Authorization: Bearer sk_test_xxx"
    ```

    Esto retorna la lista de bancos con sus IDs. Usa el `id` del banco correspondiente al crear la cuenta.
  </Step>

  <Step title="Registrar la cuenta bancaria del destinatario">
    <Note>
      Para dispersiones **no** necesitas `authorization: true`. La autorización solo es necesaria si vas a debitar la cuenta (cobrar).
    </Note>

    ```bash theme={null}
    curl https://api.onepay.la/v1/accounts \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -H "x-idempotency: cuenta-dest-001" \
      -d '{
        "customer_id": "CUSTOMER_ID",
        "bank_id": "BANK_ID",
        "subtype": "SAVINGS",
        "account_number": "123456789"
      }'
    ```
  </Step>

  <Step title="Crear la dispersión">
    ```bash theme={null}
    curl https://api.onepay.la/v1/cashouts \
      -X POST \
      -H "Authorization: Bearer sk_test_xxx" \
      -H "Content-Type: application/json" \
      -H "x-idempotency: dispersion-001" \
      -d '{
        "amount": 500000,
        "customer_id": "CUSTOMER_ID",
        "account_id": "ACCOUNT_ID",
        "currency": "COP",
        "method": "ACH",
        "description": "Pago proveedor Enero 2025"
      }'
    ```

    Cambia `method` según la velocidad que necesites: `ACH`, `TURBO` o `INSTANT`.
  </Step>

  <Step title="Escuchar el webhook de dispersión">
    Implementa el [Webhook de dispersiones](/client/webhooks/cashouts) para recibir la notificación cuando la transferencia se procese.

    Estados posibles del cashout:

    ```mermaid theme={null}
    stateDiagram-v2
        [*] --> pending: Creado
        pending --> processing: En proceso
        processing --> processed: Exitoso
        processing --> failed: Fallido
        pending --> cancelled: Cancelado
    ```
  </Step>
</Steps>

## Verificar tu saldo

Antes de crear una dispersión, verifica que tienes saldo suficiente:

```bash theme={null}
curl https://api.onepay.la/v1/balance \
  -H "Authorization: Bearer sk_test_xxx"
```

## Errores comunes

| Error               | Causa                                         | Solución                                                        |
| ------------------- | --------------------------------------------- | --------------------------------------------------------------- |
| Saldo insuficiente  | No tienes fondos para cubrir la dispersión    | Recarga tu cuenta o espera a que se acrediten cobros pendientes |
| `validation_error`  | Falta `account_id`, `customer_id` o `method`  | Verifica que envías todos los campos requeridos                 |
| Cuenta inválida     | El número de cuenta no existe en el banco     | Verifica los datos bancarios con el destinatario                |
| Banco no disponible | El banco está fuera de servicio temporalmente | Reintenta más tarde o usa otro tipo de transferencia            |

## Siguiente paso

<CardGroup cols={2}>
  <Card title="Implementar webhooks" icon="webhook" href="/guides/implementar-webhooks">
    Recibe notificaciones en tiempo real sobre tus dispersiones.
  </Card>

  <Card title="Cobrar con link de pago" icon="link" href="/guides/cobrar-link-pago">
    Recauda los fondos que luego dispersarás.
  </Card>
</CardGroup>