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

# Cuentas virtuales de depósito BOB

> Recibe bolivianos mediante una cuenta dedicada de transferencia bancaria

export const EnvUrls = ({lang = "en"}) => {
  const T = {
    en: {
      test: "Test",
      live: "Live",
      hint: "Same API on both environments — build against test first, then go live by swapping the base URL and the key.",
      guide: "Environments and testing",
      href: "/en/environment-testing"
    },
    es: {
      test: "Test",
      live: "Live",
      hint: "La misma API en ambos ambientes — construye primero contra test y pasa a live cambiando la URL base y la key.",
      guide: "Entorno y pruebas",
      href: "/es/entorno-y-pruebas"
    },
    zh: {
      test: "Test",
      live: "Live",
      hint: "两个环境的 API 完全一致——先在 test 环境构建，再通过切换基础 URL 和密钥上线。",
      guide: "环境与测试",
      href: "/zh/environment-testing"
    }
  };
  const t = T[lang] || T.en;
  const row = (label, url, keyPattern, badgeCls) => <div className="flex flex-wrap items-center gap-2 px-3 py-2">
      <span className={"rounded px-1.5 py-0.5 text-xs font-semibold uppercase tracking-wide " + badgeCls}>
        {label}
      </span>
      <code className="text-xs">{url}</code>
      <span className="text-xs text-gray-400 dark:text-zinc-500">·</span>
      <code className="text-xs">{keyPattern}</code>
    </div>;
  return <div className="my-4 rounded-xl border border-gray-200 dark:border-zinc-700 divide-y divide-gray-200 dark:divide-zinc-700 text-sm not-prose">
      {row(t.test, "https://cryptobank.qbank.cl/platform", "pk_test_...", "bg-amber-100 text-amber-800 dark:bg-amber-900/40 dark:text-amber-300")}
      {row(t.live, "https://api.qbank.cl/platform", "pk_...", "bg-emerald-100 text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-300")}
      <p className="px-3 py-2 text-xs text-gray-500 dark:text-zinc-400 m-0">
        {t.hint} <a href={t.href}>{t.guide} →</a>
      </p>
    </div>;
};

<EnvUrls lang="es" />

## Qué resuelve este producto

Una cuenta virtual de depósito BOB es un destino fijo de recepción vinculado
a una cuenta CBPay. Tu pagador hace una transferencia bancaria normal en
bolivianos a ese destino; CBPay detecta el abono, reconcilia la cuenta
reportada y acredita tu cuenta mediante el flujo normal de payins.

La cuenta es solo de recepción. No es una wallet, no crea una sesión de pago y
el pagador no necesita incluir una referencia de anuncio.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
  participant A as Tu cuenta
  participant C as CBPay
  participant B as Banco del pagador
  A->>CBPay: GET métodos de payin
  CBPay-->>A: BO/BOB/bank_transfer
  A->>CBPay: POST deposit-accounts
  CBPay-->>A: Instrumento fijo de recepción
  B->>CBPay: Transferencia al instrumento
  CBPay->>CBPay: Polling y conciliación
  CBPay-->>A: Webhook payin_credited
```

## 1. Confirma el corredor

Usa siempre el catálogo vivo antes de activar una opción de pago:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.qbank.cl/platform/v1/payins/methods \
  -H "Authorization: Bearer <token>"
```

La fila relevante es:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "country": "BO",
  "currency": "BOB",
  "method": "bank_transfer",
  "delivery": "polling"
}
```

El catálogo es la fuente de verdad. Tu organización puede tener el corredor
apagado aunque exista el contrato de la API.

## 2. Crea o repara el destino de recepción

Normalmente la cuenta recibe su instrumento BOB durante la provisión inicial.
Este endpoint también sirve para reparar un instrumento faltante:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.qbank.cl/platform/v1/payins/deposit-accounts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BO",
    "currency": "BOB",
    "method": "bank_transfer",
    "alias": "Operaciones BOB"
  }'
```

