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

# Settlement de payouts fiat

> Debita payouts BOB, MXN o ARS desde el saldo fiat local correspondiente

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

<Note>
  Esta página cubre settlement en la misma moneda para BOB, MXN y ARS. No
  convierte un saldo fiat en otra moneda fiat.
</Note>

Un payout puede debitar un saldo fiat local cuando la moneda del payout y
`settlement_asset` son iguales. La tasa de settlement es `"1"` y los spreads
de settlement son cero. Las comisiones configuradas en USDT se convierten con
la cotización bloqueada y se redondean hacia arriba a la unidad mínima de la
moneda del payout.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Tu app
    participant CB as CBPay
    App->>CB: POST payout con settlement_asset=BOB
    CB->>CB: Valida moneda y unidad mínima
    CB-->>App: 202 processing con campos settlement
```

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

El beneficiario recibe `100.00 BOB`; los `0.01 BOB` adicionales son la
comisión configurada, convertida y redondeada hacia arriba en moneda local.
Si el payout falla, el `settlement_amount` retenido se reembolsa sin cambios.

`GET /v1/rates` marca los assets fiat locales con `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
      }
    ]
  }
}
```

El settlement cross-fiat se rechaza. Por ejemplo, un payout MXN no puede
debitar un saldo BOB:

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

Para BOB, MXN y ARS, los montos con más de dos decimales responden
`400 invalid_amount`; por ejemplo, `"100.001"`. Usa la unidad mínima de la
moneda del payout: CBPay no redondea silenciosamente el monto local.

Consulta [Errores](/es/errors) para el contrato público de errores.

<AccordionGroup>
  <Accordion title="¿Puedo debitar BOB para un payout MXN?">
    No. En esta versión el settlement cross-fiat no es una conversión FX.
    Elige la moneda del payout u otro asset de settlement soportado.
  </Accordion>

  <Accordion title="¿Se aplican spreads al fiat de la misma moneda?">
    No. Usa tasa identidad y spreads de settlement cero. Las comisiones configuradas
    siguen cobrándose y se convierten a fiat.
  </Accordion>
</AccordionGroup>

## USD como activo principal del ledger

Las cuentas usan `USD` como valor predeterminado de `settlement_asset` y
`payin_settlement_asset`; cámbialo cuando quieras con `PUT /v1/settlement`.
Las operaciones en vuelo nunca se vuelven a cotizar.

Los montos del ledger en USD usan centavos (dos decimales). Los créditos y
d débitos directos, las comisiones y los flujos de payout, checkout, POS y
tarjetas usan USD solo cuando el campo de activo de ese flujo lo acepta. Los
swaps entre USD y USDT usan paridad 1:1 y no consultan un oráculo FX. BOB,
MXN y ARS siguen siendo activos fiat separados del ledger; en v1 el pricing
de money-out para esos activos sigue no disponible.

Un payin acreditado directamente a una cuenta USD-principal expone
`credit_asset: USD` y el monto fiat acreditado en centavos; `usdt_credited`
sigue siendo el equivalente USD para reportes. El hold de una controversia
sigue el activo acreditado: los créditos USD usan `hold_asset: USD`. `disputed` y `held` usan las
unidades del activo retenido; `disputed_usdt` y `held_usdt` son equivalentes
normalizados.


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