Agregado
- Controles de cumplimiento en pagos salientes (guía payouts, errores): los payouts, los retiros crypto con nombre de beneficiario y los cobros collect ahora pasan por controles de cumplimiento adicionales antes de mover fondos. Errores documentados:
403 compliance_hold(la operación fue retenida y NO se creó — sin débito; por política no se informa la razón exacta, contacta a soporte con el timestamp) y503 compliance_check_unavailable(la verificación no se pudo evaluar; la operación NO se creó — reintenta con la mismaidempotency_key).
Corregido
- Shapes de persona del screening AML (guía): el motor
de screening exige
date_of_birthcomo objeto{year, month, day}(el string"YYYY-MM-DD"responde422),nationalitycomo array de códigos ISO-3166 ypersonal_identification[]como{ "issuing_country", "number" }sin campotype. Guía y ejemplos del spec actualizados con los shapes verificados en vivo.
Agregado
- QR Crypto POS — cobros QR crypto con monto para procesadores (guía):
las cuentas empresa con POS físicos registran a sus comercios como
merchants verificados (KYB/KYC de terceros aprobado) y generan cobros
crypto (USDT, USDC, BTC) con dirección exclusiva y QR por venta.
Detección temprana del pago para el POS (
confirmingen segundos), crédito con conversión automática al settlement asset, atribución por merchant en cobros/webhooks, resumen de conciliación (GET /v1/pos/summary) con comisión informativa por merchant y neto a repartir, y devoluciones por el riel de retiro crypto con tope duro (jamás más de lo recibido). Rutas nuevas bajo/v1/pos/*(tag QR Crypto POS del API Reference); pagos parciales acumulan y los pagos tardíos a un cobro expirado se acreditan igual.
Corregido
- QR crypto de Bitcoin: el QR del checkout ahora lleva la dirección
bech32 cruda (igual que TRON/ETH). Las apps de exchanges como Binance
rechazaban el URI BIP-21 (
bitcoin:…?amount=…) como “invalid QR”; el monto exacto sigue visible al lado con botón copiar. - Página de cobro: favicon white-label (símbolo de la org) y el texto
del panel ya no parte palabras a mitad (“momento” → “moment”/“o”) —
el
word-breakagresivo quedó solo en las direcciones monospace.
Agregado
- CLABE dedicada por link de cobro (México): materializar
bank_transferMX en un link de cobro universal ahora emite (o toma de un pool reciclable) una CLABE exclusiva de ese link. El pagador transfiere el monto exacto sin poner referencia: el abono se detecta y rutea al link automáticamente por la cuenta de destino. El payload de la materialización llevadestinationcondedicated: true; si la cuenta dedicada no puede emitirse, degrada al camino clásico (cuenta del comercio +referenceobligatoria en la glosa). Las CLABEs se reciclan con período de enfriamiento al resolverse el link (pagado o expirado).
Agregado
- Cobros pull en el link de cobro universal (Venezuela): la página del
checkout ahora ofrece los métodos que cobran directo en la cuenta del
pagador (
c2pydebito_inmediatoen VE). El pagador completa banco, documento, teléfono o cuenta y la clave OTP en la misma página; el monto siempre es el congelado en la cotización. Endpoints públicos nuevos:POST /pay/{token}/collect/otp(solicita la clave cuando el rail la envía a demanda) yPOST /pay/{token}/collect(ejecuta el cobro; si el rail confirma síncrono el link queda pagado en la misma llamada). En el catálogo deGET /pay/{token}/quoteestos métodos llegan concollect: true. - Fiat multi-moneda por país: cada país del quote lista sus corredores
en
options[]— una fila por método+moneda (ej. Bolivia con QR en BOB y en USD) con sulocal_amountencountry_quote. Materializar un método ofrecido en varias monedas exige¤cy=YYY(el error400 currency_requiredahora aplica a cualquier método, no solo tarjetas). - Cuenta de destino en transferencias bancarias: cuando el corredor
usa una cuenta de depósito dedicada (la CLABE en México), la
materialización de
bank_transferincluyedestination(tipo, número de cuenta y beneficiario) además de la referencia — el pagador ya sabe adónde transferir sin salir de la página.
- Banderas SVG en la página de pago: las banderas de países y monedas ahora son imágenes SVG (se ven igual en Windows, macOS y móviles; antes algunos sistemas mostraban el código del país en texto). En la pestaña Tarjeta, la bandera se deriva de la moneda del cargo (USD → bandera de Estados Unidos, aunque el adquirente sea de otro país).
- La página del checkout ya no responde
429 too_many_attemptspor el solo hecho de estar abierta: los límites de tráfico de lectura, materialización, OTP y cobro ahora son independientes entre sí.
Agregado
- Pestaña Tarjeta en el link de cobro universal: el pago con tarjeta
sale de la pestaña Fiat y ahora tiene su propia pestaña, listada por
moneda de cargo (hoy BOB y USD; monedas de adquirentes futuros
aparecen solas).
GET /pay/{token}/quoteresponde el catálogo nuevocards[](país, moneda ylocal_amountpor opción) ycountries[]deja de listarcardentre los métodos. Materializar una tarjeta exige la moneda:POST /pay/{token}/methods/card?country=XX¤cy=YYY— sin ella responde el error nuevo400 currency_required. Cada moneda es una materialización independiente con su propia página de pago hosted.
- Página de pago con identidad visual reforzada: logos de los assets (USDT, USDC, BTC, GOLD) junto al monto y en los grupos crypto, banderas por país en el selector Fiat y en las filas de tarjeta, íconos por método, y un timer de expiración prominente (pill con reloj; bajo 1 hora muestra cuenta regresiva y bajo 10 minutos cambia a rojo).
- La página del checkout ya no se desplaza sola hacia el panel activo cada pocos segundos: el refresco automático re-renderiza solo cuando cambia la data y nunca mueve el scroll (solo la selección manual de un método lleva la vista al detalle).
Cambiado
- Página de pago del checkout universal rediseñada: las opciones ahora
se organizan en tres pestañas — CBPay (QR + alias del comercio, con
botón de copiar), Crypto (monedas agrupadas por red; las redes
nuevas aparecen solas al habilitarse) y Fiat (selector de país +
métodos con el monto local cotizado). Botones de copiar en alias,
direcciones, montos y referencias. Sin cambios de API: la URL, el
contrato de creación y los endpoints públicos (
/state,/quote,/methods/{method}) son los mismos.
Corregido
- Payout QR — validación antes de crear el payout: un
POST /v1/payouts/qr/scancon un QR ilegible o dinámico ahora responde400 invalid_qr_payloadcon el motivo concreto (antes devolvía un502genérico). En el confirm de Brasil, un monto que no coincide con un QR PIX de monto fijo responde422con el payoutfailedy el reembolso ya aplicado — y el QR queda intacto para reintentarlo con el monto correcto y una clave nueva. - QR PIX estático reutilizable: el guard “un QR = un pago” ya no aplica
a los QR PIX estáticos de Brasil (se pagan muchas veces por diseño); la
protección por pago es tu
idempotency_key, que en Brasil es obligatoria en cada confirm.
Agregado
- Payout por QR PIX en Brasil (BR/BRL): el flujo de dos pasos
POST /v1/payouts/qr/scan→POST /v1/payouts/qr/confirmahora acepta QR PIX estáticos de Brasil (incluido el código “copia e cola”) — envíacountry: "BR"ycurrency: "BRL". El scan decodifica el BR Code localmente (sin costo) y devuelve nombre del comercio, llave PIX y monto; el confirm paga por PIX con el mismo pricing de un payout normal.amountes siempre obligatorio: los QR de monto fijo exigen coincidencia exacta (un mismatch responde422con el payoutfailedy reembolso automático — el QR no se inutiliza). Un QR PIX estático es reutilizable: cada pago lleva su propiaidempotency_key. Los QR dinámicos o corruptos responden400 invalid_qr_payload— usa el métodopixcon la llave del beneficiario. Disponible en el ambiente de pruebas con QRs de ejemplo y valores mágicos (montos.99fallan) — ver Entorno y pruebas. Detalle en la guía de payouts.
Cambiado
- Link de cobro universal v2 — multi-país + liquidación en el saldo
elegido (Breaking sobre el shape v1 de ayer): el cobro ahora se
denomina en cualquiera de tus 4 saldos virtuales con
settlement_asset(USDTdefault,USDC,BTC,GOLD) yamountEN ese asset (“50” USDT, “0.001” BTC, “2” g de oro); enviarcurrencyresponde400(los links v1 existentes siguen operando). El pagador ve todos los países con corredor de payin vivo (elige país → métodos con el monto local cotizado y congelado al materializar), las 4 opciones crypto con QR escaneable (qr_payload+qr_png_base64; BIP-21 en BTC, dirección cruda en tokens TRON/ETH — legible por Trust Wallet, MetaMask, Binance y wallets externas), y el QR + alias CBPay del comercio para pagar al instante desde la app (deeplinkcbpay:pay?to=…&checkout=…;POST /v1/transfersaceptacheckout_tokeny valida el due server-side). Todo pago se auto-convierte alsettlement_assetal acreditar (mismo asset no convierte);conversion_statusvisible en/state. Endpoint público nuevoGET {checkout_url}/quotecon el catálogo de países, dues crypto y dues CBPay. Errores nuevoscountry_required,country_unavailable,settlement_asset_disabledycheckout_amount_mismatch. Detalle en la guía de payins.
Agregado
- Detalle del rechazo en cobros activos fallidos: cuando un cobro
activo (
collect, C2P o débito inmediato) quedafailed, el payin ahora incluye un objetofailurecon el origen del rechazo (provider= el banco del pagador,core= la validación previa al cobro), el código y el mensaje concretos — visible en la respuesta síncrona delPOST, enGET /v1/payins/{id}y en el webhook. Antes solo se veía el estadofailedgenérico. Detalle en la guía de payins.
Agregado
- Link de cobro universal (
checkout):POST /v1/payinsaceptamethod: "checkout"y devuelvecheckout_url— una página pública brandeada donde el pagador elige cómo pagar: QR, tarjeta, transferencia bancaria o crypto (USDT en TRON, USDT/USDC en Ethereum y BTC) con una dirección de depósito exclusiva de ese cobro y acumulación de pagos parciales. Un link = un cobro: el primer método que completa el pago gana. Estado consultable sin auth enGET {checkout_url}/state; elpayin_creditedde un pago crypto agregasettled_viaycrypto_amount. Soportasuccess_url,failure_url,expires_in(10 minutos a 7 días) e idempotencia (el retry devuelve el mismo link). Errores nuevosalready_paid,checkout_expiredymethod_unavailable. Detalle en la guía de payins.
Cambiado
- Filtro de autenticación previo a la captura en pagos con tarjeta: los
cargos con tarjeta solo se envían al procesador cuando la verificación
3-D Secure terminó con autenticación exitosa o intentada y con los datos
de autenticación completos; un intento sin autenticación real se rechaza
antes de mover fondos y el pagador puede reintentar. La página de pago
además extendió la recolección de datos del dispositivo (~11 s) para
mejorar la tasa de aprobación de los bancos emisores. En el ambiente de
test, el monto terminado en
.44simula un intento rechazado por este filtro (tabla completa en Ambiente de pruebas).
Agregado
- Pago con tarjeta (
card) en payins:POST /v1/payinsaceptamethod: "card"(Bolivia, BOB o USD) y devuelvepayment_url— una página de pago alojada con el branding de tu organización donde el pagador ingresa su tarjeta en campos seguros y pasa la verificación 3-D Secure de su banco. Campos opcionalescustomer,success_url,failure_urlyexpires_at. El pago confirmado llega por el webhookpayin_receivedy acredita el saldo como cualquier payin; si nadie paga,payin_expiredcierra el cobro. Detalle en la guía de payins.
Agregado
account_iden swaps y address screenings: las respuestas dePOST/GET /v1/swapsyPOST/GET /v1/screenings/addressesahora incluyenaccount_id(la cuenta dueña de la operación). Para integraciones de una sola cuenta es informativo; en vistas administrativas permite atribuir cada registro.
Agregado
- Bitcoin on-chain (
btc/btc): cuarta red soportada del producto crypto. Toda cuenta nace ahora con cuatro wallets de depósito (se suma la de Bitcoin, dirección bech32bc1q…); los depósitos BTC acreditan el saldo BTC (confirmación ~30 min, 3 bloques) y los retiros on-chain aceptanchain: "btc"(destinos bech32, taproot y legacy; el fee de red lo cubre la operación, el destinatario recibe el monto exacto). Las wallets segregadas también soportan el parbtc/btc(sin gas: el fee sale del saldo de la wallet). Travel Rule aplica igual que en las demás redes, valorando el monto a USD. Detalle en la guía crypto.
Cambiado
- El login en dos pasos también respeta el cooldown del teléfono: con
2FA de login por SMS/WhatsApp y un número recién enlazado sin verificar,
el código del login se emite por un factor más fuerte (app autenticadora,
luego email de login) en vez del teléfono — el
channelefectivo llega en la respuesta del login. Sin factor alternativo el login responde403 phone_binding_cooldownhasta que venza el cooldown. El código jamás viaja a un número enlazado desde la propia sesión. Detalle en la guía de seguridad y 2FA.
Cambiado
- Desafíos OTP con teléfono en cooldown caen a un factor más fuerte:
con el número recién enlazado (cooldown de 24 h),
POST /v1/otp/challengesya no bloquea si tienes la app autenticadora enrolada o tu email verificado — el desafío se emite automáticamente por ese canal (jerarquía totp > email) y la respuesta indica el canal efectivo. El403 phone_binding_cooldownqueda solo para cuentas sin factor alternativo. Antes, el cooldown bloqueaba toda relajación del 2FA (incluso desactivar el canal email) aunque tuvieras factores más fuertes disponibles. Detalle en la guía de seguridad y 2FA.
Agregado
- Identidad verificada como fuente de verdad del perfil: al aprobarse
tu onboarding KYC/KYB,
display_name(persona = nombre + apellido; empresa = razón social),tax_idycountryse rellenan automáticamente desde la identidad verificada. Documentado en la guía de KYC y la guía de perfil.
PATCH /v1/mebloquea los campos de identidad tras verificar: conkyc_status: approved, cambiardisplay_name,tax_idocountryresponde409 identity_locked(código nuevo en la página de errores).phonesigue editable con su propio flujo de verificación.
Agregado
- Informe PDF del screening AML:
GET /v1/aml/screenings/{screeningID}/reportdescarga cada screening de tu historial como informe PDF ejecutivo con tu branding — portada con la decisión y su semáforo de riesgo, indicadores (sanciones, watchlists, PEP, prensa adversa…), coincidencias consolidadas, alias, glosario y sección final de respaldo con las fuentes internacionales consultadas. Trilingüe víalang=en|es|zh(default inglés). Lectura pura, sin comisión. Sección nueva en la guía AML. - Nuevo código de error
invalid_language(HTTP 400): ellangdel informe PDF no esen,esnizh. Documentado en la página de errores.
- Campos de empresa en el AML screening: los ejemplos y el spec
documentaban
tax_id/registration_number/country_of_incorporationcomo campos planos decustomer.company, pero el motor de screening los rechaza con422. El identificador va enregistration_authority_identification, el país enplace_of_registrationyincorporation_datees un objeto{year, month, day}. Guía y spec corregidos (verificado en producción).
Agregado
- Nuevo corredor: Ecuador (USD) con cuatro métodos de payout —
bank_transfer(transferencia bancaria),deuna(billetera DeUna),cash_pickup(retiro en ventanilla sin cuenta) ycnb(corresponsal no bancario). El beneficiario acepta nombres estructurados (given_name/first_surname/…) o el split automático desdename, y un bloque opcional de remitente (sender_nameo sus campos estructurados). Ejemplos por método en la guía de payouts y en el spec. - Nuevo código de error
channel_unavailable(HTTP 503): el canal de pago del corredor no está disponible temporalmente. Reintenta más tarde con la mismaidempotency_key. Documentado en la página de errores.
Agregado
- Las cuentas de test nacen pobladas: toda cuenta nueva del ambiente de test nace con ~6 meses de historia demo realista de todos los productos (payouts, payins, transfers, crypto, swaps, tarjetas, banking, contactos…), con saldos de juego, cartola conciliada y analytics listos para explorar. Aplica a todo camino de creación (registro, login social, creación por admin y el switch test/live del dashboard).
- Ambientes 100% independientes: los datos de test ya no se refrescan desde un snapshot de producción — nada se copia entre ambientes. Guía de entornos y pruebas actualizada.
Agregado
- Servidor MCP oficial en
https://mcp.cbpayapp.com: conecta tu editor o asistente de IA (Cursor, VS Code, Claude, ChatGPT y cualquier cliente MCP) a esta documentación — búsqueda, endpoints con ejemplos reales y catálogo de errores, sin salir del editor. Solo lectura, sin autenticación. Página nueva Servidor MCP con instalación de un click e instrucciones por cliente.
Cambiado
- Ambiente de test: las cuentas nuevas ahora nacen con
kyc_status: approved— puedes probar todos los productos de inmediato, sin pasar por el onboarding. Aplica a todo camino de creación (registro, login social, creación por admin y el switch test/live del dashboard); las cuentas de test existentes fueron aprobadas retroactivamente. En live nada cambia: las cuentas nacen sin verificar y el KYC/KYB sigue siendo obligatorio antes de que salga dinero. Para probar el flujo de verificación en test, usa las verificaciones KYC/KYB de terceros.
Cambiado
PUT /v1/otp/preferences: activar el 2FA de la acciónloginpor canal telefónico (sms/whatsapp) ahora exige el teléfono de la cuenta ya verificado (completa cualquier desafío OTP por SMS/WhatsApp antes). Si el número no está verificado, la API responde409 phone_verification_required. Este candado evita que un número mal escrito te deje fuera de tu cuenta al activar el 2FA de login.
Corregido
POST /v1/me/passkeys/register/beginyDELETE /v1/me/passkeys/{passkeyID}ahora aceptan un request sin body, tal como lo documenta el spec (body opcional). Antes respondían400 invalid_json. La contraseña actual sigue siendo obligatoria para las cuentas que tienen contraseña (403 invalid_passwordsi falta o es incorrecta); las cuentas que solo usan login social pasan con su sesión.
Corregido
POST /v1/me/totp/enrollahora acepta un request sin body, tal como lo documenta el spec (body opcional). Antes respondía400 invalid_json. La contraseña actual sigue siendo obligatoria para las cuentas que tienen contraseña (403 invalid_passwordsi falta o es incorrecta); las cuentas que solo usan login social pasan con su sesión.PUT /v1/otp/preferencescon canalemailototprespondía un error 500; corregido — los cuatro canales (sms,whatsapp,email,totp) se guardan correctamente.
- Cartola PDF: los estados de las operaciones ahora aparecen coloreados (verde completado, ámbar pendiente, rojo fallido) para lectura rápida.
Agregado — Exportación CSV / Excel en los listados
- Los listados de
movements,payouts,payinsytransfersaceptan ahora el parámetroformat=csvoformat=xlsxpara descargar las filas como archivo listo para contabilidad (hasta 10.000 filas por descarga; los filtrosfrom/to,statusy demás aplican igual).
- Sin
formatla respuesta sigue siendo el JSON paginado de siempre — no hay cambios de compatibilidad.
Breaking — Las wallets segregadas se mueven a
/v1/segregated-wallets- Todas las rutas de wallets segregadas se renombran de
/v1/wallets*a/v1/segregated-wallets*. Mismos métodos, parámetros, shapes de respuesta, comisiones y webhooks — solo cambia el prefijo del path. No hay alias de compatibilidad: las rutas viejas/v1/wallets*ahora responden404. - Mapeo (las 15 rutas siguen el mismo patrón):
- El
receipt_urlde respuestas, webhooks y emails de comprobantes de envíos/depósitos de wallets ahora apunta al path nuevo. - Por qué: el prefijo genérico
/v1/walletsse confundía constantemente con las wallets de depósito del producto crypto. Esas no cambian y siguen viviendo en/v1/crypto/wallets.
type en toda respuesta de wallet- Las wallets de depósito (
/v1/crypto/wallets) ahora incluyentype: "deposit"yreceive_only: true. - Las wallets segregadas incluyen
type: "segregated". - Úsalo para distinguir los dos productos de forma defensiva — nunca solo por la ruta.
Agregado — Webhook
payin_expired: cierre automático de cobros no pagados- Cuando un cobro activo (QR o checkout hosteado) vence o falla sin recibir
el pago, el payin ahora pasa automáticamente de
pendingaexpired(ofailed) — antes podía quedar pendiente indefinidamente. - Nuevo evento de webhook
payin_expiredcon elpayin_id, el estado final, el corredor y la referencia, para que cierres el cobro en tu sistema sin polling. Suscribible enPOST /v1/webhooks/subscriptions. - No se mueve dinero en ningún caso: para reintentar el cobro se crea un payin nuevo.
Cambiado — Comprobantes, cartola y emails con diseño renovado
- Todos los comprobantes PDF (
GET .../receipt) estrenan un diseño de nivel bancario: encabezado con logo y N° de comprobante, icono del producto, monto destacado, detalle en dos columnas, franja “Documento verificable” con QR y pie institucional. El símbolo de la marca aparece como marca de agua sutil; las operaciones no completadas conservan la marca de agua de estado. - La cartola PDF (
GET /v1/reports/statement?format=pdf) suma tarjetas de resumen con iconos, sello de cuadratura verificada e iconos por sección; el Excel mantiene su estructura. - Los emails (comprobantes, códigos de verificación y avisos de seguridad) comparten ahora una plantilla brandeada con encabezado y pie institucionales de tu organización.
- En los comprobantes de envíos fiat el banco del beneficiario se muestra
SIEMPRE por nombre: si la operación se creó con el
bank_codedel catálogo, se resuelve automáticamente al nombre del banco. - Sin cambios de API: mismas rutas, mismos shapes. Solo cambia el diseño de los documentos y correos.
Agregado — Refresh tokens para sesiones de usuario
- Todo login (contraseña, OTP, social, passkey, handoff y registro) ahora
devuelve, junto al
access_tokende 24 horas, unrefresh_token(rt_…) de un solo uso para renovar la sesión sin re-login:POST /v1/auth/refreshentrega un par nuevo y rota el token (30 días por rotación, tope absoluto de 90 días desde el login original). Detalle y reglas de seguridad en Autenticación → Renovación de sesión. - Rotación estricta y detección de robo: canjear revoca el access token
anterior del dispositivo; presentar un refresh token ya canjeado revoca la
cadena completa y registra el evento
refresh_token_reuseenGET /v1/me/security/events. Cerrar sesión, revocar sesiones o cambiar la contraseña también invalida los refresh tokens. - Código de error nuevo:
401 invalid_refresh_token. Las API keyspk_no cambian: no expiran ni usan refresh.
Agregado — Ambiente de test (sandbox) con dinero simulado
- Nuevo ambiente de test en
https://cryptobank.qbank.cl/platform: la misma API, con todos los corredores atendidos por un simulador propio determinista — siempre disponible, sin depender de terceros. Las operaciones completan solas en segundos y los valores mágicos (montos.99/.77, beneficiarioREJECT, OTP000000, etc.) fuerzan cada resultado alternativo. Guía completa en Ambientes y pruebas. - API keys por ambiente: test emite y acepta solo keys
pk_test_; live solopk_. Una key del otro ambiente devuelve401— imposible cruzar ambientes por error. - Toda respuesta lleva el header
CBPay-Environment(test|live) yGET /healthzexponelivemode. - Switch test/live de un click:
POST /v1/auth/environment-handoff(live) emite un token de un solo uso (60s) que se canjea enPOST /v1/auth/handoff(test) por una sesión del ambiente de test, con auto-provisión de la cuenta espejo si no existe.
Agregado — Historial auditable de screenings AML
GET /v1/aml/screeningsyGET /v1/aml/screenings/{screeningID}listan y consultan cada screening AML (persona, empresa y rescreen) guardado localmente para auditoría — sujeto, riesgo, comisión y resultado completo.POST /v1/aml/screeningsyPOST /v1/aml/rescreenahora exigenidempotency_key(las operaciones cobran comisión). Repetir con la misma clave devuelve el registro original conidempotency_hit: truesin cobrar dos veces.PATCH /v1/aml/monitoringguarda cada activación/desactivación en el mismo historial (kind: monitoring);idempotency_keyes obligatoria cuando el estado cambia (habilitar cobra comisión).
Agregado — Travel Rule en retiros on-chain (FATF R.16)
- Los retiros crypto sobre el umbral configurado (default 1.000 USD)
ahora exigen declarar el beneficiario antes de mover fondos:
wallet_type: "self_hosted"+beneficiary_namepara wallets propias, otravel_address+beneficiary_namepara destinos en otra institución (el intercambio de datos ocurre en línea y la dirección de pago la entrega la institución receptora). Bajo el umbral nada cambia. - La respuesta del retiro incluye
travel_rule_status(not_required/self_hosted_attested/approved). - Códigos de error nuevos:
travel_rule_required,travel_rule_beneficiary_required,travel_rule_address_mismatch,travel_rule_rejected,travel_rule_pending,travel_rule_incomplete_approval,travel_rule_unavailable. Detalle en la guía crypto y la página de errores.
Agregado — Series banking en el historial de saldos
GET /v1/balances/historyahora incluye enassetslas series diarias de las cuentas banking (BANK_USD,BANK_EUR), cada una en su propia moneda (2 decimales), listas para graficarlas como un filtro más junto a USDT/USDC/BTC/GOLD. Siguen fuera del agregadototal_usd, que cubre solo los saldos operativos. Guía de analytics actualizada.
Agregado — Filtro por país en envíos y depósitos
GET /v1/payoutsyGET /v1/payinsaceptan el filtrocountry(ISO 3166-1 alfa-2, ej.?country=MX), combinable constatus,from/toy la paginación. Guías de payouts y payins actualizadas.- El bloque
feesdeGET /v1/ratesahora devuelve la configuración de comisiones efectiva (defaults de la organización resueltos contra los overrides de la cuenta). Antes una cuenta sin overrides veíafees: []aunque sus operaciones tuvieran costo; usa este bloque para cotizar la comisión exacta antes de crear la operación.
Cambiado — Límites de wallets por tipo de cuenta
- Wallets de depósito: toda cuenta — persona y empresa — mantiene
exactamente una wallet de depósito por par soportado (
tron/usdt,eth/usdt,eth/usdc), creadas gratis al registrarse.POST /v1/crypto/walletsqueda solo para restaurar un par faltante; con el par ya creado responde422 wallet_limit_reachedpara cualquier tipo de cuenta (antes las empresas podían crear más). - Wallets segregadas: ahora también disponibles para cuentas persona,
con límite de 1 por par red/activo (la segunda responde
422 wallet_limit_reached). Las empresas siguen sin límite. El error403 company_requiredya no aplica a wallets segregadas. - Guías de crypto y wallets segregadas, página de personas y empresas y errores actualizadas.
Agregado — Monitoreo transaccional continuo (controles de cumplimiento)
- La plataforma ahora monitorea todas las operaciones en tiempo real con controles de cumplimiento de estándar bancario. Para la gran mayoría de los clientes esto es invisible: no cambia ningún flujo ni agrega latencia perceptible.
- Códigos de error nuevos documentados en errores:
403 compliance_hold(operación retenida por cumplimiento),403 geo_restricted(jurisdicción no soportada) y503 compliance_check_unavailable(verificación temporalmente no disponible — la operación no salió; reintenta con la misma clave de idempotencia).
Agregado — Documentación en 3 idiomas (inglés por defecto)
- Esta documentación ahora está disponible completa en inglés (idioma por defecto), español y chino simplificado. Cambia de idioma con el selector en la parte superior del sitio.
- La API Reference también existe en los tres idiomas (mismos endpoints y ejemplos; solo cambian las descripciones).
- La colección Postman y la guía compilada en Markdown se mantienen al día desde cualquier idioma del sitio.
Agregado — Screening de wallets (riesgo AML de direcciones blockchain)
- Producto nuevo:
POST /v1/screenings/addressesevalúa cualquier dirección blockchain contra inteligencia on-chain global — sanciones, exposición a fondos ilícitos — y devuelve un nivel de riesgoLow/Medium/High/Severecon la evidencia completa. Comisión fija por scan (address_screening, con reembolso automático si falla) e idempotencia obligatoria. Historial conGET /v1/screenings/addresses(+/{id}). - Protección automática gratis: los retiros on-chain evalúan el destino antes de firmar (riesgo severo ⇒ rechazo con reembolso completo) y los depósitos entrantes evalúan al remitente antes de acreditar (severo ⇒ retenido en revisión de compliance; alto ⇒ se acredita con alerta).
- Webhooks nuevos:
crypto_deposit_heldycrypto_deposit_alert. - Guía nueva: Screening de wallets.
Agregado — Assets públicos por CDN (avatares, branding, QR de cobro)
- Avatares por CDN:
avatar_url(enPUT /v1/me/avatar,GET /v1/resolvey contactos) ahora es una URL pública absoluta que carga sin autenticación cuando la imagen está publicada en el CDN;GET /v1/avatars/{accountID}responde con un302hacia esa URL (los avatares legados se siguen sirviendo directo). - Branding con URLs:
GET /v1/brandingsumalogo_urlysymbol_url— URLs públicas de CDN de los logos, para tematizar el front sin decodificar base64 (los campos*_png_base64se mantienen). - QR de payins: los cobros QR (
POST /v1/payins, métodoqr) exponenqr_image_url, el PNG del QR publicado en el CDN, además del base64qr_imagede siempre. Ideal para mostrarlo con un<img>directo.
Agregado — Catálogos de compliance
- Nuevo
GET /v1/aml/catalogs: todos los catálogos para construir formularios de compliance y verificación (géneros, formas jurídicas por país, fuentes de ingreso/patrimonio, estándares de industria, países y subdivisiones ISO-3166). Antes esta data no estaba disponible en la API.
- El bloque
asset_pricesdeGET /v1/ratesyGET /v1/rates/historyya no incluye el campo internosource; usasettlement_gradeyupdated_atpara saber si un precio es ejecutable y qué tan fresco está.
Agregado — Toda cuenta nace con sus wallets de depósito
- Al crear una cuenta (persona o empresa) se aprovisionan automáticamente y
sin costo sus tres wallets de depósito crypto:
tron/usdt,eth/usdtyeth/usdc. Apenas registrada,GET /v1/crypto/walletsya devuelve las tres direcciones (la provisión corre en segundo plano; si consultas en el mismo segundo puede tardar unos instantes). POST /v1/crypto/walletsqueda para wallets adicionales (empresas); las personas ya tienen ocupado el cupo de cada combinación desde el registro. Las cuentas creadas antes de este cambio fueron completadas con las wallets que les faltaban.
- El registro público de cuentas ahora tiene límite de velocidad por IP
(
429 too_many_attempts).
Agregado — Trazabilidad total: banking en la cartola, comisiones desglosadas y custodia de wallets
- Cartola más completa: nuevas secciones
card_transactions(compras con tarjeta),swaps(conversiones de saldo) ybanking_operations(operaciones bancarias). Si usas Banking, tus cuentas bancarias cuadran como saldos espejoBANK_USD/BANK_EURen la secciónassets. - Comisiones desglosadas: payouts, payins y retiros crypto ahora
separan la comisión en
fee_percentyfee_fixed(suman exacto elfee); los cargos standalone llevanfee_model: "fixed"y se etiquetan Fixed Com en el PDF/Excel. - Comprobantes nuevos:
GET /v1/banking/operations/{id}/receipt,GET /v1/wallets/{walletID}/sends/{sendID}/receiptyGET /v1/wallets/{walletID}/deposits/{depositID}/receipt. El webhookbanking_operation_status_changedahora incluyereceipt_url. - Custodia de wallets segregadas: campo
custody(cbpay|client) en cada wallet; la plataforma sincroniza la actividad on-chain completa y emite los webhookswallet_external_movement(movimiento firmado por fuera, esperable en custodiaclient) ywallet_key_compromise_suspected(alarma crítica). - Analytics:
sections.banking.volume(dinero movido por tus cuentas bancarias, que también suma algross_volume),sections.verifications.fees_by_kind(gasto KYC vs KYB por separado),sections.adjustmentsydeposits.wallet_fees_usd. - Contabilidad garantizada por wallet (custodia
cbpay): cuadratura de vida completa en la cartola yfunding_sources(atribución FIFO depósito→envío) en el detalle de cada envío. Los saldos espejoBANK_*también aparecen enGET /v1/balancesconcustody: "banking".
Agregado — Series históricas para tu dashboard
GET /v1/rates/history: la evolución de las tasas de cambio de tu cuenta (punta payout y payin por punto), con granularidaddayuhour, ychange_pctcon signo por moneda — listo para el gráfico de tasas con su badge “+3.4% / −3.0%”. Incluye las series de referencia USD de BTC y GOLD.GET /v1/balances/history: la evolución diaria de tus saldos — una serie por asset con el saldo de cierre de cada día (sin huecos), la serie agregada en USD valorizada al precio histórico de cada día, las entradas/salidas del período y el snapshot actual — todo lo necesario para la tarjeta de saldo con gráfico.- El historial de tasas nace con un backfill de ~90 días de tasas diarias y se registra continuamente hacia adelante.
Agregado — Comprobantes PDF con verificación de autenticidad
- Todo producto transaccional tiene su comprobante PDF brandeado:
GET .../receipten payouts, payins, transferencias, retiros y depósitos crypto (deposit_idnuevo enGET /v1/crypto/transactions), swaps y compras con tarjeta. Idiomas?lang=es|en. receipt_urlen toda respuesta de esos productos y en los webhooks de estados finales: el front nunca construye la URL a mano.- Verificación pública de autenticidad: cada PDF lleva un código firmado
con QR que abre
GET /verify/receipts/{code}(sin credenciales) — JSON para APIs y página web brandeada para navegadores, siempre con el estado y monto reales y vigentes, sin datos personales del beneficiario. - Los comprobantes de operaciones no completadas llevan marca de agua diagonal (“EN PROCESO” / “FALLIDA”): un PDF en tránsito jamás pasa por prueba de pago.
- Email automático con el PDF adjunto al llegar la operación a estado
final, con opt-out por cuenta (
PATCH /v1/meconreceipt_emails: false).
GET /v1/branding: el branding efectivo de la plataforma (logo, colores, nombre) para que el front white-label se auto-tematice desde la API.
- La cartola PDF ahora sale con el logo real de la marca y tipografía Inter (antes wordmark tipográfico), y el Excel incluye el logo en la hoja resumen.
Agregado — Wallets segregadas (solo cuentas empresa)
- Wallets on-chain con saldo propio (fuera del ledger): crear
(
POST /v1/wallets), listar y ver detalle, importar una wallet externa con su llave (POST /v1/wallets/import), exportar la llave privada (POST /v1/wallets/{id}/export, custodia compartida) y enviar crypto directo desde la wallet (POST /v1/wallets/{id}/sends). - Consulta on-chain en vivo:
GET .../balance(incluye gas),.../depositsy.../transactions; auto-forward configurable (GET/POST .../auto-forward). - El gas de los envíos corre por el cliente: sin gas el envío responde
422 insufficient_gas. Import y export exigen sesión de usuario con 2FA. - Fees nuevos:
wallet_import,wallet_export,wallet_send. - Webhooks nuevos:
wallet_deposit_received,wallet_send_status_changed,wallet_key_exported. Service flag nuevo:wallets. - La cartola y el dashboard incluyen una sección de wallets segregadas.
Agregado — Perfil, credenciales y seguridad de la cuenta
- Contraseña: cambio self-service (
POST /v1/me/password, revoca las demás sesiones) y recuperación por código (POST /v1/auth/password/forgot→POST /v1/auth/password/reset) al email o al teléfono verificado. Forgot siempre responde 200 (no revela si la cuenta existe). - Email de login: cambio verificado (
POST /v1/me/email/change→confirmcon el código enviado al email nuevo) y verificación del actual (POST /v1/me/email/verify). - Alias permanente (
PUT /v1/me/alias) y QR de perfil (GET /v1/me/qr): identifican tu cuenta para recibir transferencias. Las transferencias aceptanto_aliasyto_qr_token;GET /v1/resolvemuestra una vista previa del destinatario antes de enviar. - Foto de perfil:
PUT/DELETE /v1/me/avataryGET /v1/avatars/{id}. - 2FA self-service (
GET/PUT /v1/otp/preferences): activa y elige el canal por acción — ahora también email y app autenticadora (TOTP) además de SMS/WhatsApp. Puedes endurecer libremente; relajar exige verificación. - App autenticadora (TOTP):
POST /v1/me/totp/enroll(QR) →confirm(entrega 10 códigos de respaldo de un solo uso),DELETE, yPOST /v1/me/totp/recovery-codespara regenerarlos. - Passkeys (WebAuthn): inicio de sesión sin contraseña con la biometría
del dispositivo (Face ID, Touch ID, Windows Hello, llaves). Registro
(
/v1/me/passkeys/register/begin|finish), gestión (GET,DELETE) y login (/v1/auth/passkey/login/begin|finish). - Sesiones y actividad:
GET /v1/me/sessions+ revocar una o todas, yGET /v1/me/security/events(historial de seguridad de la cuenta). - Avisos por email ante eventos sensibles (cambio de contraseña o email, alta/baja de un factor).
Agregado — Identidad verificada reutilizable (KYC/KYB unificado)
- La verificación KYC/KYB aprobada de un cliente pasa a ser su identidad única dentro de CBPay: sus datos y documentos se reutilizan en los demás productos sin volver a tipearlos ni re-subirlos. Guía: identidad reutilizable.
- Tarjetas: la primera emisión de tu cuenta completa la identidad y los
documentos del titular desde tu verificación aprobada — solo envías
occupationysalary_usd. Los campos explícitos siguen ganando. - Informe de compliance (KYB):
GET /v1/kyb/submissions/{id}/reportdescarga el informe de compliance firmado (PDF) de la verificación.
POST /v1/banking/third-partiesahora exigeverification_idde una verificación aprobada del tercero. Eltypesale del kind (KYC ⇒ INDIVIDUAL, KYB ⇒ COMPANY), la identidad se completa sola y los documentos ya validados se re-entregan al proveedor bancario (documents_synced). Los terceros existentes siguen operando.POST /v1/cardspara personas designadas (cuentas empresa) ahora exigecardholder.verification_iddel KYC aprobado de esa persona; su identidad y documentos salen de la verificación.- Errores nuevos:
422 verification_required,422 verification_not_approved,422 verification_kind_mismatch,422 verification_invalid.
Agregado — Resumen de cuenta (analytics) + usuarios banking de terceros
GET /v1/analytics/summary: en una sola llamada, todas las series y estadísticas de tu cuenta para armar tu dashboard — volumen bruto (in/out), transacciones y usuarios nuevos por período (día/semana/mes, con comparativa vs el período anterior), vista global por país, y una sección por CADA servicio (payouts, payins, depósitos, retiros, transferencias, swaps, tarjetas, banking, KYC/KYB, AML, contactos) con sus dimensiones (país, moneda, método, estado, chain, comercio). Ademásspending(lo que consumiste en fees por servicio) ybalancesvalorizados en USD. Guía nueva: Resumen de tu cuenta.- Usuarios banking de terceros (solo empresas):
POST/GET /v1/banking/third-parties(+documentos, submit, cuentas, saldo) para dar de alta a tus clientes finales como usuarios banking separados, con su identidad/KYC y cuentas a su nombre. Aislados por cuenta. - Límite nuevo: las cuentas persona pueden tener máximo 1 cuenta
bancaria (
409 banking_account_limit).
Cambiado — Tasas de Bolivia y Venezuela
- Las tasas USD→BOB y USD→VES de
GET /v1/ratesahora reflejan el mercado con el que realmente operamos tus pagos (antes se publicaba una tasa de referencia que no correspondía al valor aplicado). - Si en algún momento una de esas tasas no está disponible, el país no
aparece en
GET /v1/ratesy las operaciones en esa moneda responden422 currency_not_supportedhasta que vuelva — nunca cotizamos con una tasa incorrecta. Te recomendamos consultarGET /v1/rates(o suscribirte al webhook de tasas) antes de cotizar pagos enBOBoVES.
Agregado — Swaps: conversión entre tus saldos
- Nuevo producto
swaps: convierte entreUSDT,USDC,BTCyGOLDal instante y sin que la plata salga de tu cuenta — cualquier par, incluidoBTC↔GOLDdirecto.POST /v1/swaps(síncrono, conidempotency_key),GET /v1/swaps/quote(cotización indicativa gratis) yGET /v1/swaps(+/{id}) para el historial. - La tasa cotizada es la tasa de ejecución de tu cuenta: cotizado =
recibido, sin comisiones aparte. Precios de BTC/GOLD en vivo (si el
precio no está fresco, el swap se rechaza con
503 pricing_unavailable). - Las conversiones que tocan BTC/GOLD comparten los límites por operación
y de volumen 24 h con payouts y compras con tarjeta
(
GET /v1/settlement). Guía nueva: Swaps.
Agregado — Contactos y envío por teléfono
- Libreta de contactos (
/v1/contacts): CRUD completo con búsqueda y favoritos. Cada envío (transferencia, payout, retiro crypto) guarda su destino como contacto automáticamente — deduplicado; opt-out con"save_contact": false. - Import de la agenda del celular (
POST /v1/contacts/import, hasta 1.000 por request): normaliza los teléfonos a E.164 y te dice qué contactos ya tienen CBPay (has_cbpay, match solo dentro de tu operador). - Transferir por teléfono:
POST /v1/transfersaceptato_phone(solo cuentas con teléfono verificado por OTP; ambigüedad responde422 recipient_ambiguous) yto_contact_id. - Envío rápido a contactos:
beneficiary_contact_iden payouts (usa el beneficiario guardado del contacto) yto_contact_iden retiros crypto (usa su dirección guardada). Guía nueva: Contactos.
Agregado — Verificación de identidad KYC/KYB (wizard hosteado, documentos con OCR y prueba de vida)
- Onboarding obligatorio: toda cuenta nueva debe aprobar su verificación
de identidad (persona ⇒ KYC, empresa ⇒ KYB) antes de operar. Hasta
entonces solo puede fondear (payins, depósitos crypto, transferencias
entrantes) y leer; el resto responde
403 verification_required. Pide tu link conPOST /v1/me/verification/linky consulta tu estado conGET /v1/me/verification— la aprobación actualiza tukyc_statusautomáticamente. Las cuentas existentes quedaron aprobadas. - Verificación de terceros (solo cuentas empresa): genera links
hosteados (
POST /v1/kyc/links,POST /v1/kyb/links) o envía los datos por API (POST /v1/{kyc,kyb}/submissions), sube documentos con presign + OCR y cierra la prueba de vida con liveness links. Comisiones fijas nuevaskyc_verification/kyb_verificationcobradas al crear (conidempotency_keyobligatoria y reembolso automático si falla). - 7 webhooks nuevos:
kyc/kyb_verification_status_changed,kyc/kyb_link_completed,kyc/kyb_document_validated,kyc_liveness_completed. Guía completa en Verificación KYC y KYB.
POST /v1/kyc,POST /v1/kyc/rescreenyPATCH /v1/kyc/monitoringse eliminaron: el screening contra listas ahora vive enPOST /v1/aml/screenings,POST /v1/aml/rescreenyPATCH /v1/aml/monitoring(misma semántica y comisionescompliance_*). El errorno_kycpasa ano_screeningy el screening ya no toca tukyc_status. Nuevo webhookaml_screening_updatedy nuevo service flagaml(el flagkycahora gatea la verificación de identidad). Guía: AML screening.
Corregido — Catálogo de bancos sin
method en países con varios métodosGET /v1/payouts/banks?country=VErespondía400pidiendomethod, y?country=BOrespondía400 payout_corridor_unsupported. Ahora el catálogo sinmethoddevuelve la unión de los bancos de todos los métodos del país (deduplicada por código), como promete esta documentación; conmethodse acota al canal específico (parámetro documentado en la referencia).
Agregado — Compras con tarjeta desde BTC y GOLD (conversión al momento)
spending_assetahora acepta también BTC y GOLD: las compras se convierten con el precio efectivo del momento de cada evento (el mismo del bloquesettlementdeGET /v1/rates).- Autorización: se reserva el equivalente más un pequeño colchón (no es
un cobro; se devuelve al liquidar). Si el precio de ejecución no está
disponible, la compra se declina con
pricing_unavailable— nunca se convierte con un precio no confiable. - Liquidación: el monto final se re-cotiza al precio del momento de la captura y el sobrante del colchón vuelve solo. Anulación de una autorización: devolución del monto exacto, sin conversión. Devoluciones/ajustes posteriores: re-convertidos al precio del momento del evento (tu saldo asume la variación del precio).
- Las compras BTC/GOLD comparten los límites de assets volátiles de la
cuenta con los payouts: por operación (
settlement_limit_exceeded) y volumen 24 h (settlement_daily_limit_exceeded).
Agregado — Elige desde qué saldo gastan tus tarjetas (USDT o USDC)
- Cada tarjeta ahora tiene un asset de gasto (
spending_asset): sus compras se debitan del saldo USDT o USDC de la cuenta, 1:1 con el USD y sin comisión de conversión. USDT por defecto (comportamiento idéntico al histórico). - Defínelo al crear la tarjeta (
spending_assetenPOST /v1/cards) o cámbialo cuando quieras conPATCH /v1/cards/{cardID}. El cambio aplica solo a compras futuras: las autorizaciones en vuelo conservan (y devuelven a) el asset con el que debitaron. - Las transacciones de tarjeta ahora exponen
spend_assetyspend_amount(el saldo y monto realmente debitados);amount_usd/amount_usdtsiguen siendo el valor USD de referencia. Los límites por tarjeta siguen midiéndose en USD. - Errores nuevos:
400 spending_asset_unavailable(BTC/GOLD no están disponibles para compras con tarjeta) y rechazos de autorizaciónspending_asset_disabledsi tu operador deshabilita el asset.
Cambiado — Endurecimiento del settlement multi-asset
- Los pagos desde BTC/GOLD ahora tienen, además del límite por operación,
un tope de volumen en 24 h móviles por cuenta (
422 settlement_daily_limit_exceeded). Lo ves enGET /v1/settlementcomovolatile_daily_limit_usdt. - Las comisiones de tarjetas (emisión, cancelación y mensualidad) ahora también se debitan desde tu saldo de settlement predeterminado, igual que el resto de los servicios. Las compras con tarjeta siguen liquidando en USDT.
Agregado — Paga payouts y servicios desde cualquier saldo (settlement multi-asset)
- Los payouts y las comisiones de servicios (KYC, creación de wallets, banking) ahora pueden debitarse desde cualquiera de tus cuatro saldos (USDT, USDC, BTC, GOLD). El pricing sigue cotizándose en USDT; el total se traduce al asset elegido con el precio efectivo de settlement del momento. Detalle en el modelo de dinero.
- Nuevo
GET/PUT /v1/settlement: define el saldo predeterminado de tu cuenta (default_settlement_asset). Override puntual por operación consettlement_assetenPOST /v1/payoutsy en el confirm de QR. - La respuesta del payout ahora registra
settlement_asset,settlement_amount(el monto exacto debitado, que es también el que se reembolsa si falla — nunca se re-cotiza) ysettlement_rate. GET /v1/ratessuma un bloquesettlementcon el precio efectivo por asset habilitado, yasset_pricesahora traesource,updated_atysettlement_grade(si el precio está apto para ejecutar).- Errores nuevos:
503 pricing_unavailable(precio de ejecución de BTC/GOLD no disponible),400 settlement_asset_disabled,400 invalid_settlement_assety422 settlement_limit_exceeded(límite por operación de los assets volátiles).
Cambiado — Referencia corta en la transferencia anunciada
POST /v1/payinsconmethod: "bank_transfer"ahora devuelve unareferencecorta de 12 caracteres alfanuméricos (ej.CBW4N8R2T6P9) en vez del UUID: los conceptos bancarios tienen límites duros (en Paraguay/SIPAP el máximo es 20 caracteres sin caracteres especiales) y el UUID no cabía.- El match automático acepta la referencia nueva y sigue aceptando el
UUID de los anuncios antiguos — los payins
pendingexistentes no se ven afectados. El respaldo por monto+moneda no cambia. GET /v1/payinsy el detalle muestran la referencia de anuncio enreferencemientras el payin estápending.
Agregado — Payins en Paraguay (transferencia anunciada)
- Nuevo corredor de cobro
PY/PYG/bank_transfer: anuncia el depósito conPOST /v1/payins, tu pagador transfiere (SIPAP o transferencia interna del banco receptor) con lareferenceen el concepto, y el abono llega automático en USDT a tupayin_rate, como en todos los países. Guía en payins. - Los guaraníes no usan decimales: anuncia el monto entero exacto
(ej.
"596000"). El match de respaldo por monto+moneda aplica igual. - El corredor aparece en
GET /v1/payins/methodscondelivery: polling.
Agregado — Saldos virtuales multi-moneda (USDT, USDC, BTC, GOLD)
- Cada cuenta ahora mantiene cuatro saldos virtuales independientes:
USDT(la moneda operativa),USDC,BTC(8 decimales, satoshis) yGOLD(gramos de oro fino, 6 decimales, con respaldo en custodio). Nunca se mezclan ni se convierten automáticamente. Detalle en modelo de dinero. GET /v1/balancesdevuelve siempre los cuatro saldos (con ceros si no has operado esa moneda) yGET /v1/movementsfiltra por moneda con?asset=.- Transferencias internas multi-moneda:
POST /v1/transfersaceptaasset(USDTdefault,USDC,BTC,GOLD) — siempre entre saldos de la misma moneda, sin conversión y sin comisión. - USDC on-chain: crea wallets
eth/usdc, deposita y retira USDC por Ethereum. Cada depósito acredita el saldo de su propio activo. Guía en crypto. - Precios de referencia:
GET /v1/ratesincluyeasset_pricescon el precio USD referencial de cada moneda (BTC por unidad, GOLD por gramo) — solo para valorizar, sin conversión ni spread. - Cartola multi-moneda: nueva sección
assetscon la conciliación independiente de cada saldo no-USDT (inicial/entradas/salidas/final y su flagbalanced), también en el PDF y el Excel. - Los payouts, payins, tarjetas y comisiones de servicios siguen operando exclusivamente contra el saldo USDT.
Agregado — Login social (Google, Apple, Microsoft, Meta)
- Registro e inicio de sesión sin contraseña con Google, Apple,
Microsoft y Facebook por token exchange: tu front obtiene la credencial
con el SDK del proveedor y la intercambias en
POST /v1/auth/oauthpor la sesión CBPay. Guía completa en login social. - Endpoints nuevos:
POST /v1/auth/oauth(login + registro unificado),GET /v1/auth/oauth/providers(proveedores habilitados, público),GET/POST /v1/me/identitiesyDELETE /v1/me/identities/{provider}(vincular/desvincular proveedores desde la sesión). - Integra el 2FA: si la cuenta exige OTP en login, el login social
también devuelve
otp_required+pending_token. - Multi-método: una misma cuenta puede tener contraseña y varios proveedores; el auto-vínculo por email solo ocurre si el proveedor lo entrega verificado.
- Códigos de error nuevos en el catálogo:
invalid_provider,provider_not_configured,invalid_credential,email_conflict,identity_taken,last_login_method.
- El sello de “Colección actualizada” en la página de Postman ahora muestra correctamente hace cuánto se actualizó (antes quedaba un indicador vacío).
Agregado — OTP/2FA por SMS y WhatsApp
- Verificación en dos pasos para acciones sensibles: tu operador puede exigir un código de un solo uso (por SMS o WhatsApp) antes de login, payouts, retiros crypto, transferencias, pagos bancarios, revelar una tarjeta, emitir API keys, agregar miembros o cambiar el teléfono. Guía completa en seguridad y 2FA.
- Endpoints nuevos:
POST /v1/otp/challenges(envía el código),POST /v1/otp/challenges/{id}/verify(devuelve elotp_tokende un solo uso para el headerX-OTP-Token),GET /v1/otp/challenges(+ detalle) yGET /v1/otp/settings(tu política efectiva). - Login en dos pasos: con OTP activo en
login,POST /v1/auth/logindevuelveotp_required: true+pending_token, y la sesión se emite enPOST /v1/auth/login/otp. - Solo sesiones de usuario: las API keys
pk_quedan exentas — tus integraciones server-to-server no cambian. - Códigos de error nuevos en el catálogo:
otp_required,otp_invalid,phone_required,phone_binding_cooldown,too_many_attemptsy más.
Documentación — persona vs empresa y guías unificadas
- Nueva página personas y empresas: TODAS las diferencias entre los dos tipos de cuenta (wallets, tarjetas, miembros, KYC/KYB) en una sola tabla, con los errores que delata cada límite.
- Guía de tarjetas reorganizada por tipo de cuenta: pestañas “Cuenta persona” y “Cuenta empresa”, cada una con su flujo completo (primera tarjeta, siguientes, y para empresas la emisión corporativa y para empleados) — ya no hay que armar el flujo leyendo notas sueltas.
- Ejemplos por país de vuelta en sus guías: los requests/responses por corredor de payouts y payins viven otra vez DENTRO de la guía de cada producto (una sola página por producto, sin saltar a una referencia aparte). Las URLs antiguas redirigen.
- Postman con frescura en vivo: la página Postman ahora muestra hace cuánto se actualizó la colección (segundos/minutos/días), además de la fecha y la versión.
- El MD compilado incluye ahora la referencia completa de endpoints y la versión de la documentación.
Documentación — rediseño completo del sitio
- Navegación nueva: Comenzar → Conceptos → Flujos de integración → Productos → Integración → Recursos, con icono por página y breadcrumbs.
- Páginas nuevas: ambiente y pruebas (túnel
para webhooks en local + checklist de go-live),
servicios habilitados,
estados y ciclo de vida (incluye el catálogo de
status_codede payouts fallidos), movimientos y conciliación y flujos de integración con diagramas end-to-end. - Payouts y payins divididos: guía general + referencia por país con el request y response real de cada corredor.
- Guías ampliadas: quickstart cierra el ciclo con webhooks; perfil
(
PATCH /v1/me) y miembros con roles; tabla completa de endpoints con idempotencia; schedule de reintentos de webhooks; tiempos de confirmación on-chain; cuentas banking en EUR; errores de banking en el catálogo; FAQ con límites, cancelaciones y conciliación. - Tarjetas: cuándo se envía el
cardholder, aclarado. La guía y el spec ahora explican que la primera emisión de una cuenta crea y verifica al titular (datos completos + documentos obligatorios) y que las tarjetas siguientes lo reutilizan sin pedir datos — antes el ejemplo mínimo daba a entender que nunca se pedían.
Agregado
payin_rateenGET /v1/rates: cada país ahora entrega tus dos tasas —ratepara payouts (dispersiones) ypayin_ratepara payins (cobros/depósitos fiat). Cotizado = acreditado, siempre.
- Pricing de payins igual que payouts: el pricing FX de un payin vive
en tu
payin_rate(la conversión del abono se hace exactamente a esa tasa) y la comisión de payin pasa a ser un fijo por operación — sin porcentajes aparte. El campofx_ratede cada payin registra la tasa aplicada. Ver comisiones y la guía de payins. - La conversión de abonos redondea hacia abajo al micro-USDT (los débitos siguen redondeando hacia arriba), con diferencia máxima de 1 micro-USDT.
- KYC/KYB: referencia completa de campos de identidad. El objeto
customersiempre aceptó muchos más campos opcionales de los que mostraban los ejemplos (fecha de nacimiento, nacionalidades, documentos con país emisor, alias, domicilios, datos registrales de empresa…) y enviarlos hace el screening más preciso. La guía de KYC ahora documenta todos los campos, con ejemplos de identidad completa y la regla de deduplicación.
Agregado
- Catálogo de tarjetas:
GET /v1/cards/catalog/occupationsyGET /v1/cards/catalog/business-activities(buscables con?q=) para poblar selectores. Al designar una persona,occupationdebe ser un código del catálogo; para empresa,kind_of_businesstambién. Un valor fuera de catálogo se rechaza con400 invalid_occupation/400 invalid_kind_of_businessantes de tocar el emisor. Ver la guía de tarjetas.
Agregado
GET /v1/services: mapa efectivo de los servicios habilitados para tu cuenta (payouts,payins,transfers,crypto,banking,kyc,cards) — úsalo para decidir qué mostrar en tu UI. Los servicios se habilitan por cuenta según tu acuerdo comercial; si uno está apagado, sus acciones responden el nuevo error403 service_disabled(las lecturas y el dinero en tránsito nunca se bloquean).
Agregado
- Tarjetas virtuales y físicas que gastan directo del saldo USDT de la
cuenta, sin prefondeo: cada compra se autoriza en tiempo real contra el
saldo disponible y los límites de la tarjeta. Personas: 1 virtual + 1
física; empresas: ilimitadas, propias o para personas designadas (ej.
empleados). Nuevos endpoints
POST/GET /v1/cards,GET/PATCH /v1/cards/{id}(límites y congelar/descongelar),POST /v1/cards/{id}/activate|cancel|revealyGET /v1/cards/{id}/transactions. Ver la guía de tarjetas. - Nuevos servicios facturables (fijos, configurables, pueden ser 0):
card_creation_virtual,card_creation_physical,card_monthly(si no hay saldo, la tarjeta se congela — sin deuda) ycard_cancellation. - Nuevos webhooks
card_transaction(autorizada/anulada/ajustada) ycard_status_changed(cambios de estado, incluido el congelamiento automático). - Nuevos tipos de movimiento en el ledger:
card_debit,card_refund,card_fee,card_fee_refund.
Agregado
- Chile: página de pago hosted (
method: "fintoc") enPOST /v1/payins. La respuesta trae unapayment_urlque el pagador abre para transferir desde cualquier banco o billetera chilena (Banco Estado, Santander, Mach, Tenpo, Mercado Pago, entre otros); el depósito se detecta, valida y acredita automáticamente en USDT con el webhookpayin_creditedde siempre. Soportaidempotency_keyopcional: un reintento devuelve el mismo payin y la misma URL sin abrir otra sesión de pago. Ver la guía de payins.
Agregado
-
Filtros de fecha
from/toen todos los listados:/v1/movements,/v1/payouts,/v1/payinsy/v1/crypto/transactionsahora aceptanfrom/to(YYYY-MM-DD, UTC, inclusive), además de la paginación de siempre (page,page_sizehasta 200). Fechas inválidas devuelven400 invalid_range. -
Consulta de transferencias:
GET /v1/transfers(lista con paginación y fechas) yGET /v1/transfers/{id}— antes solo se podían crear. -
Listar suscripciones de webhook:
GET /v1/webhooks/subscriptions. -
Idempotencia en cobros activos:
POST /v1/payins/collectahora exigeidempotency_key(ejecuta un cargo real; un reintento nunca vuelve a cobrar al pagador). Igual refuerzo en creación de wallet (no dobla el fee en reintentos) y en ajustes de administración. -
Paginación uniforme agregada a
members,crypto/wallets,deposit-accountsy (admin)orgs. -
Cartola / estado de cuenta (
GET /v1/reports/statement): consolida todos los movimientos del período — payouts, payins, crypto, transferencias y comisiones — en un solo documento auditable con cuadratura contable exacta (saldo inicial + entradas − salidas = saldo final, verificada contra el ledger). Tres formatos con el mismo endpoint: JSON para tu web, PDF con branding CBPay y Excel multi-hoja con celdas numéricas, filtros y hoja de movimientos para auditores (format=json|pdf|xlsx,lang=es|en). El org admin puede generar la cartola de cualquiera de sus cuentas. Ver la guía.
Mejorado
- Diagramas de flujo visuales en toda la documentación: mapa del dinero en la introducción (todo lo que entra y sale del saldo USDT), ciclo de vida del payout con débito/hold/reembolso, flujo QR en dos pasos, las 4 modalidades de payin convergiendo al abono, depósito y retiro crypto, ciclo completo de banking, estados del KYC, entrega y reintentos de webhooks, y la regla de decisión de idempotencia (“¿con qué clave reintento?”).
Cambiado
- Nueva URL base:
https://api.qbank.cl/platform(antesexchange.qbank.cl/platform). El dominio anterior sigue funcionando como alias, así que ninguna integración existente se rompe — pero usaapi.qbank.clpara todo lo nuevo. Toda la documentación, el spec y el Postman ya apuntan a la URL nueva.
Agregado
- Banking: cuentas bancarias reales para tu cuenta — recibe, mantén y
envía dinero por rieles bancarios internacionales (SEPA, SWIFT, ACH
según la moneda). 14 endpoints nuevos bajo
/v1/banking/*:- Perfil bancario: crear, consultar, subir documentos y enviar a verificación.
- Cuentas: abrir por moneda, listar y consultar saldo en vivo.
- Beneficiarios: registrar, listar y agregar cuentas destino.
- Pagos: cotizar (
prepare, gratis) y ejecutarTRANSFER/WITHDRAWcon idempotencia.
- Webhooks nuevos:
banking_customer_status_changedybanking_operation_status_changed. - Comisiones nuevas (fijas, configurables, reembolsables si la operación
falla):
banking_customer,banking_account,banking_operation— el campobanking_feede cada respuesta muestra lo cobrado. - Guía completa de Banking con el flujo end-to-end y ejemplos de cada operación.
Mejorado
- API Reference completamente en español: títulos, descripciones, campos y grupos del sidebar ahora están traducidos cuando navegas la documentación en español (antes solo la interfaz cambiaba de idioma).
- Guía de payouts reordenada: PIX de Brasil vive ahora solo en “Ejemplos por país” (se eliminó la sección duplicada); el QR quedó como única sección de flujo aparte por ser un flujo distinto (scan + confirm).
- Webhooks: payload de ejemplo de cada uno de los 5 eventos.
- Quickstart: registro con ejemplos de persona y empresa.
- Colección Postman ampliada a 53 requests: los endpoints con varios casos de uso ahora traen un request por caso (un payout por país y método, payins por modalidad, KYC persona/empresa, etc.), cada uno con su body listo para enviar.
- Guía de payins reestructurada por país, igual que payouts: matriz de corredores con la modalidad de cada país y pestañas Chile / Perú / México / Venezuela / Bolivia / Brasil con sus ejemplos completos.
- Nueva página de preguntas frecuentes: sandbox, fondeo inicial, costos previos al payout, garantía de tasa, tiempos de llegada, reintentos seguros, depósitos sin referencia y más — las dudas del primer día respondidas en la misma docu.
- Quickstart abre con la tabla de datos clave (URL base, header de
auth, slug, formato de montos, ambiente) y el ejemplo de respuesta de
GET /v1/ratescon la fórmula para estimar costos. - Payouts: respuesta de ejemplo de los catálogos de métodos y bancos, y
tabla de estados con el efecto en tu saldo. Payins: respuesta de ejemplo
del catálogo con el significado de
delivery.
Mejorado
- Ejemplos completos por caso de uso en toda la documentación:
- Payouts: ejemplo de cada país y método con su
beneficiaryreal y la respuesta (Chile, Perú CCI + Yape, México CLABE + tarjeta, Venezuela Pago Móvil + transferencia, Bolivia ACH, Brasil PIX, Paraguay). - Payins: QR de Bolivia y Brasil lado a lado, cobro activo
c2pydebito_inmediatocon la respuesta del OTP, cuenta de depósito dedicada. - KYC/KYB: requests de persona, empresa y mínimo autocompletado, con las respuestas de screening, rescreening y monitoreo (activar/desactivar).
- Transferencias: por email, por
account_id, empresa→persona (nómina) y replay idempotente. - Crypto: creación de wallet persona vs empresa, y el error
wallet_limit_reached. - API Reference: ejemplos nombrados seleccionables en cada endpoint (10 corredores en payouts, 3 modos en payins, persona/empresa en KYC…).
- Payouts: ejemplo de cada país y método con su
Agregado
- Brasil (BRL) con PIX documentado en payouts y payins:
- Payout
pixpor llave (CPF/CNPJ, teléfono, email o llave aleatoriaevp) víaPOST /v1/payouts. - Payout a QR PIX (estático o “copia e cola”) vía el flujo
qr/scan+qr/confirmconcountry: "BR". - Payin con QR PIX dinámico vía
POST /v1/payins(method: "qr",country: "BR"), con imagen del QR y código “copia e cola”. - Payin por transferencia anunciada (
method: "bank_transfer").
- Payout
GET /v1/payouts/methods, GET /v1/payins/methods) refleja la
disponibilidad en cada momento.Agregado
- Todos los métodos de cobro (payins) disponibles por API:
POST /v1/payinsahora aceptamethod:qr(cargo QR, como antes) obank_transfer(anuncias un depósito entrante y recibes la referencia que debe incluir la transferencia para acreditarse sola).POST /v1/payins/collect— cobro activo (pull) al pagador en los corredores que lo soportan (ej. Venezuelac2p/debito_inmediato), con acreditación síncrona;POST /v1/payins/collect/otppara el OTP previo cuando el método lo requiere.POST /v1/payins/deposit-accounts— cuenta de depósito dedicada fija (ej. CLABE en México) vinculada a tu cuenta: todo lo que llega se acredita automáticamente.GET /v1/payins/deposit-accountspara listarlas.
- Matriz completa de corredores y métodos de payout en la guía (Chile,
Perú con
yape, México SPEI, Venezuela conpago_movil, Bolivia conqr, Paraguay). - Venezuela (VES) se sumó a las tasas de
GET /v1/rates.
Agregado
- Payout QR Bolivia: paga a cualquier QR de cobro boliviano en dos
pasos —
POST /v1/payouts/qr/scan(gratis, devuelve los datos del destinatario) yPOST /v1/payouts/qr/confirm(se cobra igual que un payout: tu tasa + fijo, con resultado final síncrono y reembolso automático si falla). - Bolivia (BOB) se sumó a las tasas de
GET /v1/rates.
Agregado
- Nueva página Postman: colección oficial descargable con los 25 endpoints, cuerpos de ejemplo y autenticación preconfigurada. Se regenera con cada versión de la API.
- La página de Comisiones y los ejemplos de payout reflejan el modelo de pricing vigente: los payouts se cobran a tu tasa + fijo por operación (sin porcentaje aparte). Si dispersas el equivalente a 100 USDT, se debitan 100 USDT más el fijo configurado.
Mejorado
GET /v1/ratesahora entrega el tipo de cambio propio de tu cuenta por país: la misma tasa con la que se ejecutan tus operaciones (monto_local / rate = USDT), sin diferencias entre lo cotizado y lo cobrado.
Eliminado (Breaking)
- Se eliminó definitivamente
GET /v1/crypto/deposit-address(el alias que quedó deprecado en v1.4). UsaPOST /v1/crypto/walletspara crear wallets yGET /v1/crypto/walletspara consultarlas.
Agregado
- Wallets múltiples para empresas: las cuentas empresa ahora pueden crear wallets ilimitadas por red (las personas mantienen 1 por red).
- Nuevos endpoints:
POST /v1/crypto/wallets(crear wallet, conlabelopcional para distinguirlas) yGET /v1/crypto/wallets(listar mis wallets). Cada creación cobra la comisión fijawallet_creationsi está configurada. - Nuevo error
422 wallet_limit_reachedcuando una persona intenta crear una segunda wallet en la misma red. - Las respuestas de wallet ahora incluyen
wallet_idylabel.
- La guía de Crypto se reorganizó en: crear wallet, ver mis wallets, depositar, transferir y movimientos.
GET /v1/crypto/deposit-addressqueda como alias legacy (deprecado): usa los endpoints de wallets.
- Pulido de redacción y traducciones en ambos idiomas; la tabla de
movimientos ahora incluye los tipos
wallet_creation_feeywallet_creation_refund.
Mejorado
- API Reference de nivel profesional: los 25 endpoints ahora incluyen ejemplos de request y de respuesta para todos los casos (éxito, replay de idempotencia, y cada error posible con su cuerpo real), listos para probar desde el playground de la documentación.
- Los 5 webhooks ahora están documentados dentro de la propia API Reference (sección Webhooks del estándar OpenAPI), con esquema y payload de ejemplo de cada evento.
- Catálogos de métodos y bancos documentados con las formas de respuesta reales del sistema.
- Endpoint
GET /healthzdocumentado (estado del servicio). - La guía de Crypto agrega “Saldo y actividad de tu wallet”: cómo ver el
saldo, la actividad on-chain con
tx_idy el historial contable. - Redacción en voz de marca: toda la documentación habla como CBPay (antes usaba términos genéricos como “tu operador” o “la organización”).
- La verificación de identidad ahora se nombra KYC/KYB en toda la documentación (KYC para personas, KYB para empresas).
- Transferencias internas: documentado explícitamente que funcionan entre cualquier combinación de cuentas (persona↔persona, persona↔empresa, empresa↔empresa) y son siempre sin comisión.
Agregado
- Nuevo servicio de comisión
wallet_creation: la primera creación de una dirección de depósito en cada red puede tener un cargo fijo configurado por CBPay (0 = gratis, valor por defecto). La respuesta deGET /v1/crypto/deposit-addressahora incluyecreation_fee, y el historial de movimientos incorpora los tiposwallet_creation_feeywallet_creation_refund. Consultar una dirección existente sigue siendo siempre gratis; si la creación falla, el cargo se reembolsa automáticamente. - Nueva página Novedades (esta página) con el historial de versiones de la API y la documentación.
- La guía de Crypto ahora tiene una sección explícita “Crear tu wallet”
que explica la creación por red (201 primera vez con
creation_fee, 200 gratis después), y la API Reference renombra el endpoint a “Create or get my wallet (deposit address)”.
Agregado
- Comisiones de compliance por operación:
compliance_person,compliance_company,compliance_rescreenycompliance_monitoring(cargo fijo por llamada; 0 = gratis). Las respuestas de KYC ahora incluyencompliance_serviceycompliance_fee. - Endpoints
POST /v1/kyc/rescreenyPATCH /v1/kyc/monitoring(desactivar monitoreo es gratis). Requieren un KYC previo (409 no_kyc).
- Identidad visual oficial de CBPay aplicada a toda la documentación.
- La documentación de administración se movió a un portal interno de CBPay; este sitio contiene solo la API de cuentas.
Lanzamiento inicial
- Documentación pública de la API de CBPay, bilingüe (español e inglés):
autenticación (sesiones JWT y API keys
pk_), modelo de dinero USDT, comisiones, idempotencia, payouts fiat multi-país, payins, transferencias internas, crypto (fondeo y retiros on-chain), KYC, webhooks firmados y catálogo completo de errores. - API Reference interactiva generada desde OpenAPI 3.1.