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

# 创建 payout

> 向本地银行账户派发法币。本地金额按**你账户的汇率**(与 `GET /v1/rates` 返回的相同)转换为 USDT;扣除 `usdt_amount` 加固定费用(如有配置)并冻结,直到派发完成。若失败,全额退款。

**从任意余额支付**:默认从你账户的默认结算资产扣款(USDT,除非通过 `PUT /v1/settlement` 更改)。传 `settlement_asset`(USDT、USDC、BTC 或 GOLD)可让这笔操作从其他余额支付:USDT 总额按当时的有效结算价格转换为该资产(见 `GET /v1/rates` 的 `settlement` 块),扣款、冻结以及失败时的退款都在该资产中且金额完全一致。若 BTC/GOLD 的执行价格不可用,请求返回 `503 pricing_unavailable`;波动性资产还有单笔限额(`422 settlement_limit_exceeded`)。

必须提供幂等键(请求体字段或 `Idempotency-Key` 请求头)。使用相同键重试会返回原始 payout(`200` 且 `idempotency_hit: true`)。



## OpenAPI

````yaml /openapi.zh.yaml post /v1/payouts
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": "<code>", "message": "<detail>"}`。
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/payouts:
    post:
      tags:
        - 付款(Payouts)
      summary: 创建 payout
      description: >-
        向本地银行账户派发法币。本地金额按**你账户的汇率**(与 `GET /v1/rates` 返回的相同)转换为 USDT;扣除
        `usdt_amount` 加固定费用(如有配置)并冻结,直到派发完成。若失败,全额退款。


        **从任意余额支付**:默认从你账户的默认结算资产扣款(USDT,除非通过 `PUT /v1/settlement` 更改)。传
        `settlement_asset`(USDT、USDC、BTC 或 GOLD)可让这笔操作从其他余额支付:USDT
        总额按当时的有效结算价格转换为该资产(见 `GET /v1/rates` 的 `settlement`
        块),扣款、冻结以及失败时的退款都在该资产中且金额完全一致。若 BTC/GOLD 的执行价格不可用,请求返回 `503
        pricing_unavailable`;波动性资产还有单笔限额(`422 settlement_limit_exceeded`)。


        必须提供幂等键(请求体字段或 `Idempotency-Key` 请求头)。使用相同键重试会返回原始 payout(`200` 且
        `idempotency_hit: true`)。
      operationId: createPayout
      parameters:
        - $ref: '#/components/parameters/idempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - country
                - currency
                - amount
              properties:
                country:
                  type: string
                  description: ISO 3166-1 alpha-2 目标国家(例如 CL、PE、MX)。
                currency:
                  type: string
                  description: 本地货币(例如 CLP、PEN、MXN)。
                method:
                  type: string
                  description: >-
                    来自 `GET /v1/payouts/methods` 的 payout 方式(例如
                    `bank_transfer`)。
                amount:
                  type: string
                  description: 本地货币金额,正数十进制字符串。
                  example: '50000.00'
                beneficiary:
                  type: object
                  additionalProperties:
                    type: string
                  description: >
                    目标账户详情。所需键取决于国家与方式;参见 `GET /v1/payouts/methods` 和

                    `GET /v1/payouts/banks`。示例:智利为 RUT + 银行,墨西哥为 CLABE,秘鲁为
                    CCI。巴西 PIX:`pix_key` + `pix_key_type`(cpf、

                    cnpj、phone、email、evp),或不用键的银行账户,使用

                    `bank_code`(ISPB)+ `branch_code` + `account_number` +
                    `tax_id`。

                    厄瓜多尔(汇款走廊):`document_value`(身份证号)加上在同一对象中平铺的汇款人数据(`sender_name`、

                    `sender_document_value` 等);可选的结构化姓名字段

                    (`given_name`、`first_surname` 等及其对应的 `sender_*` 字段)

                    优先于对 `name` 的自动拆分。
                beneficiary_contact_id:
                  type: string
                  format: uuid
                  description: >-
                    使用联系人在该国家(及方式,若传入)最近保存的受益人,而无需再次输入 `beneficiary`。显式
                    `beneficiary` 始终优先;若联系人没有则返回 422 no_saved_destination。
                save_contact:
                  type: boolean
                  default: true
                  description: 受益人会自动保存为联系人;传 false 可跳过。
                description:
                  type: string
                settlement_asset:
                  type: string
                  enum:
                    - USDT
                    - USDC
                    - BTC
                    - GOLD
                  description: >-
                    此操作要扣款的虚拟余额。省略则使用账户的默认结算资产(USDT,除非通过 `PUT /v1/settlement`
                    更改)。
                idempotency_key:
                  type: string
            examples:
              cl_bank_transfer:
                summary: 智利 — 银行转账(CLP)
                value:
                  country: CL
                  currency: CLP
                  method: bank_transfer
                  amount: '100000'
                  beneficiary:
                    name: Pedro Soto Fuentes
                    tax_id: 12.345.678-5
                    bank_code: '012'
                    account_type: checking
                    account_number: '123456789'
                  description: 供应商付款
                  idempotency_key: cl-prov-0091
              pe_bank_transfer:
                summary: 秘鲁 — 经 CCI 银行转账(PEN)
                value:
                  country: PE
                  currency: PEN
                  method: bank_transfer
                  amount: '1000.00'
                  beneficiary:
                    name: Rosa Alvarez Diaz
                    account_number: 219300123456789020
                  idempotency_key: pe-cci-3310
              pe_yape:
                summary: 秘鲁 — Yape 至手机号(PEN)
                value:
                  country: PE
                  currency: PEN
                  method: yape
                  amount: '150.00'
                  beneficiary:
                    name: Luis Ramos Vega
                    phone: '51987654321'
                  idempotency_key: pe-yape-8874
              mx_clabe:
                summary: 墨西哥 — SPEI 至 CLABE(MXN)
                value:
                  country: MX
                  currency: MXN
                  method: bank_transfer
                  amount: '1500.00'
                  beneficiary:
                    name: Maria Lopez
                    account_type: clabe
                    account_number: 12180001234567896
                  idempotency_key: mx-clabe-8841
              mx_debit_card:
                summary: 墨西哥 — SPEI 至借记卡(MXN)
                value:
                  country: MX
                  currency: MXN
                  method: bank_transfer
                  amount: '800.00'
                  beneficiary:
                    name: Jorge Herrera
                    account_type: debit_card
                    account_number: '4152313412341234'
                    bank_code: '40012'
                  idempotency_key: mx-card-1102
              ve_pago_movil:
                summary: 委内瑞拉 — Pago Móvil(VES)
                value:
                  country: VE
                  currency: VES
                  method: pago_movil
                  amount: '2000.00'
                  beneficiary:
                    phone: '04141234567'
                    bank_code: '0102'
                    document_value: V12345678
                  idempotency_key: ve-pm-5567
              ve_bank_transfer:
                summary: 委内瑞拉 — 银行转账(VES)
                value:
                  country: VE
                  currency: VES
                  method: bank_transfer
                  amount: '5000.00'
                  beneficiary:
                    name: Carmen Delgado
                    account_number: 1020123456789012400
                    document_value: V87654321
                  idempotency_key: ve-bank-7810
              bo_bank_transfer:
                summary: 玻利维亚 — ACH 转账(BOB)
                value:
                  country: BO
                  currency: BOB
                  method: bank_transfer
                  amount: '1382.00'
                  beneficiary:
                    name: Juan Quispe Mamani
                    tax_id: '4567890'
                    bank_code: '1016'
                    account_number: '1234567890'
                  idempotency_key: bo-ach-2204
              br_pix:
                summary: 巴西 — 按 PIX 键(BRL)
                value:
                  country: BR
                  currency: BRL
                  method: pix
                  amount: '350.00'
                  beneficiary:
                    name: João da Silva
                    tax_id: 123.456.789-09
                    pix_key_type: cpf
                    pix_key: '12345678909'
                  idempotency_key: br-pix-3321
              ec_bank_transfer:
                summary: 厄瓜多尔 — 银行转账(USD,含汇款人数据的汇款)
                value:
                  country: EC
                  currency: USD
                  method: bank_transfer
                  amount: '250.00'
                  beneficiary:
                    name: Carlos Andrade Vera
                    document_value: '1712345678'
                    account_number: '2203456789'
                    sender_name: Ana Torres Silva
                    sender_document_value: V23456789
                    sender_country: US
                  idempotency_key: ec-bank-4471
              ec_deuna:
                summary: 厄瓜多尔 — 按手机号的 DE UNA 钱包(USD)
                value:
                  country: EC
                  currency: USD
                  method: deuna
                  amount: '80.00'
                  beneficiary:
                    name: Lucia Paredes Mora
                    document_value: '0923456781'
                    phone: '0998765432'
                    sender_name: Ana Torres Silva
                  idempotency_key: ec-deuna-5520
              ec_cash_pickup:
                summary: 厄瓜多尔 — 网点现金领取(USD)
                value:
                  country: EC
                  currency: USD
                  method: cash_pickup
                  amount: '120.00'
                  beneficiary:
                    name: Miguel Zambrano Loor
                    document_value: '1309876543'
                    sender_name: Ana Torres Silva
                  idempotency_key: ec-cash-6612
              ec_cnb:
                summary: 厄瓜多尔 — 非银行代理点现金(USD)
                value:
                  country: EC
                  currency: USD
                  method: cnb
                  amount: '60.00'
                  beneficiary:
                    name: Rosa Cedeño Vera
                    document_value: '0801234567'
                    sender_name: Ana Torres Silva
                  idempotency_key: ec-cnb-7703
              py_bank_transfer:
                summary: 巴拉圭 — 银行转账(PYG)
                value:
                  country: PY
                  currency: PYG
                  method: bank_transfer
                  amount: '500000'
                  beneficiary:
                    name: Sofia Benitez
                    tax_id: '4123456'
                    bank_code: '0011'
                    account_number: '600123456'
                  idempotency_key: py-bank-9917
              cl_paid_from_btc:
                summary: 智利 — 从 BTC 余额支付(settlement_asset)
                value:
                  country: CL
                  currency: CLP
                  method: bank_transfer
                  amount: '100000'
                  beneficiary:
                    name: Pedro Soto Fuentes
                    tax_id: 12.345.678-5
                    bank_code: '012'
                    account_type: checking
                    account_number: '123456789'
                  settlement_asset: BTC
                  idempotency_key: cl-btc-0192
      responses:
        '200':
          description: 既有 payout 的幂等重放。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
              example:
                payout_id: 7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: invoice-8841
                country: MX
                currency: MXN
                method: bank_transfer
                local_amount: '1500.00'
                fx_rate: '17.50'
                usdt_amount: '85.714286'
                fee: '0.300000'
                total_debit: '86.014286'
                settlement_asset: USDT
                settlement_amount: '86.014286'
                settlement_rate: '1'
                beneficiary:
                  name: Maria Lopez
                  account_type: clabe
                  account_number: 12180001234567896
                description: 发票 8841
                status: processing
                status_code: ''
                status_message: ''
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
                idempotency_hit: true
        '202':
          description: payout 已受理并派发中。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
              example:
                payout_id: 7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: invoice-8841
                country: MX
                currency: MXN
                method: bank_transfer
                local_amount: '1500.00'
                fx_rate: '17.50'
                usdt_amount: '85.714286'
                fee: '0.300000'
                total_debit: '86.014286'
                settlement_asset: USDT
                settlement_amount: '86.014286'
                settlement_rate: '1'
                beneficiary:
                  name: Maria Lopez
                  account_type: clabe
                  account_number: 12180001234567896
                description: 发票 8841
                status: processing
                status_code: ''
                status_message: ''
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientFunds'
        '403':
          description: 账户未激活(`account_blocked`)或缺少账户凭证。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: account_blocked
                message: account is not active
        '422':
          description: >
            该货币无外汇汇率(`currency_not_supported`),或 payout 被预先拒绝——响应为带 `status:
            failed` 的 payout 对象,扣款已退回。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/Payout'
              example:
                payout_id: 7d5c2f0a-1e9b-4a6d-8f3c-0b2a1d9e8c7f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: invoice-8841
                country: MX
                currency: MXN
                method: bank_transfer
                local_amount: '1500.00'
                fx_rate: '17.50'
                usdt_amount: '85.714286'
                fee: '0.300000'
                total_debit: '86.014286'
                settlement_asset: USDT
                settlement_amount: '86.014286'
                settlement_rate: '1'
                beneficiary:
                  name: Maria Lopez
                  account_type: clabe
                  account_number: 12180001234567896
                description: 发票 8841
                status: failed
                status_code: core_rejected
                status_message: beneficiary account is invalid
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
        '503':
          description: 付款通道暂时不可用(`channel_unavailable`);请稍后使用相同的幂等键重试。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: channel_unavailable
                message: >-
                  the payout channel is temporarily unavailable, please retry
                  later
