Conceptos fundamentales

Tokeflow es la infraestructura detrás de tu plataforma. Modelas tu negocio una sola vez — sus cuentas, catálogo, clientes y pagos — y Tokeflow estandariza esos objetos en todos los proveedores de pago conectados. Esta página es el glosario canónico y el modelo de objetos: cada entidad, qué representa, su prefijo de ID y cómo encajan las piezas.

El modelo de objetos de un vistazo

Todo en Tokeflow cuelga de un modelo de tenencia de dos niveles: una Organization (tu plataforma) que contiene uno o más Merchants (las marcas o unidades de negocio que realmente venden). Casi cualquier otro recurso está delimitado a un único merchant.

Tenencia

Organization

Tu plataforma — el tenant de nivel superior y el límite de facturación/gobernanza. Una organization posee uno o más merchants y lleva la identidad de cumplimiento de toda la org (razón social, registro, país). Las claves de API delimitadas a la organization (sk_live_org_… / pk_live_org_…) pueden actuar a través de cada merchant de la org.

Prefijo de ID: org_

Merchant

Una única marca o unidad de negocio que vende bajo tu plataforma. Un merchant es el ámbito para casi todos los recursos operativos — clientes, catálogo, checkout, transacciones, órdenes y suscripciones pertenecen todos a exactamente un merchant. Las claves delimitadas a merchant (sk_live_mer_… / pk_live_mer_…) infieren el merchant automáticamente.

Prefijo de ID: mrc_

Clientes y datos de pago

Customer

Un comprador bajo un merchant específico. Contiene identidad (nombre, correo electrónico, teléfono), un documento fiscal opcional y una dirección de facturación. Los clientes se deduplican por correo electrónico dentro de un merchant, y la misma persona puede existir de forma independiente bajo diferentes merchants.

Prefijo de ID: cust_

Payment Instrument

Un método de pago reutilizable y tokenizado propiedad de un cliente — típicamente una tarjeta almacenada para cobros futuros (checkout recurrente, suscripciones, un clic). Tokeflow almacena únicamente metadatos seguros como la marca, los últimos cuatro dígitos y la caducidad; los datos brutos de la tarjeta nunca se persisten en los sistemas de Tokeflow.

Prefijo de ID: pi_

Card Token

Una referencia efímera y de un solo uso a los datos de la tarjeta recopilados en el navegador por los secure fields de Tokeflow. Los secure fields se ejecutan dentro de iframes aislados y cross-origin; los datos de la tarjeta se cifran en el navegador y nunca tocan tus servidores. Tu cliente recibe un card token y lo entrega a tu backend, que lo intercambia (del lado del servidor, con una clave secreta) por un Payment Instrument duradero.

Prefijo de ID: tok_

Catálogo

Tu catálogo vendible es una jerarquía de cuatro niveles: una Product Family agrupa Products relacionados; cada producto se vende como una o más Offers; cada oferta tiene precio mediante Offer Prices (uno por moneda). Las Offer Transitions definen cómo un suscriptor puede moverse entre ofertas (upgrade/downgrade) dentro de una familia.

Product Family

Una agrupación de productos relacionados entre los que un suscriptor puede moverse (por ejemplo, niveles de un plan). La familia define el comportamiento predeterminado — change_charge_behavior — para las transiciones entre sus ofertas. Un producto pertenece a una familia cuando participa en flujos de upgrade/downgrade.

Prefijo de ID: pfa_

Product

Algo que vendes. Un producto es one_time o recurring (type), y está active o archived (status). Cuando forma parte de una familia, lleva una posición de nivel para que los planes puedan ordenarse en la lógica de upgrade/downgrade.

Prefijo de ID: prd_

Offer

Una configuración comprable de un producto — lo que un cliente realmente compra. Una oferta fija el ciclo de facturación, el comportamiento de prueba y de configuración, y cuántos ciclos cobrar. Un producto puede exponer varias ofertas (por ejemplo, una oferta mensual y una anual).

Prefijo de ID: ofr_

Offer Price

El importe de una oferta en una única moneda. Una oferta tiene un precio por moneda, con uno marcado como predeterminado. Los importes son unidades menores enteras y siempre van emparejados con una moneda ISO 4217.

Prefijo de ID: opr_

Offer Transition

