Inicio rápido

Esta guía te lleva de cero a un primer pago con Tokeflow — la capa de orquestación detrás de tu plataforma. Obtendrás tus claves de API, crearás un cliente, abrirás una sesión de checkout, recolectarás los datos de la tarjeta en el navegador, la cobrarás del lado del servidor y confirmarás el resultado con un webhook.

Tokeflow estandariza las operaciones de pago a través de múltiples proveedores bajo tu propia marca. Tus proveedores de pago conectados realizan el procesamiento y la liquidación; Tokeflow orquesta el enrutamiento, la resiliencia y una única API normalizada.

El flujo de un vistazo

Paso 1 — Obtén tus claves de API

Las claves de API se emiten en el Panel de Tokeflow durante el onboarding. Allí aprovisionas merchants, registras URLs de webhook y generas claves — no existe una API pública para el aprovisionamiento.

Trabajarás con dos tipos de claves:

Cada clave está limitada a exactamente una entidad. Una clave de Merchant (sk_live_mer_…) infiere su merchant automáticamente. Una clave de Organization (sk_live_org_…) abarca todos los merchants de la organización, por lo que las llamadas con alcance de merchant deben indicar el merchant objetivo mediante merchant_id. Consulta Autenticación para conocer la anatomía completa de las claves y sus alcances.

Paso 2 — Realiza tu primera solicitud autenticada

Verifica tu clave secreta con una lectura simple. Lista los clientes:

curl https://api.tokeflow.com/api/v1/customers?limit=1 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Cada respuesta viene envuelta en el sobre estándar. Una lista devuelve data como un arreglo más meta.pagination:

{
  "success": true,
  "data": [
    {
      "id": "cust_a1b2c3d4e5",
      "merchant_id": "mrc_a1b2c3d4e5",
      "email": "joao@example.com",
      "name": "Joao da Silva",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 1,
      "total": 42,
      "total_pages": 42,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c1a2b",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Si la clave es incorrecta, obtienes el sobre de error estándar con HTTP 401:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid.",
    "details": {},
    "request_id": "req_9a0b1c2d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Paso 3 — Crea un cliente

Crea el cliente al que estás a punto de cobrar. Esta llamada es idempotente por email: si el email ya existe, se devuelve el registro existente con HTTP 200 en lugar de 201.

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "document_type": "cpf",
    "document_number": "123.456.789-00"
  }'

Un único recurso omite meta:

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "created_at": "2026-01-15T12:00:00.000Z"
  },
  "request_id": "req_1f2e3d4c",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Paso 4 — Crea una sesión de checkout

Una sesión de checkout captura lo que el cliente está comprando. Referencia una oferta (una configuración de precio vendible para un producto) y Tokeflow deriva de ella el monto y la moneda — así nunca codificas precios de forma rígida en el cobro.

curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "selected_currency": "BRL",
    "items": [
      { "offer_id": "ofr_a1b2c3d4e5", "quantity": 1, "installments": 1 }
    ]
  }'

{
  "success": true,
  "data": {
    "id": "cks_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "selected_currency": "BRL",
    "status": "initiated",
    "expires_at": null,
    "completed_at": null,
    "created_at": "2026-01-15T12:05:00.000Z",
    "updated_at": "2026-01-15T12:05:00.000Z"
  },
  "request_id": "req_2c3d4e5f",
  "timestamp": "2026-01-15T12:05:00.000Z"
}

Conserva cks_a1b2c3d4e5 — lo referenciarás cuando cobres en el Paso 6.

Paso 5 — Recolecta el pago en el navegador

Los datos de la tarjeta nunca deben tocar tus servidores. El Bridge SDK ejecuta los campos seguros de Tokeflow dentro de iframes aislados y de origen cruzado; los datos de la tarjeta se cifran en el navegador y se intercambian por un token de un solo uso. Inicializa el SDK con tu clave pública y el id de la sesión de checkout:

import { TokeflowBridge } from "@tokeflow_com/bridge-js";

const tokeflow = new TokeflowBridge({
  publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx",
  checkoutSessionId: "cks_a1b2c3d4e5",
});
await tokeflow.init();

// Create and mount a secure card element, then tokenize on submit:
const cardElement = tokeflow.createCardElement();
cardElement.mount("#card-element");

const token = await tokeflow.cards.tokenize({ card: cardElement });
// token.tokenId => "tok_a1b2c3d4e5" — send this to YOUR server

Envía el token.tokenId resultante (tok_…) a tu backend. Es de un solo uso y de corta duración.

Paso 6 — Cobra

Ahora cobra del lado del servidor. Referencia la sesión de checkout (el monto y la moneda provienen de ella) y el token del SDK. Envía un Idempotency-Key para que una solicitud reintentada nunca cobre dos veces.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_2026_0115_attempt_1" \
  -d '{
    "checkout_session_id": "cks_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "capture": true,
    "card_ciphertext_id": "tok_a1b2c3d4e5"
  }'

El primer envío devuelve HTTP 201; reproducir el mismo Idempotency-Key devuelve el resultado original con HTTP 200. Lee siempre el campo status — esa es la fuente de verdad del resultado.

{
  "success": true,
  "data": {
    "id": "tx_a1b2c3d4e5",
    "organization_id": "org_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "amount_authorized": 9900,
    "amount_captured": 9900,
    "currency": "BRL",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "status": "authorized",
    "timeline": [
      {
        "attempt_number": 1,
        "is_fallback": false,
        "connector_id": "conn_a1b2c3",
        "provider_slug": "acquirer_a",
        "status": "success",
        "started_at": "2026-01-15T12:10:00.000Z",
        "finished_at": "2026-01-15T12:10:02.000Z"
      }
    ],
    "payment_instructions": null,
    "metadata": {},
    "created_at": "2026-01-15T12:10:00.000Z",
    "updated_at": "2026-01-15T12:10:02.000Z"
  },
  "request_id": "req_3d4e5f6a",
  "timestamp": "2026-01-15T12:10:02.000Z"
}

Valores de estado de transacción que puedes ver: pending, pre_authorized, authorized, capture_pending, failed, canceled, voided, refund_pending, refunded, partially_refunded, charged_back, expired. Para métodos asíncronos como pix y boleto, la respuesta incluye payment_instructions (código QR o código de barras) y el estado comienza en pending.

Paso 7 — Recibe un webhook

El sondeo es innecesario. Cuando la transacción se asienta en un estado terminal, Tokeflow entrega un webhook normalizado al endpoint que registraste durante el onboarding — por ejemplo transaction.authorized:

{
  "id": "evt_4e5f6a7b8c9d",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:10:02.000Z",
  "data": {
    "object": {
      "id": "tx_a1b2c3d4e5",
      "current_status": "authorized",
      "amount_captured": 9900,
      "currency": "BRL"
    }
  }
}

Cada entrega lleva un encabezado X-Tokeflow-Signature. Verifícalo contra el cuerpo sin procesar de la solicitud antes de confiar en el payload, y rechaza las entregas cuyo timestamp esté fuera de tu ventana de tolerancia. El código completo de verificación y el catálogo de eventos están en Webhooks.

Lo lograste

Una única superficie de API, tus proveedores detrás de ella, tu marca por encima. A partir de aquí:

• Autenticación — tipos de clave, alcances y el modelo org-vs-merchant en profundidad.
• Sesiones de checkout — ítems, selección de moneda y eventos del ciclo de vida.
• Transacciones — captura, anulación, reembolso y lectura de la timeline de intentos.
• Bridge SDK — campos seguros, tarjetas guardadas, wallets y orquestación de 3DS.
• Webhooks — verificación de firma y la lista completa de eventos.