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

# Fiat payout settlement

> Debit BOB, MXN or ARS payouts from the matching local-fiat balance

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="en" />

<Note>
  This page covers same-currency settlement for BOB, MXN and ARS. It does not
  convert one fiat balance into another.
</Note>

Payouts can debit a local-fiat balance when the payout currency and
`settlement_asset` are the same. The settlement rate is `"1"` and settlement
spreads are zero. Fees configured in USDT are converted using the locked quote
and rounded up to the smallest unit of the payout currency.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Your app
    participant CB as CBPay
    App->>CB: POST payout with settlement_asset=BOB
    CB->>CB: Validate currency and minor unit
    CB-->>App: 202 processing with settlement fields
```

```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
}
```

The beneficiary receives `100.00 BOB`; the extra `0.01 BOB` is the configured
fee converted and rounded up in local currency. The exact
`settlement_amount` is held and is refunded unchanged if the payout fails.

`GET /v1/rates` marks local-fiat assets with `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 is rejected. For example, a MXN payout cannot debit a
BOB balance:

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

For BOB, MXN and ARS, amounts with more than two decimal places are rejected:
`"100.001"` returns `400 invalid_amount`. Use the payout currency's minor
unit; CBPay does not silently round the requested local amount.

See [Errors](/en/errors) for the public error contract.

<AccordionGroup>
  <Accordion title="Can I debit BOB for an MXN payout?">
    No. Cross-fiat settlement is not an FX conversion path in this release.
    Choose the payout currency or use a supported non-fiat settlement asset.
  </Accordion>

  <Accordion title="Are settlement spreads applied to same-currency fiat?">
    No. Same-currency fiat settlement uses an identity rate and zero settlement
    spreads. Configured fees are still charged and converted into fiat.
  </Accordion>
</AccordionGroup>

## USD as the principal ledger asset

Accounts use `USD` as the default for `settlement_asset` and
`payin_settlement_asset`; change it any time with `PUT /v1/settlement`.
In-flight operations are never re-quoted.

USD ledger amounts use cents (two decimal places). Direct credits and debits,
fees, and supported payout, checkout, POS, and card paths use USD only where
their asset field accepts it. Swaps between USD and USDT use 1:1 pricing and
do not use an FX oracle. BOB, MXN, and ARS remain separate fiat-ledger
assets; v1 money-out pricing for those assets remains unavailable.

A payin credited directly to a USD-principal account exposes
`credit_asset: USD` and the credited fiat amount in cents; `usdt_credited`
remains the USD-equivalent reporting field. A controversy hold follows the
credited asset: USD credits use `hold_asset: USD`. `disputed` and `held` use hold-asset units;
`disputed_usdt` and `held_usdt` are normalized equivalents.


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