components:
  parameters:
    idempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: '`idempotency_key` 请求体字段的替代方式。'
      schema:
        type: string
  schemas:
    Payout:
      type: object
      properties:
        payout_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        idempotency_key:
          type: string
        country:
          type: string
        currency:
          type: string
        method:
          type: string
        local_amount:
          type: string
        fx_rate:
          type: string
          description: 执行时你账户的汇率(每 1 USDT 的本地单位数)。
        usdt_amount:
          type: string
        fee:
          type: string
        total_debit:
          type: string
        settlement_asset:
          type: string
          enum:
            - USDT
            - USDC
            - BTC
            - GOLD
          description: 该操作实际扣款的虚拟余额。
        settlement_amount:
          type: string
          description: >-
            从结算资产余额实际扣除的准确金额(以该资产单位表示)。当资产为 USDT 时等于 `total_debit`。若 payout
            失败,退款即为该准确金额——绝不重新计价。
        settlement_rate:
          type: string
          description: 用于转换 USDT 总额的结算资产有效 USD 单价(USDT/USDC 为 "1")。
        beneficiary:
          type: object
        description:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        status_code:
          type: string
        status_message:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        idempotency_hit:
          type: boolean
          description: 当响应为幂等重放时为 true。
    Error:
      type: object
      properties:
        error:
          type: string
          description: 机器可读的错误代码(snake_case)。
          example: insufficient_funds
        message:
          type: string
          description: 人类可读的说明。
  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
    InsufficientFunds:
      description: 账户余额不足以完成此操作(`insufficient_funds`)。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: insufficient_funds
            message: account balance is not enough for this operation
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        会话 JWT(来自注册/登录)或 API key(`pk_...`)。
        也接受 `X-API-Key: <token>` 作为替代请求头。

````