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

# Flujos de integración

> Los flujos end-to-end de una integración típica, con diagramas de secuencia paso a paso

Esta página conecta los productos en **flujos completos de negocio**: qué
llamar, qué esperar y qué webhook cierra cada ciclo. Cada flujo linkea a la
guía detallada de su producto.

## 1. Fondear la cuenta

Tres caminos para que entre dinero; todos terminan en un abono al saldo
USDT y un webhook:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    participant Pagador as Pagador / Red
    App->>CB: POST /v1/payins (o wallet crypto)
    CB-->>App: pending + datos de pago (QR, URL, referencia, dirección)
    App->>Pagador: comparte el medio de pago
    Pagador->>CB: paga (transferencia, QR, USDT on-chain)
    CB->>CB: convierte a tu payin_rate − fee (fiat)
    CB-->>App: webhook payin_credited / crypto_deposit_credited
    App->>CB: GET /v1/balances (verifica)
```

| Camino | Endpoint | Webhook de cierre |
| - | - | - |
| Cobro fiat (QR, transferencia, página de pago, pull) | `POST /v1/payins` / `/collect` | `payin_credited` |
| Depósito USDT on-chain | `POST /v1/crypto/wallets` (dirección fija) | `crypto_deposit_credited` |
| Transferencia interna de otra cuenta | — (la inicia el emisor) | `transfer_received` |

Detalle: [payins](/es/guides/payins) · [crypto](/es/guides/crypto) ·
[transferencias](/es/guides/transfers).

## 2. Dispersar (payout)

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    participant Banco as Riel local
    App->>CB: POST /v1/payouts (idempotency_key)
    CB-->>App: 202 processing (fx_rate, total_debit; débito queda en held)
    CB->>Banco: ejecuta la dispersión
    alt pagado
        Banco-->>CB: confirmación
        CB-->>App: webhook payout_status_changed (completed)
    else rechazo
        Banco-->>CB: rechazo
        CB->>CB: reembolsa el débito COMPLETO a available
        CB-->>App: webhook payout_status_changed (failed + status_code)
    end
    App->>CB: GET /v1/payouts/{id} (verifica estado final)
```

Variante **QR** (Bolivia, PIX de Brasil): `POST /v1/payouts/qr/scan`
(gratis, decodifica) → muestra los datos → `POST /v1/payouts/qr/confirm`
(cobra como un payout normal). Detalle: [payouts](/es/guides/payouts) ·
[payout QR](/es/guides/qr-payout).

## 3. Cobrar a un cliente

Elige la modalidad según el país y la experiencia que quieras dar:

| Modalidad | Países | Experiencia del pagador | Confirmación |
| - | - | - | - |
| Página de pago hosted | CL | Abre una URL y paga desde su banco | Automática |
| QR | BO, BR (PIX) | Escanea con su app bancaria | Automática |
| Transferencia anunciada | CL, PE, MX, BR | Transfiere incluyendo la referencia | Automática por referencia (o monto) |
| CLABE / CVU dedicada | MX, AR | Transfiere a una cuenta fija tuya | Automática, sin referencias |
| Pago con tarjeta | BO (BOB/USD) | Ingresa su tarjeta en una página hosted segura (3DS) | Automática |
| Link de cobro universal | Todos los países activos + crypto + tarjetas | Abre un link y elige cómo pagar | Automática |

Todos cierran con `payin_credited` y el abono neto en tu saldo.
Detalle: [payins](/es/guides/payins) · [checkout](/es/guides/checkout).

## 4. Checkout end-to-end

Un link, todos los rieles, liquidado en el saldo que elijas:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    participant Pagador as Pagador
    App->>CB: POST /v1/payins (method: checkout, amount, settlement_asset)
    CB-->>App: checkout_url (página pública brandeada)
    App->>Pagador: comparte el link
    Pagador->>CB: elige fiat / crypto / tarjeta / app CBPay y paga
    CB->>CB: acredita y auto-convierte a tu settlement_asset
    CB-->>App: webhook payin_credited (settled_via, conversion_status)
```

Detalle: [checkout](/es/guides/checkout).

## 5. Tarjetas guardadas y suscripciones

Guarda la tarjeta una vez (con consentimiento del pagador) y cóbrala
después — con un clic, sin el pagador presente (MIT) o con un calendario
recurrente:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    participant Pagador as Pagador
    App->>CB: POST /v1/payins (method: card, save_card: true)
    Pagador->>CB: paga con 3DS y marca "guardar mi tarjeta"
    CB-->>App: webhook card_stored (stored_card_id)
    App->>CB: POST /v1/stored-cards/{id}/charges (MIT, sin el pagador)
    CB-->>App: webhook payin_credited
    App->>CB: POST /v1/subscriptions (intervalo + monto)
    CB-->>App: payin_credited por período + subscription_status_changed
```

Detalle: [tarjetas guardadas y suscripciones](/es/guides/stored-cards-subscriptions).

## 6. Cobro QR POS (procesadores)

Para empresas que operan puntos de venta físicos:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant POS as Tu POS
    participant CB as CBPay
    participant Cliente as Cliente
    POS->>CB: POST /v1/pos/merchants (merchant verificado, una vez)
    POS->>CB: POST /v1/pos/charges (monto, idempotency_key)
    CB-->>POS: dirección crypto exclusiva + QR + due cotizado
    Cliente->>CB: paga en crypto (los pagos parciales acumulan)
    CB-->>POS: webhook payin_credited (atribución pos_merchant)
```

Detalle: [QR POS](/es/guides/qr-pos).

## 7. Convertir saldos (swaps)

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    Q["GET /v1/swaps/quote<br/>(indicativa, gratis)"] --> S["POST /v1/swaps<br/>(idempotency_key)"]
    S --> B["Abono instantáneo en el<br/>saldo destino"]
```

Una llamada convierte entre USDT, USDC, BTC, GOLD, SILVER y PLATINUM a la tasa de tu
cuenta — la plata no sale de la cuenta, así que no requiere OTP. Detalle:
[swaps](/es/guides/swaps).

## 8. Conciliar

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    webhooks["Webhooks<br/>(push, por evento)"] --> interno["Tu registro interno<br/>(por idempotency_key)"]
    movements["GET /v1/movements<br/>(ledger inmutable)"] --> interno
    cartola["Cartola del período<br/>(JSON/PDF/Excel)"] --> cierre["Cierre contable<br/>con cuadratura"]
    interno --> cierre
```

Receta completa en
[movimientos y conciliación](/es/concepts/movements-reconciliation) y
[cartola](/es/guides/statement).

## 9. Banking internacional end-to-end

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    App->>CB: POST /v1/banking/customers (perfil, una vez)
    CB-->>App: webhook banking_customer_status_changed (approved)
    App->>CB: POST /v1/banking/accounts (cuenta USD/EUR)
    App->>CB: POST /v1/banking/operations/prepare (cotiza, gratis)
    App->>CB: POST /v1/banking/operations (idempotency_key)
    CB-->>App: webhook banking_operation_status_changed (completed/failed)
```

El saldo banking vive en tus cuentas bancarias (separado del USDT); CBPay
solo cobra los fees fijos configurados. Detalle:
[banking](/es/guides/banking).

<Tip>
  ¿Primera integración? Sigue el [inicio rápido](/es/quickstart) (fondeo →
  payout → webhook) y vuelve aquí cuando agregues productos.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.