Una regla direccional que conecta dos ofertas de la misma familia — el camino que toma un suscriptor al hacer upgrade o downgrade. Una transición puede anular el change_charge_behavior predeterminado de la familia (next_renew, prorated, o override) para ese par específico, y puede activarse o desactivarse.

Prefijo de ID: oft_

Checkout

Un flujo de compra alojado y con estado. Una Checkout Session rastrea a un comprador desde su llegada hasta la finalización, contiene las ofertas elegidas como Checkout Items, y registra una línea de tiempo de Checkout Events (incluyendo atribución UTM) para el análisis del embudo. Una sesión completada produce una Order.

Checkout Session

El contenedor para un intento de checkout. Rastrea la oferta principal, el cliente (eventualmente identificado), la moneda seleccionada, y un estado del ciclo de vida: initiated, customer_identified, payment_pending, completed, expired, abandoned.

Prefijo de ID: cks_

Checkout Item

Una línea dentro de una sesión: una oferta, su moneda e importe capturado como snapshot, cantidad, y cuotas seleccionadas. Los importes se capturan como snapshot del precio de la oferta en el momento de la sesión para que ediciones posteriores del catálogo no cambien un checkout en curso.

Prefijo de ID: cki_

Checkout Event

Un evento de solo anexado en la línea de tiempo de una sesión. Tipos de evento: initiated, customer_identified, currency_changed, payment_started, payment_failed, payment_succeeded, completed, expired, abandoned. Lleva atribución opcional (utm_source, utm_medium, utm_campaign) y contexto de la solicitud.

Prefijo de ID: cke_

Pagos

Transaction

Un único intento de pago contra un proveedor — el registro normalizado de una autorización/captura, independientemente de qué proveedor conectado la haya gestionado. Lleva el método de pago, los importes (autorizado y capturado, en unidades menores), la moneda, el país y un estado detallado. Las transacciones son idempotentes en la creación y pueden vincularse a una Order.

Prefijo de ID: tx_

status: pending, pre_authorized, authorized, failed, canceled, voided, charged_back, refund_pending, capture_pending, refunded, partially_refunded, expired.

Order

El registro normalizado y orientado al merchant de una única venta. Una orden se vincula a como máximo una Transaction que la liquida, referencia al cliente, y puede estar ligada a una Subscription cuando se trata de una renovación o configuración de prueba. Usa la orden como tu referencia de negocio estable; la transacción es la mecánica de pago detrás de ella.

Prefijo de ID: ord_

status: pending, pre_authorized, authorized, failed, canceled, refunded, partially_refunded, charged_back, refund_pending.

Refund

Una reversión total o parcial de una transacción capturada. Una transacción puede tener múltiples reembolsos (p. ej. reembolsos parciales sucesivos). Cada reembolso registra un importe en unidades menores, una moneda, un estado y un motivo.

Prefijo de ID: ref_

Subscription

Un acuerdo de facturación recurrente: un cliente facturado en una Offer usando un Payment Instrument almacenado. Tokeflow rastrea la oferta y el importe actuales, el período de facturación, las ventanas de prueba, el estado de dunning para renovaciones fallidas, y un estado del ciclo de vida. Cada cobro de renovación produce una Order (y su transacción).

Prefijo de ID: sub_

Convenciones de dinero y formato

La consistencia entre proveedores y monedas se garantiza mediante unas pocas reglas. Aplícalas en todas partes.

Envoltorio de respuesta estándar

Cada respuesta de la API envuelve el recurso en un envoltorio consistente. Un único recurso omite meta; una lista incluye meta.pagination.

{
  "success": true,
  "data": {
    "id": "tx_8f3c2a1b",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount_authorized": 15000,
    "amount_captured": 15000,
    "currency": "BRL",
    "country": "BR"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Una respuesta de lista establece data como un array e incluye paginación:

{
  "success": true,
  "data": [
    { "id": "ord_a1b2c3", "status": "authorized", "total_amount": 9900, "currency": "USD" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Referencia de formato de ID

Cada objeto de Tokeflow lleva un identificador opaco con prefijo. Los prefijos son estables — haz coincidencias con ellos en lugar de analizar el sufijo aleatorio.

Próximos pasos

• Autenticación — tipos de clave, ámbitos y la regla de merchant_id para claves de org.
• Idempotencia — reintentos seguros en llamadas de creación y de cobro.
• SDK — recopila tarjetas con secure fields e intercambia card tokens por instrumentos de pago.
• Webhooks — entrega normalizada de eventos y verificación de firmas.