Payouts

Un payout envía dinero en moneda local a una cuenta bancaria del país destino. El monto se convierte de moneda local a USDT con la tasa de tu cuenta (la de GET /v1/rates) y se debita usdt_amount + fee (el fijo, si está configurado) de tu saldo. Así se ve el ciclo completo, incluido qué pasa con tu saldo en cada paso:

1. Descubre los corredores disponibles

Los países, monedas y métodos disponibles los define CBPay. Consúltalos siempre por catálogo:

curl https://api.qbank.cl/platform/v1/payouts/methods \
  -H "Authorization: Bearer <token>"

{
  "items": [
    { "country": "CL", "currency": "CLP", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "bank_transfer" },
    { "country": "PE", "currency": "PEN", "method": "yape" },
    { "country": "BO", "currency": "BOB", "method": "qr" }
  ],
  "meta": { "retrieved": 4 }
}

Corredores y métodos disponibles:

País	Moneda	Métodos
Chile	CLP	`bank_transfer`
Perú	PEN	`bank_transfer`, `yape`
México	MXN	`bank_transfer` (SPEI: CLABE o tarjeta de débito)
Venezuela	VES	`bank_transfer`, `pago_movil`
Bolivia	BOB / USD	`bank_transfer`, `qr` (ver Payout QR)
Brasil	BRL	`pix` (por llave o a cuenta), `qr` (QR PIX — ver Payout QR)
Ecuador	USD	`bank_transfer`, `deuna`, `cash_pickup`, `cnb`
Paraguay	PYG	`bank_transfer`

La disponibilidad puede variar; el catálogo (GET /v1/payouts/methods) es siempre la fuente de verdad. Si un país tiene un solo método, method es opcional. Todos los métodos se cobran igual: tu tasa + fijo. Para transferencias bancarias necesitas además el catálogo de bancos (de ahí sale el bank_code del beneficiario):

curl "https://api.qbank.cl/platform/v1/payouts/banks?country=CL" \
  -H "Authorization: Bearer <token>"

{
  "items": [
    { "code": "001", "name": "Banco de Chile" },
    { "code": "012", "name": "Banco del Estado de Chile" },
    { "code": "016", "name": "Banco de Crédito e Inversiones" }
  ],
  "meta": { "retrieved": 3 }
}

2. Crea el payout

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "1500.00",
    "beneficiary": {
      "name": "María López",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "description": "Pago factura 8841",
    "idempotency_key": "factura-8841"
  }'

beneficiary es un objeto de pares clave/valor cuyos campos requeridos dependen del corredor (RUT y banco en Chile, CLABE en México, CCI en Perú, llave PIX en Brasil, etc.). El catálogo de métodos documenta los campos de cada uno.

Cada payout guarda al beneficiario como contacto automáticamente ("save_contact": false para no guardarlo). Para repetirle un pago sin re-tipear sus datos, envía "beneficiary_contact_id" en vez de beneficiary — se usa su beneficiario guardado más reciente para ese país y método (422 no_saved_destination si no tiene).

Respuesta 202 Accepted:

{
  "payout_id": "0d4f…",
  "account_id": "…",
  "idempotency_key": "factura-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",
  "status": "processing",
  "created_at": "2026-07-06T20:00:00Z"
}

En ese momento tu saldo ya refleja el débito: total_debit pasó de available a held (en el saldo del settlement_asset).

Pagar desde otro saldo (`settlement_asset`)

Por defecto el débito sale de tu asset de settlement predeterminado (USDT salvo que lo cambies con PUT /v1/settlement). Para pagar una operación puntual desde otro saldo, agrega settlement_asset al request. Ejemplo: un payout de 100.000 CLP pagado desde el saldo BTC pasa por cuatro transformaciones, todas registradas en la respuesta:

