> ## 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 结算

> 从对应的本地法币余额扣除 BOB、MXN 或 ARS payout

export const EnvUrls = ({lang = "en"}) => {
  const T = {
    en: {
      test: "Test",
      live: "Live",
      hint: "Same API on both environments — build against test first, then go live by swapping the base URL and the key.",
      guide: "Environments and testing",
      href: "/en/environment-testing"
    },
    es: {
      test: "Test",
      live: "Live",
      hint: "La misma API en ambos ambientes — construye primero contra test y pasa a live cambiando la URL base y la key.",
      guide: "Entorno y pruebas",
      href: "/es/environment-testing"
    },
    zh: {
      test: "Test",
      live: "Live",
      hint: "两个环境的 API 完全一致——先在 test 环境构建，再通过切换基础 URL 和密钥上线。",
      guide: "环境与测试",
      href: "/zh/environment-testing"
    }
  };
  const t = T[lang] || T.en;
  const row = (label, url, keyPattern, badgeCls) => <div className="flex flex-wrap items-center gap-2 px-3 py-2">
      <span className={"rounded px-1.5 py-0.5 text-xs font-semibold uppercase tracking-wide " + badgeCls}>
        {label}
      </span>
      <code className="text-xs">{url}</code>
      <span className="text-xs text-gray-400 dark:text-zinc-500">·</span>
      <code className="text-xs">{keyPattern}</code>
    </div>;
  return <div className="my-4 rounded-xl border border-gray-200 dark:border-zinc-700 divide-y divide-gray-200 dark:divide-zinc-700 text-sm not-prose">
      {row(t.test, "https://cryptobank.qbank.cl/platform", "pk_test_...", "bg-amber-100 text-amber-800 dark:bg-amber-900/40 dark:text-amber-300")}
      {row(t.live, "https://api.qbank.cl/platform", "pk_...", "bg-emerald-100 text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-300")}
      <p className="px-3 py-2 text-xs text-gray-500 dark:text-zinc-400 m-0">
        {t.hint} <a href={t.href}>{t.guide} →</a>
      </p>
    </div>;
};

<EnvUrls lang="zh" />

<Note>
  本页介绍 BOB、MXN 和 ARS 的同币种结算。不支持将一种法币余额转换为另一种
  法币。
</Note>

当 payout 货币与 `settlement_asset` 相同时，payout 可以从本地法币余额
扣款。settlement rate 为 `"1"`，settlement spread 为零。以 USDT 配置的
费用会按锁定报价换算为 payout 货币，并向上取整到该货币的最小单位。

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as 你的应用
    participant CB as CBPay
    App->>CB: 使用 settlement_asset=BOB 创建 payout
    CB->>CB: 校验货币和最小单位
    CB-->>App: 返回带 settlement 字段的 202 processing
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-bob-001" \
  -d '{
    "country": "BO",
    "currency": "BOB",
    "method": "bank_transfer",
    "local_amount": "100.00",
    "settlement_asset": "BOB",
    "beneficiary": {
      "name": "Ana Pérez",
      "country_code": "BO",
      "bank_code": "0016",
      "account_number": "1234567890",
      "account_type": "checking"
    },
    "idempotency_key": "payout-bob-001"
  }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "payout_id": "7b2e…",
  "country": "BO",
  "currency": "BOB",
  "local_amount": "100.00",
  "settlement_asset": "BOB",
  "settlement_amount": "100.01",
  "settlement_rate": "1",
  "settlement_spread": "0",
  "platform_settlement_spread": "0",
  "status": "processing",
  "funds_debited": true
}
```

收款人收到 `100.00 BOB`；额外的 `0.01 BOB` 是已配置的费用，按本地
货币换算并向上取整。若 payout 失败，冻结的 `settlement_amount` 会原额
退回。

`GET /v1/rates` 会将本地法币资产标记为 `same_currency_only: true`：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "settlement": {
    "default_asset": "USD",
    "assets": [
      {
        "asset": "BOB",
        "available": true,
        "settlement_rate": "1",
        "same_currency_only": true
      }
    ]
  }
}
```

系统会拒绝 cross-fiat settlement。例如，MXN payout 不能从 BOB 余额扣款：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "pricing_unavailable",
  "message": "fiat settlement is only available in the payout currency"
}
```

对于 BOB、MXN 和 ARS，超过两位小数的金额会返回 `400 invalid_amount`；
例如 `"100.001"`。请使用 payout 货币的最小单位，CBPay 不会静默四舍五入
本地金额。

请参阅[错误](../errors)了解公开错误契约。

<AccordionGroup>
  <Accordion title="可以从 BOB 余额支付 MXN payout 吗？">
    不可以。本版本的 cross-fiat settlement 不是 FX 转换路径。请选择 payout
    货币或其他受支持的 settlement asset。
  </Accordion>

  <Accordion title="同币种法币会收取 settlement spread 吗？">
    不会。同币种法币使用等额 rate 和零 settlement spread。已配置的费用仍会
    收取并转换为法币。
  </Accordion>
</AccordionGroup>

## USD 作为主账本资产

账户的 `settlement_asset` 与 `payin_settlement_asset` 默认值为 `USD`，可随时用
`PUT /v1/settlement` 更改；进行中的操作不会重新报价。

USD 账本金额使用美分（两位小数）。直接入账、扣账、费用以及支持 USD
资产字段的 payout、checkout、POS 和卡片流程使用 USD。USD 与 USDT 之间
的 swap 按 1:1 计价，不使用 FX 预言机。BOB、MXN、ARS 仍是独立的法币
账本资产；v1 中这些资产的 money-out 定价仍不可用。

USD 主账户的 payin 直接入账时，响应包含 `credit_asset: USD` 以及以美分
表示的 fiat 入账金额；`usdt_credited` 仍用于 USD 等值报表。争议 hold
跟随实际入账资产：USD 入账使用 `hold_asset: USD`。`disputed` 与 `held` 使用 hold 资产的单位；
`disputed_usdt` 与 `held_usdt` 是归一化后的等值字段。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.