> ## 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 una tarjeta > Emite una tarjeta (virtual o física) que gasta Just-In-Time del saldo central de la cuenta en el asset de gasto de la tarjeta (`spending_asset`: USDT/USDC 1:1 con el USD, o BTC/GOLD convertidos al precio del momento de cada evento; USDT por defecto) — sin prefondeo: cada compra se autoriza en tiempo real contra el saldo disponible y los límites propios de la tarjeta. Las cuentas persona pueden tener **1 virtual + 1 física**; las cuentas empresa crean tarjetas **ilimitadas**, para la empresa o para personas designadas (ej. empleados, pasando sus documentos de identidad). La emisión cobra el fee `card_creation_virtual` / `card_creation_physical` cuando está configurado (0 = gratis); el cargo se reembolsa automáticamente si la emisión falla. Las tarjetas físicas nacen `pending_activation` hasta que el titular confirma la recepción. ## OpenAPI ````yaml /openapi.es.yaml post /v1/cards 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/cards: post: tags: - Cards summary: Crear una tarjeta description: >- Emite una tarjeta (virtual o física) que gasta Just-In-Time del saldo central de la cuenta en el asset de gasto de la tarjeta (`spending_asset`: USDT/USDC 1:1 con el USD, o BTC/GOLD convertidos al precio del momento de cada evento; USDT por defecto) — sin prefondeo: cada compra se autoriza en tiempo real contra el saldo disponible y los límites propios de la tarjeta. Las cuentas persona pueden tener **1 virtual + 1 física**; las cuentas empresa crean tarjetas **ilimitadas**, para la empresa o para personas designadas (ej. empleados, pasando sus documentos de identidad). La emisión cobra el fee `card_creation_virtual` / `card_creation_physical` cuando está configurado (0 = gratis); el cargo se reembolsa automáticamente si la emisión falla. Las tarjetas físicas nacen `pending_activation` hasta que el titular confirma la recepción. operationId: createCard requestBody: required: true content: application/json: schema: type: object required: - idempotency_key properties: physical: type: boolean default: false idempotency_key: type: string description: >- Obligatoria (también como header Idempotency-Key). Un retry con la misma clave devuelve la tarjeta original y nunca cobra dos veces el fee de emisión. spending_asset: type: string enum: - USDT - USDC - BTC - GOLD default: USDT description: >- Saldo desde el que gasta la tarjeta. USDT/USDC van a la par del USD (1:1 exacto, sin comisión de conversión). BTC/GOLD se convierten al precio efectivo del momento de cada evento, con colchón de reserva en la autorización (pricing fail-closed y límites de assets volátiles compartidos con payouts). limits: type: object description: >- Límites de gasto opcionales en USD (se aplican al autorizar; 0 u omitido = sin límite). properties: per_transaction: type: string daily: type: string monthly: type: string cardholder: type: object description: >- Datos del titular. En la PRIMERA emisión de la cuenta el titular se crea en el emisor: la identidad y los documentos se COMPLETAN SOLOS desde la verificación de identidad aprobada de la cuenta (los campos explícitos ganan); solo agregas los campos propios del emisor (código de ocupación del catálogo, salary_usd). Omítelo en las tarjetas siguientes: se reutiliza el titular ya verificado. Las cuentas empresa también pueden usar kind "person" más el verification_id del KYC APROBADO de ESA persona para emitir a una persona designada (su identidad y documentos salen de la verificación). properties: verification_id: type: string format: uuid description: >- OBLIGATORIO para personas designadas (kind "person" en cuentas empresa): submission_id del KYC de terceros APROBADO de la persona. examples: person_first_card: summary: >- Persona — PRIMERA tarjeta (la identidad se completa desde la verificación) value: physical: false idempotency_key: card-v-1 cardholder: occupation: '52201' salary_usd: 1800 subsequent_card: summary: Tarjeta siguiente — titular ya verificado (sin datos) value: physical: true idempotency_key: card-f-ops-1 spending_asset: USDC limits: per_transaction: '500.00' monthly: '5000.00' company_for_employee: summary: >- Empresa — tarjeta para una persona designada (exige KYC aprobado) value: physical: false idempotency_key: card-emp-77 limits: monthly: '1500.00' cardholder: kind: person verification_id: c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f occupation: '52201' salary_usd: 1800 responses: '201': description: Tarjeta creada. content: application/json: schema: $ref: '#/components/schemas/CardObject' example: card_id: 3c2b1a09-8d7e-6f5a-4b3c-2d1e0f9a8b7c account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d physical: false cardholder_kind: account cardholder_name: Client X SpA status: active spending_asset: USDT limits: monthly: '5000.000000' created_at: '2026-07-08T12:00:00Z' updated_at: '2026-07-08T12:00:00Z' creation_fee: '3.000000' '400': description: idempotency_key_required / invalid_amount content: application/json: schema: $ref: '#/components/schemas/Error' example: error: idempotency_key_required message: provide idempotency_key (body or Idempotency-Key header) '401': $ref: '#/components/responses/Unauthorized' '402': description: El saldo no alcanza para el fee de emisión (insufficient_funds). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_funds message: account balance is not enough for this operation '403': $ref: '#/components/responses/AccountRequired' '409': description: card_limit_reached (cuentas persona) / cardholder_kyc_pending content: application/json: schema: $ref: '#/components/schemas/Error' example: error: card_limit_reached message: >- person accounts can hold at most 1 virtual card (cancel the existing one first) '422': description: >- verification_required / verification_not_approved / verification_kind_mismatch (las personas designadas necesitan el verification_id de un KYC de terceros aprobado). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: verification_required message: >- an approved identity verification of the third party is required: pass verification_id components: schemas: CardObject: type: object properties: card_id: type: string account_id: type: string physical: type: boolean cardholder_kind: type: string enum: - account - person cardholder_name: type: string status: type: string enum: - pending_activation - active - frozen - cancelled spending_asset: type: string enum: - USDT - USDC - BTC - GOLD description: >- Saldo desde el que gastan las compras de la tarjeta. USDT/USDC 1:1 con el USD; BTC/GOLD convertidos al precio del momento de cada evento. USDT por defecto. Cambiarlo solo afecta compras futuras. limits: type: object description: >- Límites de gasto, siempre medidos en USD, independientes del asset de gasto. properties: per_transaction: type: string daily: type: string monthly: type: string creation_fee: type: string cancellation_fee: type: string created_at: type: string format: date-time updated_at: type: string format: date-time 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. responses: 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 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. ````