Registro de cambios

Este es el registro continuo de cambios en la plataforma Tokeflow — la API REST y el Bridge SDK. Las entradas se listan de la más nueva a la más antigua, cada una fechada y agrupada por Añadido, Cambiado y Corregido.

Tokeflow es la capa de orquestación detrás de tu plataforma: las estructuras de la API y del SDK documentadas en esta referencia son estables, y las evolucionamos con cuidado. La mayoría de las versiones son aditivas — nuevos campos, nuevos valores de enumeración, nuevos endpoints — y estas pueden aparecer dentro de la versión mayor actual (v1) en cualquier momento. Construye clientes que ignoren campos desconocidos para que los cambios aditivos nunca te rompan nada.

Cómo leer este registro de cambios

Cada entrada indica si afecta a la API, al SDK o a ambos.

---

2026-10-26 — Boleto, tokens de pagador de PIX y boleto, límites de tasa por clase de ruta

Los pagadores de PIX y boleto ahora pueden recogerse en el navegador y cobrarse por referencia, el boleto se incorpora al Bridge SDK y los límites de tasa se definen según el tipo de ruta. Todos los cambios de la API son retrocompatibles.

Añadido

REST API v1 (API)

• Tokens de pagador — POST /payer-tokens registra al pagador de un cargo PIX o boleto (nombre, correo electrónico, CPF/CNPJ y, para un boleto, la dirección de facturación) y devuelve un ptk_… de un solo uso que caduca a los 30 minutos. Cóbralo con el nuevo payer_token_id en POST /transactions, de modo que tu servidor nunca maneja el documento ni la dirección del pagador. Un token inutilizable se rechaza con 400 INVALID_PAYER_TOKEN. Consulta Pagadores de PIX y boleto.
• Opciones de boleto — boleto.expires_in_days (1–30, predeterminado 3) en POST /transactions; una fecha de vencimiento que cae en fin de semana pasa al siguiente día hábil.
• Instrucciones de pago del boleto — digitable_line junto a barcode, boleto_url y due_date (hora de Brasilia, tras el traslado por fin de semana). Consulta Métodos asíncronos.
• Capacidad boleto en la sesión del SDK y en los paymentMethods del contexto de checkout — true solo cuando un conector al que el merchant enruta el boleto puede cobrarlo.

Bridge SDK 2.8.0 y 2.8.1 (SDK)

• Boleto — tokeflow.boleto.tokenize(), 'boleto' en getAvailablePaymentMethods() / useAvailablePaymentMethods(), y el componente de React <BoletoInstructions>. Consulta Boleto.
• Nuevos tipos BoletoToken, PixTokenizeParams, BoletoTokenizeParams, PaymentInstructions, PixInstructions, BoletoInstructions, y el código de error INVALID_DOCUMENT. AvailablePaymentMethod incorpora 'boleto' — un switch exhaustivo sobre él necesita un caso nuevo.

Cambiado

• Límites de tasa por clase de ruta (API): los límites ahora se cuentan por clave y por ruta en ventanas de 60 segundos, con un tope que depende del tipo de ruta — 600 solicitudes por minuto para las rutas de pago y de lectura, 1200 para los eventos de checkout (más un límite por sesión), 600 para las rutas del Bridge SDK (más un límite por IP) y 60 para la verificación de tarjeta del SDK; las demás rutas mantienen 100. Un 429 ahora incluye Retry-After y encabezados X-RateLimit-* que describen el presupuesto que lo bloqueó. Se pueden conceder límites más altos por clave — contacta al equipo de Tokeflow. Consulta Límites de tasa.
• pix.tokenize() (SDK 2.8.0): devuelve un token de pagador (ptk_…) que la API puede cobrar con payer_token_id; email ahora es obligatorio, document acepta un CPF o un CNPJ, y el token incorpora documentType, documentLastDigits y expiresAt (cpfLastDigits queda obsoleto). Actualiza a 2.8.0 para PIX: las versiones anteriores devolvían un token que no podía cobrarse. Consulta PIX.
• Asociación de clientes (API): el correo electrónico de un token de pagador por sí solo nunca vincula un cargo a un cliente existente; envía customer_id, o el mismo correo desde tu servidor.

