> ## 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. # Crear un payin (cobro de recarga) > Crea una recarga fiat. Con `method: "qr"` (por defecto) se genera un cobro QR activo a través del procesador — en Bolivia el QR interoperable local, en Brasil un QR PIX dinámico cuyo `charge` trae la imagen del QR y el payload "copia e cola". Con `method: "bank_transfer"` el depósito queda anunciado y la respuesta trae la referencia que el remitente debe incluir para que la transferencia entrante se concilie y acredite automáticamente — un código corto de 12 caracteres alfanuméricos que cabe en cualquier concepto bancario (algunos rieles lo limitan a 20 caracteres sin caracteres especiales). Con `method: "fintoc"` (Chile) la respuesta trae una `payment_url` hosted: el pagador la abre y transfiere desde cualquier banco o billetera chilena; el depósito se detecta, valida y acredita automáticamente. Con `method: "card"` (Bolivia) la respuesta trae una `payment_url` hosted de un checkout de tarjeta con 3-D Secure y la marca de tu organización — los datos de la tarjeta jamás tocan tu integración. Con `method: "checkout"` la respuesta trae una `checkout_url` pública — un link de cobro universal denominado en el saldo virtual que elijas (`settlement_asset`: USDT, USDC, BTC o GOLD). El pagador elige cualquier país con corredor de payin vivo (monto local cotizado), cualquiera de las 4 opciones crypto (dirección de depósito exclusiva con QR escaneable) o paga al instante desde la app CBPay vía el QR/alias del comercio; cada pago se convierte automático al asset de settlement salvo que se pague en el mismo asset. El primer método que completa el pago gana. Cobrar es gratis; la comisión de payin aplica cuando el depósito se acredita. ## OpenAPI ````yaml /openapi.es.yaml post /v1/payins openapi: 3.1.0 info: title: CBPay API version: '1.89' description: | CBPay es una plataforma de pagos multimoneda: payouts y cobros fiat en toda América Latina, transferencias internas, fondeo y retiros on-chain, y screening KYC. Cada cuenta mantiene cuatro saldos virtuales independientes — USDT (la moneda operativa), USDC, BTC y GOLD (gramos de oro fino) — que nunca se mezclan ni se convierten automáticamente. Los payouts y las comisiones de servicios pueden pagarse desde cualquiera de los cuatro saldos: define un predeterminado con `PUT /v1/settlement` o haz override por payout con `settlement_asset`. Todos los montos son strings decimales en la precisión de cada moneda (6 decimales para USDT/USDC/GOLD, 8 para BTC). Los errores siempre devuelven `{"error": "", "message": ""}`. servers: - url: https://api.qbank.cl/platform description: Live (producción, dinero real) - url: https://cryptobank.qbank.cl/platform description: Test (sandbox, dinero simulado — keys pk_test_) security: - bearerAuth: [] tags: - name: Comprobantes description: >- Comprobante PDF brandeado por operacion, con verificacion publica de autenticidad (QR firmado), receipt_url en cada respuesta/webhook y envio automatico por email en estados finales. - name: Autenticación description: >- Registra e inicia sesión de los miembros de la cuenta. Las sesiones duran 24 horas. - name: Cuenta description: Perfil, miembros y llaves de API de la cuenta que llama. - name: Saldos description: Saldos, historial de movimientos y tasas de cambio. - name: Payouts description: >- Dispersiones fiat que se debitan del saldo de settlement que elijas (USDT por defecto). - name: Payins description: Recargas fiat que se acreditan al saldo en USDT. - name: Transferencias - name: Contacts - name: Swaps description: >- Transferencias internas gratuitas entre cuentas CBPay (persona o empresa, cualquier combinación). - name: Crypto description: Fondeo y retiros on-chain (TRON, Ethereum y Bitcoin). - name: Wallets segregadas description: >- Wallets on-chain con saldo propio (empresas ilimitadas; personas 1 por combinación red+activo) — crear, importar, enviar, exportar la llave privada y auto-forward. El saldo vive on-chain, nunca en el ledger. - name: QR Crypto POS description: >- Cobros QR crypto con monto para procesadores con POS físicos (cuentas empresa): merchants verificados, dirección exclusiva + QR por cobro, detección temprana del pago, conciliación por merchant y devoluciones por el riel de retiro crypto. - name: KYC / KYB - name: Screening de wallets description: >- Evaluación de riesgo AML de direcciones blockchain (sanciones, exposición a fondos ilícitos) con comisión por scan, más protección automática gratuita en retiros y depósitos. - name: AML screening description: >- Verificación de identidad: KYC para personas, KYB para empresas, con screening AML, re-screening y monitoreo continuo. - name: Analytics - name: Webhooks description: Suscripciones para recibir notificaciones de eventos firmadas. - name: Estado description: Disponibilidad del servicio. - name: Banking description: >- Cuentas bancarias reales: recibe, mantén y envía dinero por rieles bancarios internacionales. - name: Cards description: >- Tarjetas virtuales y físicas que gastan Just-In-Time del saldo USDT de la cuenta, con límites de gasto por tarjeta. - name: Seguridad (OTP) description: >- Códigos de verificación de un solo uso por SMS/WhatsApp/email que protegen acciones sensibles, más las preferencias de 2FA self-service. Aplican solo a sesiones de usuario — las API keys quedan exentas. - name: Passkeys description: >- Inicio de sesión sin contraseña con la biometría del dispositivo (Face ID, Touch ID, Windows Hello, llaves de seguridad) vía WebAuthn, apps autenticadoras (TOTP) con códigos de respaldo, y gestión de sesiones/dispositivos. - name: Login social description: >- Registro e inicio de sesión sin contraseña con Google, Apple, Microsoft y Facebook vía token exchange. El front obtiene la credencial del proveedor; la API la verifica y emite la sesión CBPay. paths: /v1/payins: post: tags: - Payins summary: Crear un payin (cobro de recarga) description: >- Crea una recarga fiat. Con `method: "qr"` (por defecto) se genera un cobro QR activo a través del procesador — en Bolivia el QR interoperable local, en Brasil un QR PIX dinámico cuyo `charge` trae la imagen del QR y el payload "copia e cola". Con `method: "bank_transfer"` el depósito queda anunciado y la respuesta trae la referencia que el remitente debe incluir para que la transferencia entrante se concilie y acredite automáticamente — un código corto de 12 caracteres alfanuméricos que cabe en cualquier concepto bancario (algunos rieles lo limitan a 20 caracteres sin caracteres especiales). Con `method: "fintoc"` (Chile) la respuesta trae una `payment_url` hosted: el pagador la abre y transfiere desde cualquier banco o billetera chilena; el depósito se detecta, valida y acredita automáticamente. Con `method: "card"` (Bolivia) la respuesta trae una `payment_url` hosted de un checkout de tarjeta con 3-D Secure y la marca de tu organización — los datos de la tarjeta jamás tocan tu integración. Con `method: "checkout"` la respuesta trae una `checkout_url` pública — un link de cobro universal denominado en el saldo virtual que elijas (`settlement_asset`: USDT, USDC, BTC o GOLD). El pagador elige cualquier país con corredor de payin vivo (monto local cotizado), cualquiera de las 4 opciones crypto (dirección de depósito exclusiva con QR escaneable) o paga al instante desde la app CBPay vía el QR/alias del comercio; cada pago se convierte automático al asset de settlement salvo que se pague en el mismo asset. El primer método que completa el pago gana. Cobrar es gratis; la comisión de payin aplica cuando el depósito se acredita. operationId: createPayin requestBody: required: true content: application/json: schema: type: object required: - country - currency - amount properties: country: type: string example: BO description: >- País del corredor. Obligatorio para todos los métodos salvo `checkout`, donde es opcional y solo preselecciona el país del pagador en la página. currency: type: string example: BOB description: >- Moneda del corredor. Obligatoria para todos los métodos salvo `checkout`, que la rechaza con 400 — el cobro se denomina en `settlement_asset`. amount: type: string description: >- String decimal positivo. Monto en moneda local para métodos de corredor; para `checkout` se denomina en el `settlement_asset` ("50" USDT, "0.001" BTC, "2" gramos de oro). description: type: string channel: type: string description: Indicación opcional de canal que se pasa al core. expires_in: type: integer description: >- Expiración del cobro en segundos. Para `checkout` acepta de 600 a 604800 (10 minutos a 7 días; default 24 horas). method: type: string enum: - qr - bank_transfer - fintoc - card - checkout default: qr description: >- Modo de cobro. `qr` crea un cobro QR activo a través del procesador; `bank_transfer` anuncia un depósito entrante y devuelve la referencia a incluir en la descripción de la transferencia; `fintoc` (solo Chile) devuelve una `payment_url` hosted donde el pagador transfiere desde cualquier banco o billetera chilena y el depósito se detecta automáticamente; `card` (Bolivia) devuelve una `payment_url` hosted de un checkout de tarjeta con 3-D Secure; `checkout` devuelve una `checkout_url` pública donde el pagador elige el método de pago (QR, tarjeta, transferencia bancaria o crypto). Usa /v1/payins/collect para cobros pull. idempotency_key: type: string description: >- Clave de idempotencia opcional (métodos `fintoc`, `card` y `checkout`; también se acepta como header `Idempotency-Key`). Un retry con la misma clave devuelve el payin original y su `payment_url`/`checkout_url` en vez de abrir una segunda sesión de pago. customer: type: object description: >- Prefill opcional de facturación para el checkout de tarjeta (método `card`) — `email`, `first_name`, `last_name`, `address`, `city`, `country` (texto plano, máx 120 caracteres por campo). El pagador puede completarlos o corregirlos en la página. success_url: type: string description: >- URL https pública opcional (métodos `card` y `checkout`) a la que se redirige al pagador tras un pago aprobado. failure_url: type: string description: >- URL https pública opcional (métodos `card` y `checkout`) a la que se redirige al pagador cuando el pago falla o expira. expires_at: type: string format: date-time description: >- Expiración RFC3339 opcional de la sesión de pago con tarjeta (método `card`, mínimo 15 minutos hacia adelante; default 24 horas). settlement_asset: type: string enum: - USDT - USDC - BTC - GOLD default: USDT description: >- Solo checkout — el saldo virtual en que se denomina y liquida el cobro. Todo pago se convierte automático a este asset al acreditar (pagos en el mismo asset no convierten). Debe estar habilitado para tu organización (`422 settlement_asset_disabled` si no). examples: bo_qr: summary: Bolivia — cobro QR (BOB) value: country: BO currency: BOB method: qr amount: '700.00' description: App top-up expires_in: 3600 br_pix_qr: summary: Brasil — QR PIX dinámico (BRL) value: country: BR currency: BRL method: qr amount: '120.00' description: Order 7719 expires_in: 1800 cl_announced_transfer: summary: Chile — transferencia bancaria anunciada (CLP) value: country: CL currency: CLP method: bank_transfer amount: '500000' py_announced_transfer: summary: >- Paraguay — transferencia bancaria anunciada (PYG, montos enteros) value: country: PY currency: PYG method: bank_transfer amount: '596000' cl_fintoc: summary: Chile — página de pago hosted, cualquier banco (CLP) value: country: CL currency: CLP method: fintoc amount: '150000' description: Top-up order 8841 idempotency_key: topup-8841 bo_card: summary: Bolivia — checkout de tarjeta 3-D Secure (BOB) value: country: BO currency: BOB method: card amount: '700.00' description: App top-up customer: email: payer@example.com first_name: Ana last_name: Rojas success_url: https://your-app.com/payment/ok failure_url: https://your-app.com/payment/error idempotency_key: topup-7719 checkout_usdt: summary: >- Link de cobro universal — 50 USDT (multi-país, CL preseleccionado) value: method: checkout amount: '50' settlement_asset: USDT country: CL description: Order 8841 success_url: https://your-app.com/payment/ok failure_url: https://your-app.com/payment/error expires_in: 86400 idempotency_key: order-8841 checkout_btc: summary: Link de cobro universal — 0.001 BTC (liquidación en BTC) value: method: checkout amount: '0.001' settlement_asset: BTC description: Invoice 1204 idempotency_key: invoice-1204 responses: '201': description: Cobro creado. content: application/json: schema: type: object properties: payin_id: type: string format: uuid status: type: string example: pending charge: type: object description: >- Detalles del cobro (datos del QR, referencias) desde el core. examples: qr: summary: 'Cobro QR (method: qr)' value: payin_id: 4f8a1b2c-3d4e-5f60-7a8b-9c0d1e2f3a4b status: pending charge: charge_id: c9d8e7f6-a5b4-c3d2-e1f0-a9b8c7d6e5f4 our_reference: QR-778812 qr_image: data:image/png;base64,iVBORw0KGgo… qr_image_url: >- https://cdn.cbpayapp.com/public/payin-qr/c9d8e7f6-a5b4-c3d2-e1f0-a9b8c7d6e5f4.png bank_transfer: summary: 'Depósito anunciado (method: bank_transfer)' value: payin_id: 4f81c1d0-aaaa-bbbb-cccc-ddddeeeeffff status: pending reference: CBJ6T3W9M2K5 note: >- include the reference in the transfer description so the deposit is credited automatically fintoc: summary: 'Página de pago hosted (method: fintoc, Chile)' value: payin_id: 7a2b3c4d-1111-2222-3333-444455556666 status: pending reference: 7a2b3c4d-1111-2222-3333-444455556666 payment_url: https://pay.fintoc.com/plink_K2zwNNSxPyx8w3GZ expires_at: '2026-07-08T18:48:25Z' note: >- share the payment_url with the payer; the deposit is credited automatically once the transfer is detected card: summary: 'Página de pago con tarjeta (method: card, Bolivia)' value: payin_id: b41c9a70-1111-2222-3333-444455556666 status: pending reference: b41c9a70-1111-2222-3333-444455556666 payment_url: https://api.qbank.cl/pay/cards/9f3XkT2m… expires_at: '2026-07-16T18:30:00Z' note: >- share the payment_url with the payer; the balance is credited automatically once the card payment is approved checkout: summary: 'Link de cobro universal (method: checkout)' value: payin_id: d0135ed5-8e9c-4f8b-a522-8ec100470426 kind: checkout status: pending settlement_asset: USDT asset_amount: '50' country: CL description: Order 8841 reference: CB68JZCT46QE checkout_url: https://api.qbank.cl/platform/pay/fc4981b8e7c7… expires_at: '2026-07-17T17:57:44Z' receipt_url: >- https://api.qbank.cl/platform/v1/payins/d0135ed5-8e9c-4f8b-a522-8ec100470426/receipt '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/AccountRequired' '422': description: El core rechazó el cobro (`core_rejected`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: core_rejected message: amount is below the minimum for this corridor '502': description: Core no disponible (`core_unavailable`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: core_unavailable message: could not create the charge components: responses: BadRequest: description: >- Solicitud inválida (ver el código `error` para la validación específica). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_json message: 'request body is not valid JSON: unknown field' Unauthorized: description: Credencial faltante o inválida (`unauthorized`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: invalid or missing credentials AccountRequired: description: Este endpoint requiere una credencial de cuenta (`account_required`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: account_required message: this endpoint requires an account credential schemas: Error: type: object properties: error: type: string description: Código de error legible por máquina (snake_case). example: insufficient_funds message: type: string description: Explicación legible por humanos. securitySchemes: bearerAuth: type: http scheme: bearer description: | JWT de sesión (de register/login) o llave de API (`pk_...`). `X-API-Key: ` se acepta como header alternativo. ````