CLP → USDT a tu tasa: 100000 / 950.25 = 105.235465 USDT.
+ comisión fija: 105.235465 + 0.30 = 105.535465 USDT (total_debit).
USDT → BTC al precio efectivo de settlement (settlement_rate 109029.34070000): 105.535465 / 109029.3407 = 0.00096795 BTC (redondeo hacia arriba al satoshi).
Débito y hold en BTC: settlement_amount 0.00096795 sale de tu saldo BTC; el beneficiario recibe sus 100.000 CLP igual que siempre.

{
  "country": "CL",
  "currency": "CLP",
  "local_amount": "100000",
  "fx_rate": "950.25",
  "usdt_amount": "105.235465",
  "fee": "0.300000",
  "total_debit": "105.535465",
  "settlement_asset": "BTC",
  "settlement_amount": "0.00096795",
  "settlement_rate": "109029.34070000",
  "status": "processing"
}

Si el payout falla, se reembolsa el settlement_amount exacto a tu saldo BTC — nunca se re-cotiza. Si el precio de ejecución de BTC/GOLD no está disponible en ese momento recibirás 503 pricing_unavailable, y los assets volátiles tienen un límite por operación (422 settlement_limit_exceeded; consúltalo en GET /v1/settlement).

3. Recibe el estado final

Suscríbete al evento payout_status_changed (webhooks):

{
  "payout_id": "0d4f…",
  "account_id": "…",
  "country": "MX",
  "currency": "MXN",
  "local_amount": "1500.00",
  "usdt_amount": "85.714286",
  "total_debit": "86.014286",
  "status": "completed",
  "status_code": ""
}

completed: el dinero llegó; el hold se consume.
failed: se reembolsa el débito completo automáticamente (payout_refund en tu ledger).

También puedes consultar en cualquier momento:

curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

Estados del payout

Estado	Significado	¿Tu saldo?
`processing`	Aceptado y en ejecución en el rail local	Débito retenido en `held`
`completed`	El dinero llegó al beneficiario	Hold consumido — final
`failed`	El corredor lo rechazó o falló	Reembolso automático completo (monto + comisión)

Consulta e historial

Cada payout se puede leer individualmente y el listado acepta filtros:

# Un payout
curl https://api.qbank.cl/platform/v1/payouts/0d4f… \
  -H "Authorization: Bearer <token>"

# Historial con filtros: fechas, estado, país y paginación
curl "https://api.qbank.cl/platform/v1/payouts?from=2026-07-01&to=2026-07-08&status=failed&country=MX&page=1&page_size=50" \
  -H "Authorization: Bearer <token>"

{
  "page": 1,
  "page_size": 50,
  "payouts": [
    {
      "payout_id": "0d4f…",
      "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",
      "status": "failed",
      "status_code": "core_rejected",
      "status_message": "beneficiary account does not exist",
      "created_at": "2026-07-06T20:00:00Z"
    }
  ]
}

from/to van en YYYY-MM-DD (UTC, ambos inclusive); una fecha inválida responde 400 invalid_range.

Ejemplos por país

Cada corredor con su beneficiary exacto, el request completo y la respuesta real. Las tasas (fx_rate) son ilustrativas — siempre aplican las de tu cuenta en GET /v1/rates; el débito es usdt_amount + fee (fijo, si está configurado; aquí 0.30).

Campos del beneficiary por corredor