Corregido

• Carreras entre captura y anulación (API): una captura y una anulación sobre la misma autorización ya no pueden surtir efecto ambas. La llamada que pierde responde 409 (conflict_error); vuelve a leer la transacción en lugar de reintentar. Consulta Captura.
• Bridge SDK 2.7.1: el paquete 2.7.0 publicado contenía el build de 2.6.0, sin savedCardCheckoutEnabled ni SavedInstrument.reusable. Usa 2.7.1 o posterior.
• Bridge SDK 2.8.1: la entrada de React importa el core en lugar de empaquetar una copia, así que instanceof TokeflowError funciona en ambas entradas y el bundle de React es aproximadamente un 80 % más pequeño.

---

2026-10-09 — Motivos de rechazo, checkout con tarjeta guardada, modo live/test

Cada intento fallido ahora indica por qué falló con una sola palabra neutral respecto al proveedor, las tarjetas guardadas pueden pagar una sesión de checkout y cada transacción indica si se ejecutó con credenciales en vivo o de prueba. Todos los cambios son retrocompatibles.

Añadido

REST API v1 (API)

• Motivos de rechazo — decline_reason en cada entrada de la cronología y en GET /transactions/:id/attempts, y en el envoltorio de error de los errores de pago que tienen uno. Los códigos de rechazo de cada proveedor se asignan a un único vocabulario (insufficient_funds, card_expired, do_not_honor, other, …), así que la misma palabra significa lo mismo sea cual sea el conector que respondió. La lista solo crece; consulta Motivos de rechazo.
• Checkout con tarjeta guardada — credential_on_file: true con payment_instrument_id ahora puede pagar un checkout_session_id: la sesión aporta el importe, la moneda y el cliente, y una oferta recurrente inicia su suscripción en el conector que conserva la credencial de la tarjeta. Controlado por el nuevo opt-in del merchant saved_card_checkout_enabled (desactivado por defecto) en el objeto de merchant y en PATCH /merchants/:id.
• mode en el objeto de transacción — live o test, según el conector del intento final; null cuando el cargo se rechazó antes del enrutamiento.
• payment_provider_id en el objeto conector, para que puedas leer el proveedor de una conexión incluso después de que deje de figurar como activo.

Bridge SDK (SDK)

• El checkout con tarjeta guardada ya está disponible. savedCardCheckoutEnabled y SavedInstrument.reusable (SDK 2.7.1+) ahora informan valores reales una vez que el merchant opta por la función; ya no están reservados. Usa el SDK 2.7.1 o posterior — el paquete 2.7.0 publicado contenía un build anterior.

Dashboard

• Los pedidos muestran una insignia live/test, pueden filtrarse por mode, y los intentos fallidos muestran su motivo de rechazo junto al código propio del proveedor. Consulta Pedidos del merchant.

Cambiado

• Una única política de enrutamiento para los rechazos (API): el motivo de rechazo ahora decide cómo se trata un rechazo, de forma idéntica para todos los proveedores — qué rechazos iniciados por el cliente se reintentan y hacen cascada, y cuáles se detienen. En las renovaciones de suscripciones, una renovación nunca se reintenta dentro de la solicitud; solo un motivo que indica que la tarjeta no podrá volver a cobrarse nunca cancela la suscripción, y cualquier otro rechazo pasa a dunning.
• Cargos sin respuesta del proveedor (API): cuando un proveedor no da un veredicto sobre un cargo con tarjeta, la transacción permanece en pending sin hacer cascada mientras Tokeflow establece el resultado, y su sesión de checkout se liquida cuando llega el estado final. Ahora se reconocen más fallos del proveedor como "sin respuesta" en lugar de rechazos.
• Credenciales de conector rechazadas (API): una renovación enrutada a un conector cuyas credenciales el proveedor confirma que rechaza queda en una retención de facturación en lugar de pasar a dunning, y guardar credenciales nuevas la libera. Consulta Credenciales rechazadas.
• Proveedores inactivos (API): un conector cuyo proveedor de pago está inactivo puede desactivarse, renombrarse o rotar sus credenciales, pero no volver a activarse.
• gateway_fee (API): ahora es la comisión tal como la informa el proveedor, y se completa más tarde cuando el proveedor la informa después del cargo.
• Configuraciones del merchant que pueden anularse (API): network_tokens_enabled y saved_card_checkout_enabled son elección propia del merchant; Tokeflow puede definir cualquiera de las dos para una organization o un merchant, y esa configuración prevalece. Consulta Configuraciones que Tokeflow puede anular.

