Cómo funciona Tokeflow

Comprende los componentes básicos de Tokeflow y el flujo de extremo a extremo de un pago, desde la recolección de la tarjeta en el cliente hasta el enrutamiento, el respaldo en cascada y los webhooks.

Tokeflow es la infraestructura detrás de tu plataforma. Conectas múltiples proveedores de pago una sola vez, aplicas reglas de enrutamiento inteligente y ejecutas cada pago a través de una única API normalizada, bajo tu propia marca.

Tokeflow orquesta pagos. No procesa ni liquida fondos: la autorización, la captura y la liquidación las realizan los proveedores de pago que conectas. Tokeflow se sitúa frente a esos proveedores y te ofrece un contrato consistente, enrutamiento inteligente, resiliencia y un registro de auditoría unificado a través de todos ellos.

Esta página explica las piezas que intervienen y recorre, paso a paso, lo que sucede cuando se realiza un pago.

Los componentes básicos

Cuatro primitivas conforman casi todo lo que construyes sobre Tokeflow.

API

La API REST en https://api.tokeflow.com es el núcleo del lado del servidor. Cada endpoint vive bajo /api/v1 (versionado por URI; la versión actual es v1). Tu backend se autentica con una clave secreta (Authorization: Bearer sk_live_…) y usa la API para crear transacciones, capturar o anular autorizaciones, emitir reembolsos, administrar el catálogo de productos y leer resultados normalizados. Las claves están limitadas a una Organization o a un solo Merchant, y cada respuesta se envuelve en un sobre consistente de éxito o error. Consulta Autenticación.

Bridge SDK

El Bridge SDK es el compañero del lado del navegador de la API. Renderiza campos seguros y recolecta datos sensibles de la tarjeta sin que esos datos toquen nunca tus servidores. Los campos seguros de Tokeflow se ejecutan dentro de iframes aislados de origen cruzado; los datos de la tarjeta se cifran en el navegador y nunca llegan a tu infraestructura. El SDK se autentica con una clave pública (pk_live_…), que es seguro exponer en el código del cliente, y devuelve una referencia de corta duración que tu backend usa para cobrar la tarjeta. Consulta el Bridge SDK.

Checkout Sessions

Una Checkout Session modela un flujo de compra alojado o incrustado. Rastrea al cliente, los artículos, la moneda seleccionada y el ciclo de vida de la experiencia de compra, desde initiated pasando por customer_identified y payment_pending hasta completed. Las sesiones emiten eventos granulares a los que puedes reaccionar y, cuando se cobra una sesión, Tokeflow ejecuta la misma orquestación que una transacción directa de la API. Usa sesiones cuando quieras que Tokeflow coordine la experiencia al inicio del embudo; usa la API de transacciones directamente cuando tu plataforma ya sea dueña de la interfaz de checkout. Consulta Checkout Sessions.

Webhooks

Los webhooks son la forma en que Tokeflow le dice a tus sistemas lo que sucedió. Cada cambio de estado significativo —una transacción que se autoriza, un reembolso que tiene éxito, un contracargo que se abre, una suscripción que entra en gestión de cobros— se entrega como un evento firmado y normalizado al endpoint que registras durante el onboarding. Debido a que Tokeflow normaliza las notificaciones específicas de cada proveedor en un solo esquema, tu manejador de webhooks no cambia cuando agregas o intercambias proveedores. Cada payload se firma con X-Tokeflow-Signature para que puedas verificar su autenticidad. Consulta Webhooks.

Las tareas de onboarding —crear merchants, emitir claves de API y registrar URLs de webhook— se realizan en el Tokeflow Dashboard, no a través de la API pública.

Anatomía de un pago

Aquí está el recorrido de extremo a extremo de un pago con tarjeta, desde el navegador del cliente hasta un resultado normalizado y un webhook.

Recolecta la tarjeta en el cliente. Tu frontend monta los campos seguros del Bridge SDK. El cliente escribe los datos de su tarjeta en iframes aislados de origen cruzado. Los datos se cifran en el navegador y nunca tocan tus servidores. El SDK devuelve una referencia de corta duración a la tarjeta cifrada.
Envía la referencia a tu backend. Tu frontend publica la referencia (y el contexto del pedido) a tu propio backend por tu canal habitual. No interviene ningún dato de tarjeta sin procesar.
Crea la transacción. Tu backend llama a POST /api/v1/transactions con una clave secreta, el monto en unidades menores, la moneda y la referencia de la tarjeta. Alternativamente, se cobra una Checkout Session, lo que dispara el mismo flujo. Envía una Idempotency-Key para que los reintentos nunca cobren dos veces.
Tokeflow selecciona un proveedor. Las reglas de enrutamiento inteligente eligen el mejor proveedor para esta transacción en función de atributos como país, moneda, método de pago y monto.
Cascada ante rechazos suaves. Si el proveedor elegido devuelve un rechazo suave (una falla reintentable como un tiempo de espera agotado del emisor o un "do not honor" temporal), Tokeflow pasa automáticamente en cascada al siguiente proveedor elegible en la ruta. Los rechazos duros (como tarjeta robada o tarjeta inválida) no se reintentan.
Devuelve un resultado normalizado. Tokeflow devuelve un único objeto de transacción independiente del proveedor. El campo status te indica el resultado, y el arreglo timeline registra cada intento, incluyendo qué proveedores se probaron y por qué cada uno tuvo éxito o falló.
Emite webhooks. Tokeflow emite eventos de webhook firmados y normalizados para los cambios de estado resultantes, de modo que tus sistemas posteriores permanezcan sincronizados sin necesidad de sondeo.