País	Método	Campos del `beneficiary`
CL	`bank_transfer`	`name`, `tax_id` (RUT), `bank_code`, `account_type`, `account_number`
PE	`bank_transfer`	`name`, `account_number` (CCI de 20 dígitos)
PE	`yape`	`name`, `phone` (`51XXXXXXXXX`)
MX	`bank_transfer`	`name`, `account_type` (`clabe`/`debit_card`), `account_number` (+ `bank_code` si es tarjeta)
VE	`pago_movil`	`phone`, `bank_code` (SUDEBAN), `document_value`
VE	`bank_transfer`	`name`, `account_number` (20 dígitos), `document_value`
BO	`bank_transfer`	`name`, `tax_id`, `bank_code`, `account_number`
BR	`pix`	`name`, `tax_id` + (`pix_key` y `pix_key_type`) o (`bank_code` ISPB, `branch_code`, `account_number`)
EC	`bank_transfer`	`name`, `document_value` (cédula), `sender_name`, `account_number` (+ `bank_code` y `account_type` si es a otro banco)
EC	`deuna`	`name`, `document_value`, `sender_name`, `phone` (celular de la billetera)
EC	`cash_pickup` / `cnb`	`name`, `document_value`, `sender_name` — el beneficiario retira con su documento
PY	`bank_transfer`	`name` (≤35), `tax_id`, `bank_code`, `account_number`

Transferencia bancaria en CLP. Requiere RUT, banco y cuenta:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "Pago proveedor",
    "idempotency_key": "cl-prov-0091"
  }'

{
  "payout_id": "b3e1…",
  "country": "CL",
  "currency": "CLP",
  "method": "bank_transfer",
  "local_amount": "100000",
  "fx_rate": "925.69",
  "usdt_amount": "108.027528",
  "fee": "0.300000",
  "total_debit": "108.327528",
  "status": "processing"
}

El catálogo de bancos (GET /v1/payouts/banks?country=CL) da los bank_code vigentes.

Dos métodos: transferencia bancaria (CCI interbancario) y Yape (al número de teléfono).

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PE",
    "currency": "PEN",
    "method": "bank_transfer",
    "amount": "1000.00",
    "beneficiary": {
      "name": "Rosa Álvarez Díaz",
      "account_number": "00219300123456789012"
    },
    "idempotency_key": "pe-cci-3310"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PE",
    "currency": "PEN",
    "method": "yape",
    "amount": "150.00",
    "beneficiary": {
      "name": "Luis Ramos Vega",
      "phone": "51987654321"
    },
    "idempotency_key": "pe-yape-8874"
  }'

{
  "payout_id": "c7a2…",
  "country": "PE",
  "currency": "PEN",
  "method": "yape",
  "local_amount": "150.00",
  "fx_rate": "3.40",
  "usdt_amount": "44.117648",
  "fee": "0.300000",
  "total_debit": "44.417648",
  "status": "completed"
}

En yape el teléfono va en formato 51XXXXXXXXX (11 dígitos con código de país). El resultado suele ser síncrono.

SPEI en MXN, a CLABE (18 dígitos) o a tarjeta de débito:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "MX",
    "currency": "MXN",
    "method": "bank_transfer",
    "amount": "1500.00",
    "beneficiary": {
      "name": "María López",
      "account_type": "clabe",
      "account_number": "012180001234567895"
    },
    "idempotency_key": "mx-clabe-8841"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

{
  "payout_id": "0d4f…",
  "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",
  "status": "processing"
}

Con CLABE el banco destino se deriva de los primeros dígitos; con tarjeta es obligatorio bank_code.

Dos métodos: Pago Móvil (teléfono + banco + cédula) y transferencia bancaria (cuenta de 20 dígitos):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "VE",
    "currency": "VES",
    "method": "pago_movil",
    "amount": "2000.00",
    "beneficiary": {
      "phone": "04141234567",
      "bank_code": "0102",
      "document_value": "V12345678"
    },
    "idempotency_key": "ve-pm-5567"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "VE",
    "currency": "VES",
    "method": "bank_transfer",
    "amount": "5000.00",
    "beneficiary": {
      "name": "Carmen Delgado",
      "account_number": "01020123456789012345",
      "document_value": "V87654321"
    },
    "idempotency_key": "ve-bank-7810"
  }'

{
  "payout_id": "e9b4…",
  "country": "VE",
  "currency": "VES",
  "method": "pago_movil",
  "local_amount": "2000.00",
  "fx_rate": "666.00",
  "usdt_amount": "3.003004",
  "fee": "0.300000",
  "total_debit": "3.303004",
  "status": "completed"
}