Corregido

• Fechas de facturación de suscripciones (API): los ciclos mensuales y más largos ya no se saltan un mes cuando el día de anclaje es del 29 al 31; la renovación cae en el último día del mes. current_period_end ahora siempre es igual a la fecha de renovación anclada, y un cambio de plan conserva el anclaje existente. Consulta Fechas de facturación.

---

2026-09-24 — Cargos en un clic, dos nuevos proveedores, cuotas por conector

Las tarjetas guardadas ahora pueden volver a cobrarse con un solo clic, las tarjetas pueden guardarse durante una compra puntual y dos proveedores de pago se suman al catálogo. Todos los cambios son retrocompatibles.

Añadido

REST API v1 (API)

• Cargos en un clic con credencial almacenada — credential_on_file: true en POST /transactions cobra un payment_instrument_id guardado con la credencial del proveedor conservada en el registro: sin datos de tarjeta, sin CVV, sin sesión de checkout. El cargo se fija al conector que conserva la credencial, siempre se captura y se registra como un pedido unscheduled iniciado por el cliente. Lee la guía: Upsells y downsells en un clic.
• Guardar una tarjeta al cobrar — save_payment_instrument: true en POST /transactions registra la tarjeta detrás de card_ciphertext_id como un instrumento de pago antes del cargo y conserva la credencial reutilizable del proveedor para cargos en un clic posteriores. Requiere un ciphertext emitido con purpose=instrument_enrollment.
• payer_ip en POST /transactions — la dirección IP del pagador, exigida por algunos proveedores en cargos con tarjeta. Recurre a la IP de la sesión del Bridge SDK del pagador cuando el cargo pertenece a una sesión de checkout.
• Dos nuevos proveedores de pago en el catálogo, ambos con soporte para cargos con credencial almacenada (un clic). La disponibilidad se habilita por organización — contacta con el equipo de Tokeflow para la lista actual; los patrones de credenciales y las reglas de webhook están en Proveedores de pago y Conectores.
• Cuotas por conector — el catálogo de proveedores ahora expone installment_config (el rango que admite cada proveedor por método de pago), y el config.installments_enabled de un conector elige dentro de él: sin definir acepta cuotas pedidas por API sin ofrecerlas en el checkout, true también las ofrece en el checkout, false las rechaza. Consulta Configuración del conector.
• Campos del catálogo de proveedores — default_supported_card_brands y supported_currencies en el objeto de proveedor de pago.
• Opt-in de network tokens — network_tokens_enabled en el objeto de merchant y en PATCH /merchants/:id. El aprovisionamiento ahora es una elección explícita por merchant, desactivada por defecto; los merchants que ya usaban network tokens se incluyeron automáticamente.

Bridge SDK 2.6.0 y 2.7.0 (SDK)

• saveCard y purpose en TokenizeOptions — una integración en el navegador ahora puede emitir un ciphertext registrable: saveCard: true dentro de una sesión de checkout de oferta puntual, o purpose: 'instrument_enrollment' en la tokenización independiente. El CardToken devuelto refleja el purpose que el servidor realmente emitió, y TokenPurpose se exporta. Consulta Tokenización → Opciones.
• savedCardCheckoutEnabled y SavedInstrument.reusable en el contexto de checkout — reservados para el checkout con tarjeta guardada, que se está desplegando; ambos devuelven false hasta que se habilite para tu merchant.

Cambiado

