> ## 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. # 创建 payin(充值收款) > 创建一笔法币充值。使用 `method: "qr"`(默认)会通过处理方生成主动 QR 收款——在玻利维亚为本地互通 QR,在巴西为动态 PIX QR,其 `charge` 携带 QR 图片和 "copia e cola" 载荷。使用 `method: "bank_transfer"` 会预告存款,响应携带付款人必须附上的参考号,以便到账转账被自动匹配入账——一个 12 位字母数字短码,适配任何银行附言字段(部分通道上限 20 个字符且不允许特殊字符)。使用 `method: "fintoc"`(智利)响应携带托管 `payment_url`:付款人打开后可从任意智利银行或钱包转账;存款会被自动检测、校验并入账。使用 `method: "card"`(玻利维亚)响应携带一个托管 3-D Secure 银行卡收银台的 `payment_url`,页面带有您组织的品牌 —— 银行卡数据绝不经过您的集成。使用 `method: "checkout"` 响应携带一个公开的 `checkout_url` —— 以您选择的虚拟余额计价的通用收款链接(`settlement_asset`:USDT、USDC、BTC 或 GOLD)。付款人可选择任何有可用 payin 走廊的国家(本地金额实时报价)、四个加密货币选项之一(带可扫描二维码的专属充值地址),或通过商户的 CBPay 二维码/别名从 CBPay 应用即时付款;每笔付款自动兑换为结算资产(以相同资产付款则不兑换)。最先完成支付的方式生效。创建收款免费;存款入账时收取 payin 费用。 ## OpenAPI ````yaml /openapi.zh.yaml post /v1/payins openapi: 3.1.0 info: title: CBPay API version: '1.89' description: > CBPay 是一个多币种支付平台:覆盖拉美的法币付款(payout)与收款(payin)、内部转账、链上充值与提现,以及 KYC 筛查。每个账户持有四个相互独立的虚拟余额——USDT(运营货币)、USDC、BTC 和 GOLD(纯金克数)——它们绝不混合也不会自动兑换。 payout 和服务费可从四个余额中的任意一个支付: 用 `PUT /v1/settlement` 设置默认值,或在单笔 payout 中用 `settlement_asset` 覆盖。 所有金额均为十进制字符串,遵循各货币的精度(USDT/USDC/GOLD 为 6 位小数,BTC 为 8 位)。错误始终返回 `{"error": "", "message": ""}`。 servers: - url: https://api.qbank.cl/platform description: Live（生产环境，真实资金） - url: https://cryptobank.qbank.cl/platform description: Test（沙盒，模拟资金 — pk_test_ 密钥） security: - bearerAuth: [] tags: - name: 凭证 description: >- 每笔操作的品牌化 PDF 凭证,附带公开的签名 QR 真伪校验、每个响应/webhook 中的 receipt_url,以及最终状态时的自动邮件发送。 - name: 身份认证 description: 注册与登录账户成员。会话有效期 24 小时。 - name: 账户 description: 调用账户的档案、成员与 API key。 - name: 余额 description: 余额、流水历史与外汇汇率。 - name: 付款(Payouts) description: 从你选择的结算余额扣款的法币派发(默认 USDT)。 - name: 收款(Payins) description: 入账到 USDT 余额的法币充值。 - name: 转账 - name: 联系人 - name: 兑换(Swaps) description: CBPay 账户之间的免费内部转账(个人或企业,任意组合)。 - name: 加密货币 description: 链上充值与提现(TRON、Ethereum 和 Bitcoin)。 - name: 隔离钱包 description: 拥有自身余额的链上钱包(企业不限数量;个人每个网络+资产组合 1 个)——创建、导入、发送、导出私钥与自动转发。余额存在于链上,从不进入账本。 - name: QR Crypto POS description: >- 面向拥有实体 POS 终端的处理商（企业账户）的定额加密货币二维码收款：已验证商户、每笔收款专属地址 + 二维码、支付早期检测、按商户对账，以及经加密货币提现通道的退款。 - name: KYC / KYB - name: AML 筛查 description: 身份验证:个人 KYC、企业 KYB,含 AML 筛查、重新筛查与持续监控。 - name: 钱包筛查 description: 区块链地址的 AML 风险评估(制裁、非法资金暴露),按次收费;另附提现与充值的免费自动防护。 - name: 分析 - name: Webhooks description: 接收签名事件通知的订阅。 - name: 状态 description: 服务可用性。 - name: 银行服务 description: 真实银行账户:通过国际银行通道接收、持有与发送资金。 - name: 卡片 description: 以 Just-In-Time 方式从账户 USDT 余额消费的虚拟卡与实体卡,支持按卡设置消费限额。 - name: 安全(OTP) description: >- 通过 SMS/WhatsApp/email 发送的一次性验证码,保护敏感操作;并提供自助 2FA 偏好设置。仅适用于用户会话——API key 豁免。 - name: 通行密钥 description: >- 通过 WebAuthn 使用设备生物识别(Face ID、Touch ID、Windows Hello、安全密钥)的无密码登录、带备份码的验证器应用(TOTP),以及会话/设备管理。 - name: 社交登录 description: >- 通过令牌交换以 Google、Apple、Microsoft 和 Facebook 实现无密码注册与登录。前端获取提供方凭证;API 验证后签发 CBPay 会话。 paths: /v1/payins: post: tags: - 收款(Payins) summary: 创建 payin(充值收款) description: >- 创建一笔法币充值。使用 `method: "qr"`(默认)会通过处理方生成主动 QR 收款——在玻利维亚为本地互通 QR,在巴西为动态 PIX QR,其 `charge` 携带 QR 图片和 "copia e cola" 载荷。使用 `method: "bank_transfer"` 会预告存款,响应携带付款人必须附上的参考号,以便到账转账被自动匹配入账——一个 12 位字母数字短码,适配任何银行附言字段(部分通道上限 20 个字符且不允许特殊字符)。使用 `method: "fintoc"`(智利)响应携带托管 `payment_url`:付款人打开后可从任意智利银行或钱包转账;存款会被自动检测、校验并入账。使用 `method: "card"`(玻利维亚)响应携带一个托管 3-D Secure 银行卡收银台的 `payment_url`,页面带有您组织的品牌 —— 银行卡数据绝不经过您的集成。使用 `method: "checkout"` 响应携带一个公开的 `checkout_url` —— 以您选择的虚拟余额计价的通用收款链接(`settlement_asset`:USDT、USDC、BTC 或 GOLD)。付款人可选择任何有可用 payin 走廊的国家(本地金额实时报价)、四个加密货币选项之一(带可扫描二维码的专属充值地址),或通过商户的 CBPay 二维码/别名从 CBPay 应用即时付款;每笔付款自动兑换为结算资产(以相同资产付款则不兑换)。最先完成支付的方式生效。创建收款免费;存款入账时收取 payin 费用。 operationId: createPayin requestBody: required: true content: application/json: schema: type: object required: - country - currency - amount properties: country: type: string example: BO description: 走廊国家。除 `checkout` 外所有方式必填;对 `checkout` 为可选,仅用于在页面上预选付款人的国家。 currency: type: string example: BOB description: >- 走廊货币。除 `checkout` 外所有方式必填;`checkout` 会以 400 拒绝该字段 —— 收款以 `settlement_asset` 计价。 amount: type: string description: >- 正数十进制字符串。走廊方式为本地货币金额;`checkout` 以 `settlement_asset` 计价("50" USDT、"0.001" BTC、"2" 克黄金)。 description: type: string channel: type: string description: 传递给核心的可选渠道提示。 expires_in: type: integer description: 收款过期时间(秒)。对 `checkout` 取值 600 到 604800(10 分钟到 7 天;默认 24 小时)。 method: type: string enum: - qr - bank_transfer - fintoc - card - checkout default: qr description: >- 收款模式。`qr` 通过处理方创建主动 QR 收款;`bank_transfer` 预告一笔入账存款并返回需附在转账附言中的参考号;`fintoc`(仅智利)返回托管 `payment_url`,付款人可从任意智利银行或钱包转账,存款自动检测;`card`(玻利维亚)返回托管 3-D Secure 银行卡收银台的 `payment_url`;`checkout` 返回一个公开的 `checkout_url`,付款人在页面上自行选择支付方式(QR、银行卡、银行转账或加密货币)。pull 收款请使用 /v1/payins/collect。 idempotency_key: type: string description: >- 可选幂等键(`fintoc`、`card` 与 `checkout` 方式;也接受 `Idempotency-Key` 请求头)。使用相同键重试会返回原始 payin 及其 `payment_url`/`checkout_url`,而不会开启第二个支付会话。 customer: type: object description: >- 银行卡收银台的可选账单预填(`card` 方式)—— `email`、`first_name`、`last_name`、`address`、`city`、`country`(纯文本,每个字段最多 120 个字符)。付款人可在页面上补充或更正。 success_url: type: string description: 可选的公共 https URL(`card` 与 `checkout` 方式),支付获批后将付款人重定向至此。 failure_url: type: string description: 可选的公共 https URL(`card` 与 `checkout` 方式),支付失败或过期时将付款人重定向至此。 expires_at: type: string format: date-time description: 银行卡支付会话的可选 RFC3339 过期时间(`card` 方式,至少提前 15 分钟;默认 24 小时)。 settlement_asset: type: string enum: - USDT - USDC - BTC - GOLD default: USDT description: >- 仅 checkout —— 收款计价与结算的虚拟余额。每笔付款入账时自动兑换为该资产(以相同资产付款则不兑换)。须为您的组织启用(否则返回 `422 settlement_asset_disabled`)。 examples: bo_qr: summary: 玻利维亚 — QR 收款(BOB) value: country: BO currency: BOB method: qr amount: '700.00' description: 应用充值 expires_in: 3600 br_pix_qr: summary: 巴西 — 动态 PIX QR(BRL) value: country: BR currency: BRL method: qr amount: '120.00' description: 订单 7719 expires_in: 1800 cl_announced_transfer: summary: 智利 — 预告银行转账(CLP) value: country: CL currency: CLP method: bank_transfer amount: '500000' py_announced_transfer: summary: 巴拉圭 — 预告银行转账(PYG,整数金额) value: country: PY currency: PYG method: bank_transfer amount: '596000' cl_fintoc: summary: 智利 — 托管支付页,任意银行(CLP) value: country: CL currency: CLP method: fintoc amount: '150000' description: 充值订单 8841 idempotency_key: topup-8841 bo_card: summary: 玻利维亚 — 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: 通用收款链接 — 50 USDT(多国,预选智利) 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: 通用收款链接 — 0.001 BTC(以 BTC 结算) value: method: checkout amount: '0.001' settlement_asset: BTC description: Invoice 1204 idempotency_key: invoice-1204 responses: '201': description: 收款已创建。 content: application/json: schema: type: object properties: payin_id: type: string format: uuid status: type: string example: pending charge: type: object description: 来自核心的收款详情(QR 数据、参考号)。 examples: qr: summary: QR 收款(方式: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: 预告充值(方式: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: 托管支付页(方式:fintoc,智利) 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,玻利维亚) 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: 通用收款链接(方式: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: 核心拒绝了该收款(`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`)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: core_unavailable message: could not create the charge components: responses: BadRequest: description: 请求无效(具体校验见 `error` 代码)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_json message: 'request body is not valid JSON: unknown field' Unauthorized: description: 凭证缺失或无效(`unauthorized`)。 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: invalid or missing credentials AccountRequired: description: 此端点需要账户凭证(`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: 机器可读的错误代码(snake_case)。 example: insufficient_funds message: type: string description: 人类可读的说明。 securitySchemes: bearerAuth: type: http scheme: bearer description: | 会话 JWT(来自注册/登录)或 API key(`pk_...`)。 也接受 `X-API-Key: ` 作为替代请求头。 ````