> ## 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. # Create a payin (top-up charge) > Creates a fiat top-up. With `method: "qr"` (default) an active QR charge is generated through the processor — in Bolivia the local interoperable QR, in Brazil a dynamic PIX QR whose `charge` carries the QR image and the "copia e cola" payload. With `method: "bank_transfer"` the deposit is announced and the response carries the reference the sender must include so the arriving transfer is matched and credited automatically — a short 12-character alphanumeric code that fits any bank concept field (some rails cap it at 20 characters with no special characters). With `method: "fintoc"` (Chile) the response carries a hosted `payment_url`: the payer opens it and transfers from any Chilean bank or wallet; the deposit is detected, validated and credited automatically. With `method: "card"` (Bolivia) the response carries a hosted `payment_url` for a 3-D Secure card checkout branded with your organization — card data never touches your integration. With `method: "checkout"` the response carries a public `checkout_url` — a branded universal checkout link denominated in the virtual balance of your choice (`settlement_asset`: USDT, USDC, BTC or GOLD). The payer picks any country with a live payin corridor (quoted local amount), any of the 4 crypto options (exclusive deposit address with a scannable QR), or pays instantly from the CBPay app via the merchant QR/alias; every payment is auto-converted to the settlement asset unless paid in the same asset. The first method that completes the payment wins. Charging is free; the payin fee applies when the deposit is credited. ## OpenAPI ````yaml /openapi.yaml post /v1/payins openapi: 3.1.0 info: title: CBPay API version: '1.89' description: | CBPay is a multi-currency payment platform: fiat payouts and collections across Latin America, internal transfers, on-chain funding and withdrawals, and KYC screening. Every account holds four independent virtual balances — USDT (the operating currency), USDC, BTC and GOLD (grams of fine gold) — that never mix or convert automatically. Payouts and service fees can be paid from any of the four balances: set a default with `PUT /v1/settlement` or override per payout with `settlement_asset`. All amounts are decimal strings in each currency's precision (6 decimals for USDT/USDC/GOLD, 8 for BTC). Errors always return `{"error": "", "message": ""}`. servers: - url: https://api.qbank.cl/platform description: Live (production, real money) - url: https://cryptobank.qbank.cl/platform description: Test (sandbox, simulated money — pk_test_ keys) security: - bearerAuth: [] tags: - name: Receipts description: >- Branded PDF receipt per operation, with a public signed-QR authenticity check, receipt_url on every response/webhook and automatic email delivery on final states. - name: Authentication description: Register and log in account members. Sessions last 24 hours. - name: Account description: Profile, members and API keys of the calling account. - name: Balances description: Balances, movement history and FX rates. - name: Payouts description: >- Fiat dispersals debited from the settlement balance of your choice (USDT by default). - name: Payins description: Fiat top-ups credited to the USDT balance. - name: Transfers - name: Contacts - name: Swaps description: >- Free internal transfers between CBPay accounts (person or company, any combination). - name: Crypto description: On-chain funding and withdrawals (TRON, Ethereum and Bitcoin). - name: Segregated wallets description: >- On-chain wallets with their own balance (companies unlimited; persons 1 per network+asset pair) — create, import, send, export the private key and auto-forward. The balance lives on-chain, never in the ledger. - name: QR Crypto POS description: >- Amount-bearing crypto QR charges for processors with physical POS terminals (company accounts): verified merchants, exclusive address + QR per charge, early payment detection, per-merchant reconciliation and refunds over the crypto withdrawal rail. - name: KYC / KYB - name: AML screening description: >- Identity verification: KYC for persons, KYB for companies, with AML screening, rescreening and continuous monitoring. - name: Wallet screening description: >- AML risk assessment of blockchain addresses (sanctions, illicit-fund exposure) with a per-scan fee, plus free automatic protection on withdrawals and deposits. - name: Analytics - name: Webhooks description: Subscriptions to receive signed event notifications. - name: Status description: Service availability. - name: Banking description: >- Real bank accounts: receive, hold and send money over international banking rails. - name: Cards description: >- Virtual and physical cards that spend Just-In-Time from the account's USDT balance, with per-card spending limits. - name: Security (OTP) description: >- One-time verification codes over SMS/WhatsApp/email protecting sensitive actions, plus self-service 2FA preferences. Applies to user sessions only — API keys are exempt. - name: Passkeys description: >- Passwordless sign-in with the device's biometrics (Face ID, Touch ID, Windows Hello, security keys) via WebAuthn, authenticator apps (TOTP) with backup codes, and session/device management. - name: Social login description: >- Passwordless sign up and sign in with Google, Apple, Microsoft and Facebook via token exchange. The front end obtains the provider credential; the API verifies it and issues the CBPay session. paths: /v1/payins: post: tags: - Payins summary: Create a payin (top-up charge) description: >- Creates a fiat top-up. With `method: "qr"` (default) an active QR charge is generated through the processor — in Bolivia the local interoperable QR, in Brazil a dynamic PIX QR whose `charge` carries the QR image and the "copia e cola" payload. With `method: "bank_transfer"` the deposit is announced and the response carries the reference the sender must include so the arriving transfer is matched and credited automatically — a short 12-character alphanumeric code that fits any bank concept field (some rails cap it at 20 characters with no special characters). With `method: "fintoc"` (Chile) the response carries a hosted `payment_url`: the payer opens it and transfers from any Chilean bank or wallet; the deposit is detected, validated and credited automatically. With `method: "card"` (Bolivia) the response carries a hosted `payment_url` for a 3-D Secure card checkout branded with your organization — card data never touches your integration. With `method: "checkout"` the response carries a public `checkout_url` — a branded universal checkout link denominated in the virtual balance of your choice (`settlement_asset`: USDT, USDC, BTC or GOLD). The payer picks any country with a live payin corridor (quoted local amount), any of the 4 crypto options (exclusive deposit address with a scannable QR), or pays instantly from the CBPay app via the merchant QR/alias; every payment is auto-converted to the settlement asset unless paid in the same asset. The first method that completes the payment wins. Charging is free; the payin fee applies when the deposit is credited. operationId: createPayin requestBody: required: true content: application/json: schema: type: object required: - country - currency - amount properties: country: type: string example: BO description: >- Corridor country. Required for every method except `checkout`, where it is optional and only preselects the payer's country on the page. currency: type: string example: BOB description: >- Corridor currency. Required for every method except `checkout`, which rejects it with 400 — the charge is denominated in `settlement_asset`. amount: type: string description: >- Positive decimal string. Local currency amount for corridor methods; for `checkout` it is denominated in the `settlement_asset` ("50" USDT, "0.001" BTC, "2" grams of gold). description: type: string channel: type: string description: Optional channel hint passed to the core. expires_in: type: integer description: >- Charge expiration in seconds. For `checkout` it accepts 600 to 604800 (10 minutes to 7 days; default 24 hours). method: type: string enum: - qr - bank_transfer - fintoc - card - checkout default: qr description: >- Collection mode. `qr` creates an active QR charge through the processor; `bank_transfer` announces an incoming deposit and returns the reference to include in the transfer description; `fintoc` (Chile only) returns a hosted `payment_url` where the payer transfers from any Chilean bank or wallet and the deposit is detected automatically; `card` (Bolivia) returns a hosted `payment_url` for a 3-D Secure card checkout; `checkout` returns a public `checkout_url` where the payer picks the payment method (QR, card, bank transfer or crypto). Use /v1/payins/collect for pull collections. idempotency_key: type: string description: >- Optional idempotency key (`fintoc`, `card` and `checkout` methods; also accepted as the `Idempotency-Key` header). A retry with the same key returns the original payin and its `payment_url`/`checkout_url` instead of opening a second payment session. customer: type: object description: >- Optional billing prefill for the card checkout (`card` method) — `email`, `first_name`, `last_name`, `address`, `city`, `country` (plain text, max 120 chars per field). The payer can complete or correct them on the page. success_url: type: string description: >- Optional public https URL (`card` and `checkout` methods) the payer is redirected to after an approved payment. failure_url: type: string description: >- Optional public https URL (`card` and `checkout` methods) the payer is redirected to when the payment fails or expires. expires_at: type: string format: date-time description: >- Optional RFC3339 expiry for the card payment session (`card` method, at least 15 minutes ahead; default 24 hours). settlement_asset: type: string enum: - USDT - USDC - BTC - GOLD default: USDT description: >- Checkout only — the virtual balance the charge is denominated in and settles into. Every payment is auto-converted to this asset on credit (same-asset payments skip conversion). Must be enabled for your organization (`422 settlement_asset_disabled` otherwise). examples: bo_qr: summary: Bolivia — QR charge (BOB) value: country: BO currency: BOB method: qr amount: '700.00' description: App top-up expires_in: 3600 br_pix_qr: summary: Brazil — dynamic PIX QR (BRL) value: country: BR currency: BRL method: qr amount: '120.00' description: Order 7719 expires_in: 1800 cl_announced_transfer: summary: Chile — announced bank transfer (CLP) value: country: CL currency: CLP method: bank_transfer amount: '500000' py_announced_transfer: summary: Paraguay — announced bank transfer (PYG, integer amounts) value: country: PY currency: PYG method: bank_transfer amount: '596000' cl_fintoc: summary: Chile — hosted payment page, any bank (CLP) value: country: CL currency: CLP method: fintoc amount: '150000' description: Top-up order 8841 idempotency_key: topup-8841 bo_card: summary: Bolivia — 3-D Secure card checkout (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: Universal checkout link — 50 USDT, any country/method value: method: checkout amount: '50' settlement_asset: USDT description: Order 8841 country: CL 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: Universal checkout link — 0.001 BTC settlement value: method: checkout amount: '0.001' settlement_asset: BTC description: Invoice 2210 idempotency_key: invoice-2210 responses: '201': description: Charge created. content: application/json: schema: type: object properties: payin_id: type: string format: uuid status: type: string example: pending charge: type: object description: Charge details (QR data, references) from the core. examples: qr: summary: 'QR charge (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: 'Announced deposit (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: 'Hosted payment page (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: 'Card payment page (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: 'Universal checkout link (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: The core rejected the charge (`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 unavailable (`core_unavailable`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: core_unavailable message: could not create the charge components: responses: BadRequest: description: Invalid request (see `error` code for the specific validation). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_json message: 'request body is not valid JSON: unknown field' Unauthorized: description: Missing or invalid credential (`unauthorized`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: invalid or missing credentials AccountRequired: description: This endpoint requires an account credential (`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: Machine-readable error code (snake_case). example: insufficient_funds message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer description: | Session JWT (from register/login) or API key (`pk_...`). `X-API-Key: ` is accepted as an alternative header. ````