• Cobrar una tarjeta guardada (API): payment_instrument_id por sí solo ahora se rechaza con 400. Envíalo con credential_on_file: true (un clic) o con un card_ciphertext_id nuevo (CVV reescrito). Consulta Orígenes de tarjeta.
• POST /tokens (API): se documentó cómo se decide el purpose del token — dentro de una sesión de checkout el servidor lo deriva de la oferta y de save_card e ignora un purpose enviado por el cliente; la tokenización independiente lo conserva.
• Conectores (API): has_webhook_secret es true para proveedores que firman webhooks con una clave ya presente en credentials; las claves desconocidas en credentials se rechazan; una clave cuyo entorno no coincide con is_test_mode se rechaza.

Corregido

• El ejemplo de POST /merchants/:merchant_id/payment-instruments enviaba una dirección IP como card_ciphertext_id; ahora muestra una referencia tok_….
• Los valores de ejemplo de tarjeta cifrada en POST /tokens ya no muestran un formato bruto de ciphertext.

---

2026-09-04 — Reactivación de suscripción y claridad de facturación

Nuevos controles de suscripción y un comportamiento de facturación más claro en la API REST y el Dashboard. Todos los cambios son retrocompatibles.

Añadido

REST API v1 (API) y Dashboard

• Reactivar una suscripción — un nuevo endpoint que cancela una cancelación programada y mantiene una suscripción viva en su plan, tanto en la API pública como en el Dashboard del merchant. Es también el remedio cuando un cliente intenta iniciar un plan que ya posee.
• Atribución de actor en las transiciones de suscripción: los cambios activados por admin ahora llevan una instantánea actor del usuario del Dashboard que los realizó.
• Documentadas las retenciones de facturación (billing holds) y la regla de una suscripción viva por plan en el ciclo de vida de Suscripciones.

Cambiado

• Cambiar de oferta (API): tras un cambio de plan, el billing_cycle ahora se re-sincroniza con el ciclo de la nueva oferta, en lugar de mantener el valor anterior.
• Reembolsos (API): se aclaró que los reembolsos pending cuentan para el saldo reembolsable y que un reembolso sin resultado definitivo del proveedor permanece en duda — la transacción sigue en refund_pending — en lugar de liberarse.
• Webhooks (API): se documentó la ventana completa de reintentos — un endpoint que falla en todos los intentos se reintenta a lo largo de aproximadamente 26 horas antes de que la entrega se abandone — y que cada entrega se marca en el momento en que se resuelve.

---

2026-08-13 — Referencia de API ampliada

Una amplia actualización de la documentación que cubre más de la superficie /api/v1, además de una nueva sección Dashboards para los endpoints autenticados por sesión del Dashboard y del Portal del Cliente. No cambió ningún comportamiento: esta versión documenta endpoints que ya estaban activos.

Añadido

REST API v1 (API)

• Merchants (mrc_) — gestiona merchants y los miembros de su equipo dentro de una organization.
• API Keys (ak_) — crea, lista, consulta scopes y revoca claves de API de forma programática.
• Webhook Endpoints — registra endpoints, inspecciona entregas y rota secretos de firma por la API.
• Sessions & Tokens (tok_) — los endpoints de sesión y tokenización del lado del servidor detrás del Bridge SDK.
• Connectors (conn_) y Routing Profiles — conecta proveedores de pago y define reglas de enrutamiento inteligente y orden de fallback.
• Payment Providers, Audit Logs y Health.
• Nuevos endpoints en recursos existentes: eliminar un customer, crear un payment instrument y cancelar administrativamente una subscription.

Dashboards (API)

• Documentamos los endpoints autenticados por sesión del Merchant Dashboard, el Organization Dashboard y el Customer Portal — las superficies detrás del Tokeflow Dashboard y del portal self-service del cliente. Se autentican con una sesión del Dashboard (JWT bearer) o una sesión de magic-link del portal, y no con claves de API sk_/pk_.

Cambiado

• La lista de grupos de recursos en la visión general de la referencia de API ahora incluye los recursos recién documentados.

2026-06-23 — API pública v1 y Bridge SDK

La primera versión pública de la plataforma Tokeflow: una API REST estable y versionada, y un SDK del lado del cliente para recopilar datos de pago en el navegador. Todo lo que hay en esta referencia está disponible de forma general a partir de esta versión.

Añadido