Respuesta `201`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "instrument_id": "1f4a…",
  "account_id": "9b1d…",
  "country": "BO",
  "currency": "BOB",
  "method": "bank_transfer",
  "instrument": "7014227171",
  "details": {
    "account_number": "7014227171",
    "status": "ACTIVA"
  },
  "status": "active",
  "created_at": "2026-09-09T20:00:00Z"
}
```

Comparte `instrument` con el pagador como número de cuenta de recepción.
`instrument_id` es el identificador estable de CBPay; no reemplaces el número
de recepción por el UUID.

Existe una sola cuenta activa por cuenta/país/moneda/método. Un segundo create
no abre otro destino. Una respuesta ausente o ambigua queda visible para
conciliación; el sistema no reintenta silenciosamente.

## 3. Lista los instrumentos

El listado es paginado y oculta los claims de provisión que aún no tienen un
número real:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.qbank.cl/platform/v1/payins/deposit-accounts?page=1&page_size=50" \
  -H "Authorization: Bearer <token>"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "page": 1,
  "page_size": 50,
  "deposit_accounts": [
    {
      "instrument_id": "1f4a…",
      "account_id": "9b1d…",
      "country": "BO",
      "currency": "BOB",
      "method": "bank_transfer",
      "instrument": "7014227171",
      "status": "active",
      "created_at": "2026-09-09T20:00:00Z"
    }
  ]
}
```

## 4. Recibe y concilia la transferencia

Este modo no usa el anuncio `POST /v1/payins`. El pagador transfiere BOB al
instrumento indicado. El rail se consulta en una ventana de fechas acotada;
los abonos completados se deduplican por la referencia bancaria, la orden ACH
o una clave determinística de respaldo.

Cuando el abono se concilie, suscríbete a `payin_credited` y usa el recurso
payin para conocer monto y estado finales:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.qbank.cl/platform/v1/payins?country=BO&status=credited&from=2026-09-01&to=2026-09-10&page=1&page_size=50" \
  -H "Authorization: Bearer <token>"
```

Se aplican la comisión normal y las reglas de conversión de payins. La API
pública no expone el objeto específico del proveedor bancario.

## Payouts BOB

Los payouts BOB mantienen el contrato provider-agnostic:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: bo-payout-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BO",
    "currency": "BOB",
    "method": "bank_transfer",
    "amount": "1382.00",
    "beneficiary": {
      "name": "Juan Quispe Mamani",
      "tax_id": "4567890",
      "bank_code": "1016",
      "account_number": "1234567890"
    },
    "description": "Pago a proveedor"
  }'
```

La organización define qué versión interna del rail está activa. Esa decisión
no es un campo controlado por el cliente y queda guardada en la operación para
que el polling posterior consulte el rail correcto. La respuesta y el webhook
siguen siendo provider-agnostic.

## Estados y recuperación

| Estado       | Significado                                    | Acción                    |
| ------------ | ---------------------------------------------- | ------------------------- |
| `active`     | La cuenta de recepción puede compartirse       | Usa `instrument`          |
| `pending`    | La provisión o conciliación sigue en curso     | No crees otra cuenta      |
| `credited`   | Una transferencia fue conciliada y acreditada  | Consume `payin_credited`  |
| `unassigned` | El crédito no pudo enrutarse a una sola cuenta | Resuélvelo en operaciones |

Después de un timeout, lee primero el listado. El proveedor puede haber
aceptado la primera solicitud aunque la respuesta se haya perdido.

## Errores

| HTTP | Código                          | Acción                                                                           |
| ---: | ------------------------------- | -------------------------------------------------------------------------------- |
|  400 | `payin_corridor_unsupported`    | Vuelve a consultar `GET /v1/payins/methods`; el corredor no está activo          |
|  401 | `unauthorized`                  | Renueva la credencial de la cuenta                                               |
|  403 | `account_blocked`               | Activa la cuenta con el operador de la organización                              |
|  422 | `deposit_account_limit_reached` | Usa el instrumento existente; hay un destino por corredor                        |
|  502 | `deposit_account_failed`        | Lee el listado antes de reintentar; no asumas que el proveedor no creó la cuenta |
|  502 | `core_unavailable`              | Reintenta la misma operación lógica cuando vuelva la disponibilidad              |
|  502 | `core_invalid_response`         | Mantén el claim en conciliación y escala si persiste                             |

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Puedo usar la misma cuenta para varias cuentas CBPay?">
    No. El destino está vinculado a una cuenta CBPay y a una organización.
    Comparte solo el instrumento de esa cuenta.
  </Accordion>

  <Accordion title="¿El pagador necesita una cuenta CBPay?">
    No. Usa el flujo de transferencia de su propio banco. CBPay solo necesita que
    el destino esté activo y que el banco reporte el abono.
  </Accordion>

  <Accordion title="¿Puedo borrar o rotar la cuenta?">
    No. El instrumento es inmutable para su corredor. Si el proveedor reporta un
    problema, contacta a operaciones en vez de crear un reemplazo a ciegas.
  </Accordion>

  <Accordion title="¿Cuándo se acredita una transferencia?">
    El rail se consulta por polling. El tiempo final depende de cuándo el banco
    registre el movimiento; el webhook se emite después de la conciliación.
  </Accordion>
</AccordionGroup>