Todas las fallas de proveedor aún devuelven HTTP 201 con status: "failed": una tarjeta rechazada es una llamada exitosa a la API con un resultado de pago fallido. Inspecciona el campo status, no el estado HTTP, para decidir qué sucedió con el dinero.

Autorización vs. captura

Los pagos con tarjeta separan dos pasos: la autorización reserva los fondos en la tarjeta del cliente, y la captura los cobra efectivamente. Tokeflow te permite hacer ambos a la vez o dividirlos.

Autorizar y capturar juntos. Establece capture: true en POST /api/v1/transactions. Si tiene éxito, la transacción queda en authorized y los fondos se cobran en un solo paso. Este es el comportamiento predeterminado para la mayoría de las compras de un solo cobro.
Autorizar ahora, capturar después (preautorización). Establece capture: false. Si tiene éxito, la transacción queda en pre_authorized: los fondos se reservan pero no se cobran. Más tarde, los cobras con una llamada de captura, o liberas la retención con una anulación.

Este modelo de dos pasos es útil cuando el monto final o el cumplimiento no se conoce en el momento de la compra; por ejemplo, reservar un monto en el momento del pedido y capturarlo una vez que el pedido se envía.

Acción	Solicitud	Estado resultante
Autorizar + capturar	`capture: true`	`authorized`
Solo autorizar (retención)	`capture: false`	`pre_authorized`
Capturar una autorización retenida	Endpoint de captura	`authorized`
Liberar una autorización retenida	Endpoint de anulación	`voided`

Usa una preautorización cuando necesites verificar una tarjeta o reservar fondos antes de estar listo para cobrar. Un tipo de cobro setup_verification valida una tarjeta sin cobrar un pago, útil al guardar una tarjeta para más adelante.

Las autorizaciones expiran. Si no capturas una transacción pre_authorized dentro de la ventana de retención del proveedor, puede pasar a expired y los fondos reservados se liberan. Captura sin demora.

El ciclo de vida de la transacción

Cada transacción lleva un status normalizado que es idéntico en todos los proveedores. El diagrama a continuación muestra cómo una transacción se mueve entre los estados canónicos.

Estado	Significado
`pending`	Creada; esperando un resultado del proveedor.
`pre_authorized`	Fondos reservados pero aún no capturados.
`authorized`	Fondos autorizados y capturados.
`capture_pending`	Captura solicitada; liquidación en curso.
`failed`	El pago fue rechazado o tuvo un error.
`canceled`	La transacción fue cancelada.
`voided`	Una autorización retenida fue liberada.
`refund_pending`	Se ha solicitado un reembolso y se está liquidando.
`refunded`	Reembolsada completamente.
`partially_refunded`	Parte del monto fue reembolsada.
`charged_back`	El cliente disputó el cargo.
`expired`	Una autorización retenida caducó antes de la captura.

El arreglo timeline en una transacción registra cada intento que Tokeflow realizó en tu nombre: el número de intento, si fue un respaldo, el resultado y los tiempos. Es tu registro de auditoría de las decisiones de enrutamiento y cascada, y nunca expone datos de tarjeta sin procesar.

Enrutamiento y resiliencia

Dos funciones convierten una lista de proveedores conectados en una capa de pago resiliente: el enrutamiento inteligente y el respaldo en cascada.

Enrutamiento inteligente

El enrutamiento inteligente elige qué proveedor maneja una transacción dada. Defines reglas en el Dashboard, y Tokeflow las evalúa por transacción usando atributos como país, moneda, método de pago, marca de la tarjeta y monto. El enrutamiento te permite dirigir el tráfico al proveedor con la mejor economía o las mejores tasas de aprobación para cada segmento de tu volumen, sin cambiar una sola línea de código de integración. Cuando una regla coincide, su identificador se registra en la transacción para que cada decisión sea auditable.

Respaldo en cascada

El respaldo en cascada decide qué sucede a continuación cuando un proveedor no puede completar el pago. Si el proveedor seleccionado devuelve un rechazo suave —una falla reintentable como un tiempo de espera agotado del emisor, un error de red temporal o un "do not honor" transitorio— Tokeflow reintenta automáticamente la misma autorización contra el siguiente proveedor elegible en la ruta. Esto recupera ingresos que de otro modo se perderían por fallas transitorias. Los rechazos duros (como una tarjeta inválida o robada) son terminales y nunca se reintentan, de modo que a los clientes no se les cobra en una tarjeta que el emisor ha rechazado.

El resultado es el mismo objeto de transacción normalizado sin importar cuántos proveedores se probaron. Tu integración ve un solo contrato; Tokeflow maneja la orquestación detrás de él.

Debido a que el enrutamiento y el respaldo se configuran en el Dashboard, puedes agregar un nuevo proveedor o cambiar tu estrategia de enrutamiento sin volver a desplegar tu aplicación.

Próximos pasos

Autenticación — claves, alcances y el sobre de solicitud.
Bridge SDK — recolecta tarjetas de forma segura en el navegador.
Transacciones — crear, capturar, anular y reembolsar.
Webhooks — verifica firmas y reacciona a eventos.

Cómo funciona Tokeflow

En esta página