API REST v1 (API)

Toda la superficie de /api/v1 está activa en https://api.tokeflow.com. Un sobre consistente, un conjunto de convenciones, en cada proveedor de pagos que conectes.

• Customers (cust_) — crea y gestiona pagadores, incluyendo documentos (cpf, cnpj, passport, tax_id) y datos de contacto.
• Checkout Sessions (cks_) — flujos de checkout alojados e integrados con líneas de artículos, identificación del cliente y una línea de tiempo de eventos transmitida en streaming.
• Transactions (tx_) — crea, recupera, captura y anula pagos con los métodos credit_card, debit_card, pix, boleto y wallet.
• Refunds (ref_) — reembolsos totales o parciales sobre transacciones capturadas.
• Orders (ord_) — registros de pedidos que agrupan transacciones a través de los flujos de API, checkout y renovación.
• Subscriptions (sub_) — facturación recurrente con ciclo de vida, gestión de cobros fallidos (dunning), pausa/reanudación y cambios de oferta.
• Payment Instruments (pi_) — métodos de pago guardados en archivo para cobros iniciados por el comercio y cobros repetidos.
• Catalog — familias de productos (pfa_), productos (prd_), ofertas (ofr_), precios de oferta (opr_) y transiciones de oferta (oft_).

Autenticación y alcance de claves (API)

• Claves de API de Organization y Merchant. Cada clave está limitada a exactamente una entidad. Una clave de Merchant infiere su merchant automáticamente; una clave de Organization abarca todos los merchants de la org y apunta a uno con el parámetro merchant_id. Consulta Autenticación.
• Claves secretas y públicas. Las claves secretas (sk_…) autorizan llamadas de servidor a servidor; las claves públicas (pk_…) están restringidas a alcances seguros para el cliente y son seguras para incluir en código del navegador. Los permisos siguen un modelo resource:action. Consulta Entornos y claves.

Convenciones de la plataforma (API)

• Idempotencia. Envía un encabezado Idempotency-Key (o el campo de cuerpo idempotency_key) en las mutaciones de creación y cobro — en particular POST /transactions — y las repeticiones devuelven el resultado original en lugar de duplicarse. Consulta Idempotencia y límites de tasa.
• Webhooks con entrega firmada. Notificaciones de eventos normalizadas e independientes del proveedor, cada una firmada con un encabezado X-Tokeflow-Signature (HMAC-SHA256) para que puedas verificar la autenticidad antes de actuar. Consulta Webhooks.
• Sobres, errores y paginación estándar. Un sobre consistente success/data/meta, un catálogo de errores estable y legible por máquina, y paginación basada en páginas en todos los endpoints de lista. Consulta la Descripción general de la referencia de la API.

Bridge SDK (SDK)

El Bridge SDK @tokeflow_com/bridge-js recopila datos de pago sensibles en el navegador y los intercambia por una referencia de token de corta duración (tok_…) — los datos de tarjeta se cifran en el navegador y nunca tocan tus servidores. Consulta la Descripción general del Bridge SDK.

• Recopilación de tarjetas con elementos seguros prediseñados y personalizables con temas. Consulta Elements y Tokenización.
• PIX, Apple Pay y Google Pay — cada método habilitado produce el mismo tipo de referencia de token. Consulta Métodos de pago.
• Contexto de checkout — lee los artículos con precio, la moneda seleccionada, los métodos habilitados y los instrumentos guardados de una sesión de checkout abierta. Consulta Checkout.
• Localización — paquetes integrados en y pt-BR con anulaciones de cadenas por elemento. Consulta Localización.
• Enlaces de React — proveedor, hooks y componentes de elementos de primera clase. Consulta React.
• Autenticación con clave pública — el SDK se autentica únicamente con una clave publicable; las claves secretas permanecen en tu servidor.

La versión de un vistazo

Próximos pasos

• Guía rápida — un pago de extremo a extremo.
• Descripción general de la referencia de la API — URL base, autenticación, sobres y convenciones.
• Descripción general del Bridge SDK — recopila y tokeniza datos de pago en el navegador.
• Webhooks — recibe y verifica eventos firmados.