bank_code usa códigos SUDEBAN; en bank_transfer puede derivarse de los primeros 4 dígitos de la cuenta.

Transferencia ACH en BOB o USD (además del payout QR):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

{
  "payout_id": "f2c8…",
  "country": "BO",
  "currency": "BOB",
  "method": "bank_transfer",
  "local_amount": "1382.00",
  "fx_rate": "6.91",
  "usdt_amount": "200.000000",
  "fee": "0.300000",
  "total_debit": "200.300000",
  "status": "processing"
}

Para USD envía currency: "USD" con la misma estructura.

PIX por llave (además del QR PIX):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

{
  "payout_id": "a6d1…",
  "country": "BR",
  "currency": "BRL",
  "method": "pix",
  "local_amount": "350.00",
  "fx_rate": "5.13",
  "usdt_amount": "68.226121",
  "fee": "0.300000",
  "total_debit": "68.526121",
  "status": "processing"
}

pix_key_type: cpf, cnpj, phone, email o evp (llave aleatoria).PIX a cuenta (sin llave) — si el beneficiario no tiene o no entrega su llave PIX, envía sus datos bancarios; llega igual de rápido (mismo riel PIX, 24/7):

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "method": "pix",
    "amount": "350.00",
    "beneficiary": {
      "name": "Empresa Exemplo Ltda",
      "tax_id": "19.385.062/0001-20",
      "bank_code": "45678923",
      "branch_code": "1",
      "account_number": "765432",
      "account_type": "CACC"
    },
    "idempotency_key": "br-pix-acct-3322"
  }'

bank_code es el ISPB del banco destino (8 dígitos), branch_code la agencia y account_type el tipo de cuenta (CACC corriente — default —, SVGS ahorro, TRAN cuenta de pago, SLRY salario).
El estado final llega por el webhook payout_status_changed (conciliación continua contra el rail); consulta puntual con GET /v1/payouts/{id}.

Remesas en USD (1 a 10.000 por operación, máx. 2 decimales) con cuatro métodos: transferencia bancaria, billetera DE UNA (por celular), retiro en ventanilla (cash_pickup) y retiro en corresponsal no bancario (cnb). Es un corredor de remesas: además del beneficiario, el rail exige los datos del ordenante (quien envía), que van planos dentro del mismo beneficiary con prefijo sender_*.

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

{
  "payout_id": "9f3a…",
  "country": "EC",
  "currency": "USD",
  "method": "bank_transfer",
  "local_amount": "250.00",
  "fx_rate": "1",
  "usdt_amount": "250.000000",
  "fee": "0.300000",
  "total_debit": "250.300000",
  "status": "processing"
}

Ecuador está dolarizado: la moneda local ES el USD (fx_rate: "1").
document_value es la cédula del beneficiario; document_type acepta IDCD (cédula, default), CCPT (pasaporte) o TXID (RUC).
En bank_transfer, si omites bank_code la cuenta es del banco emisor del corredor; para otro banco envía el bank_code del catálogo (GET /v1/payouts/banks?country=EC) más account_type (checking o savings).
Nombres estructurados opcionales (given_name, middle_name, first_surname, second_surname y sus pares sender_*): si los tienes, envíalos — mandan sobre la separación automática de name.
El estado final llega por webhook payout_status_changed (con conciliación periódica de respaldo).

Transferencia bancaria en PYG:

curl -X POST https://api.qbank.cl/platform/v1/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "PY",
    "currency": "PYG",
    "method": "bank_transfer",
    "amount": "500000",
    "beneficiary": {
      "name": "Sofía Benítez",
      "tax_id": "4123456",
      "bank_code": "0011",
      "account_number": "600123456"
    },
    "idempotency_key": "py-bank-9917"
  }'

{
  "payout_id": "d4e7…",
  "country": "PY",
  "currency": "PYG",
  "method": "bank_transfer",
  "local_amount": "500000",
  "fx_rate": "6055.76",
  "usdt_amount": "82.566020",
  "fee": "0.300000",
  "total_debit": "82.866020",
  "status": "processing"
}

name acepta hasta 35 caracteres en este corredor.

Payout QR

En Bolivia (QR interoperable local) y en Brasil (QR PIX, incluido el código “copia e cola”) también puedes pagar a un QR de cobro en dos pasos: escanear y confirmar. El escaneo es gratis; solo se cobra al confirmar, igual que un payout normal (tu tasa + fijo). Si no envías country/currency, se asume Bolivia (BOB); para Brasil envía country: "BR" y currency: "BRL".

1. Escanea el QR (gratis)

Bolivia
Brasil (QR PIX)

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_payload": "<contenido del QR>",
    "currency": "BOB"
  }'

Devuelve los datos del destinatario para que el usuario confirme a quién le paga:

{
  "scan_id": "…",
  "provider_reference": "…",
  "beneficiary_name": "Juan Quispe",
  "destination_account": "…",
  "amount": "700.00",
  "currency": "BOB",
  "glosa": "",
  "status": "…"
}

qr_payload acepta el contenido crudo del QR PIX (BR Code EMV) o el código “copia e cola” — son el mismo string:

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/scan \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "qr_payload": "00020126360014br.gov.bcb.pix0114+5511998765432520400005303986540575.005802BR5913LOJA DA MARIA6009SAO PAULO62110507PED423163040BF9"
  }'

El escaneo decodifica el BR Code localmente (valida su checksum) y devuelve la llave PIX de destino, el nombre del comercio y el monto si el QR lo trae fijo:

{
  "scan_id": "PIXSCAN-…",
  "provider_reference": "<el mismo payload EMV>",
  "beneficiary_name": "LOJA DA MARIA",
  "destination_account": "+5511998765432",
  "amount": "75.00",
  "currency": "BRL",
  "glosa": "",
  "status": "scanned"
}

amount vacío = QR de monto abierto: tú decides cuánto pagar en el confirm. Con monto fijo, el confirm debe enviar exactamente ese monto.
Se soportan QR PIX estáticos (los impresos/reutilizables, con la llave embebida). Un QR dinámico (payload con URL del PSP en vez de llave) responde 400 con el mensaje dynamic pix qr codes are not supported yet — pídele al beneficiario su llave PIX y usa el método pix.
Un payload alterado o incompleto responde 400 (checksum CRC inválido).

2. Confirma el pago (se cobra aquí)

Bolivia
Brasil (QR PIX)

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_reference": "<del scan>",
    "amount": "700.00",
    "currency": "BOB",
    "description": "Pago QR almuerzo",
    "idempotency_key": "qr-2026-07-07-a"
  }'

curl -X POST https://api.qbank.cl/platform/v1/payouts/qr/confirm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "BR",
    "currency": "BRL",
    "provider_reference": "<del scan>",
    "amount": "75.00",
    "description": "Pedido 4231",
    "idempotency_key": "qr-br-2026-07-16-a"
  }'

amount siempre es obligatorio: si el QR trae monto fijo debe coincidir exacto — si no, recibes 422 con el payout en status: failed (status_message: "amount mismatch: the qr requires exactly 75.00 BRL") y el reembolso ya aplicado; corrige el monto y reintenta con clave nueva. Si es de monto abierto, el que envíes es el que se paga.
Un QR PIX estático es reutilizable por diseño (el QR impreso de un comercio se paga muchas veces): puedes pagarlo de nuevo con una idempotency_key distinta. Un intento fallido no inutiliza el QR.
El pago sale por el mismo riel PIX del método pix (24/7); el txid del QR viaja con el pago para que el comercio concilie automático.

Se debita usdt_amount + fijo a tu tasa, igual que un bank_transfer.
El resultado es síncrono: la respuesta ya trae el estado final (completed o failed con reembolso automático) — sin esperas.
Reintentos con la misma idempotency_key devuelven el payout original. En Bolivia la referencia del scan es de un solo uso (un QR escaneado solo puede pagarse una vez); en Brasil el QR PIX estático es reutilizable y cada pago lleva su propia clave.

Errores frecuentes

HTTP	`error`	Qué hacer
400	`idempotency_key_required`	Envía la clave en body o header
400	`beneficiary_required`	Incluye el objeto `beneficiary`
402	`insufficient_funds`	Fondea la cuenta; el payout no se creó
403	`account_blocked`	La cuenta no está activa; contacta al equipo de CBPay
403	`service_disabled`	Payouts no está habilitado para tu cuenta — ver servicios
422	`currency_not_supported`	No hay tasa FX para esa moneda
422	(payout con `status: failed`)	El corredor rechazó los datos; el débito ya fue reembolsado — corrige `beneficiary` y reintenta con clave nueva
503	`channel_unavailable`	El canal de pago está temporalmente no disponible; reintenta más tarde con la MISMA `idempotency_key`

Rechazo inmediato vs fallo posterior

Si el procesador rechaza el payout al crearlo, recibes 422 con el objeto en status: failed y el reembolso ya aplicado. Si falla después (por ejemplo, cuenta destino inexistente detectada por el banco), te llega el webhook con status: failed y el reembolso automático en ese momento.

Cómo leer `status_code` en un payout fallido

`status_code`	Significado	Acción
`core_rejected`	El procesador rechazó la operación al crearla (datos del beneficiario inválidos, corredor no disponible)	Lee `status_message`, corrige y crea un payout nuevo con clave nueva
`channel_unavailable`	El canal de pago quedó temporalmente no disponible	Reintenta más tarde; el reembolso (si hubo débito) ya está aplicado
otro código	Rechazo posterior del riel bancario (p. ej. cuenta destino cerrada)	Igual: corrige los datos y crea una operación nueva
(vacío)	Fallo genérico del corredor	Revisa `status_message`; si no es claro, contacta soporte con el `payout_id`

En todos los casos el reembolso ya está aplicado — verifícalo con la entrada payout_refund en movimientos.

Un payout en processing no se puede cancelar por API: el rail ya lo tiene. Espera el estado final por webhook o GET — llega siempre, con reembolso automático si falla.

Comenzar

Conceptos

Flujos de integración

Productos

Integración

Recursos

1. Descubre los corredores disponibles

2. Crea el payout

Pagar desde otro saldo (`settlement_asset`)

3. Recibe el estado final

Estados del payout

Consulta e historial

Ejemplos por país

Campos del beneficiary por corredor

Payout QR

1. Escanea el QR (gratis)

2. Confirma el pago (se cobra aquí)

Errores frecuentes

Rechazo inmediato vs fallo posterior

Cómo leer `status_code` en un payout fallido

​1. Descubre los corredores disponibles

​2. Crea el payout

​Pagar desde otro saldo (settlement_asset)

​3. Recibe el estado final

​Estados del payout

​Consulta e historial

​Ejemplos por país

​Campos del beneficiary por corredor

​Payout QR

​1. Escanea el QR (gratis)

​2. Confirma el pago (se cobra aquí)

​Errores frecuentes

​Rechazo inmediato vs fallo posterior

​Cómo leer status_code en un payout fallido

1. Descubre los corredores disponibles

2. Crea el payout

Pagar desde otro saldo (`settlement_asset`)

3. Recibe el estado final

Estados del payout

Consulta e historial

Ejemplos por país

Campos del beneficiary por corredor

Payout QR

1. Escanea el QR (gratis)

2. Confirma el pago (se cobra aquí)

Errores frecuentes

Rechazo inmediato vs fallo posterior

Cómo leer `status_code` en un payout fallido