Sesiones y tokens

Los endpoints del lado del servidor detrás del Bridge SDK — crea una sesión de navegador, intercambia datos de tarjeta cifrados por una referencia de token de un solo uso y lee los detalles no sensibles de un token.

Estos son los endpoints que el Bridge SDK llama en tu nombre. Una sesión de navegador delimita lo que el SDK puede hacer — para qué Merchant actúa, a qué checkout está vinculada y cuánto dura. Un token es la referencia de un solo uso (tok_…) que sustituye a los datos de tarjeta que tus servidores nunca ven.

La mayoría de las integraciones nunca llaman a estos endpoints directamente: @tokeflow_com/bridge-js se encarga del handshake de la sesión y la tokenización por ti. Los documentamos aquí porque definen el contrato — y porque los flujos impulsados por el servidor a veces necesitan crear una sesión o inspeccionar los metadatos no sensibles de un token directamente. Consulta la visión general del Bridge SDK para el camino del lado del cliente.

Los datos de tarjeta se recopilan dentro de iframes aislados y cross-origin y se cifran en el navegador — nunca llegan a tus servidores, ni tampoco el PAN o el CVC en bruto. Estos endpoints solo devuelven las partes no sensibles de un token (marca, últimos cuatro dígitos, vencimiento). Nunca intentes enviarles datos de tarjeta en bruto.

El objeto sesión

Lo que una sesión expone al SDK una vez creada.

Campo	Tipo	Descripción
`sessionId`	string	ID de la sesión.
`expiresAt`	string	Marca de tiempo de expiración de la sesión (ISO 8601).
`merchant`	object	Información del Merchant.
`capabilities`	object	Capacidades de pago del Merchant.
`settings`	object	Configuración de tokenización del Merchant.
`sdk`	object	Información de integridad del SDK.
`installmentsSupported`	boolean	Si el Merchant admite cuotas.
`installmentOptions`	object	Opciones de cuotas admitidas por el Merchant, indexadas por método de pago.

Endpoints

POST`/api/v1/sessions`

Auth: Public key (X-Public-Key). Seguro en el cliente — utilizable desde el navegador.

Crea una sesión de SDK para tokenización.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`sdkVersion`	string	No	Versión del SDK usada por el cliente.
`checkoutSessionId`	string	No	Sesión de checkout a vincular con esta sesión de SDK. Validada contra el Merchant en la creación; obligatoria para luego leer la sesión de checkout vía GET /sessions/checkout.
`metadata`	object	No	Metadatos opcionales para almacenar con la sesión.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/sessions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "sdkVersion": "2.0.0",
    "checkoutSessionId": "cks_1234567890abcdef",
    "metadata": {
      "customerId": "cus_123",
      "checkoutId": "chk_456"
    }
  }'

Ejemplo de respuesta — 201

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2024-01-15T12:30:00.000Z",
  "merchant": {
    "id": "mrc_abc123",
    "name": "Acme Store",
    "organizationId": "org_xyz789"
  },
  "capabilities": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": true,
    "googlePay": true
  },
  "settings": {
    "allowedCardBrands": [
      "visa",
      "mastercard",
      "amex"
    ],
    "requireCvc": true,
    "requireCardholderName": true,
    "collectBillingAddress": true
  },
  "sdk": {
    "sriHash": "sha256-abcdef1234567890...",
    "sriExpiresAt": "2024-01-15T12:30:00.000Z"
  },
  "installmentsSupported": true,
  "installmentOptions": {
    "credit_card": {
      "min": 2,
      "max": 12
    },
    "pix": null
  }
}

GET`/api/v1/sessions/checkout`

Auth: Public key (X-Public-Key). Seguro en el cliente — utilizable desde el navegador.

Obtiene el contexto completo de checkout de la sesión de SDK — la sesión de checkout, los métodos de pago disponibles y las tarjetas guardadas del cliente.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/sessions/checkout \
  -H "Authorization: Bearer sk_live_mer_…"

Ejemplo de respuesta — 200

{
  "checkout": {
    "id": "cks_a1b2c3d4e5",
    "merchantId": "mer_a1b2c3d4e5",
    "offerId": "ofr_a1b2c3d4e5",
    "customerId": "mcu_a1b2c3d4e5",
    "customerEmail": "jane@acme.com",
    "customerName": "Jane Doe",
    "selectedCurrency": "BRL",
    "status": "initiated",
    "externalSessionId": "sess_external_42",
    "expiresAt": "2026-05-20T18:00:00Z",
    "completedAt": "2026-05-20T17:32:11Z",
    "createdAt": "2026-05-19T12:00:00Z",
    "updatedAt": "2026-05-19T12:00:00Z",
    "items": [
      {
        "id": "cki_a1b2c3d4e5",
        "checkoutSessionId": "cks_a1b2c3d4e5",
        "offerId": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 9900,
        "firstChargeAmount": 0,
        "quantity": 1,
        "installments": 1,
        "createdAt": "2026-05-19T12:00:00Z"
      }
    ]
  },
  "paymentMethods": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": false,
    "googlePay": false,
    "cardBrands": [
      "visa",
      "mastercard"
    ],
    "installmentsSupported": true,
    "installmentOptions": {
      "credit_card": {
        "min": 1,
        "max": 12
      }
    }
  },
  "savedInstruments": [
    {
      "id": "pi_a1b2c3d4e5",
      "instrumentType": "card",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2030
    }
  ]
}

POST`/api/v1/sessions/:sessionId/payment-instruments`

Auth: Public key (X-Public-Key). Seguro en el cliente — utilizable desde el navegador.

Verifica una tarjeta (zero-dollar / SetupIntent) y la registra en archivo para futuros cobros iniciados por el Merchant.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`tokenId`	string	Sí	La referencia de enrollment cifrada de un solo uso (`tok_…`) del Bridge SDK a verificar y guardar.
`customerId`	string	No	id del cliente Tokeflow (cust_*) al que pertenece la tarjeta. Recurre al cliente del checkout vinculado.
`currency`	string	No	Moneda ISO 4217 para el enrutamiento de verificación. Recurre a la moneda del checkout vinculado.
`country`	string	No	País ISO 3166-1 alpha-2. Recurre al país del Merchant.
`connectorId`	string	No	Verifica contra un conector específico; de lo contrario, se enruta.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/sessions/ses_8c3a5d17/payment-instruments \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenId": "tok_8f3c2a1b9d4e",
    "customerId": "cust_2f9a71d4",
    "currency": "BRL",
    "country": "BR",
    "connectorId": "conn_a1b2c3d4"
  }'

Ejemplo de respuesta — 201

{
  "verified": true,
  "paymentInstrumentId": "string",
  "status": "active",
  "brand": "string",
  "last4": "string",
  "expMonth": 1,
  "expYear": 1,
  "reason": "requested_by_customer"
}

POST`/api/v1/sessions/:sessionId/refresh`

Auth: Public key (X-Public-Key). Seguro en el cliente — utilizable desde el navegador.

Renueva la sesión de SDK.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`sessionId`	string	Sí	—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/sessions/ses_8c3a5d17/refresh \
  -H "Authorization: Bearer sk_live_mer_…"

Ejemplo de respuesta — 200

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2024-01-15T12:30:00.000Z",
  "merchant": {
    "id": "mrc_abc123",
    "name": "Acme Store",
    "organizationId": "org_xyz789"
  },
  "capabilities": {
    "cards": true,
    "pix": true,
    "boleto": false,
    "applePay": true,
    "googlePay": true
  },
  "settings": {
    "allowedCardBrands": [
      "visa",
      "mastercard",
      "amex"
    ],
    "requireCvc": true,
    "requireCardholderName": true,
    "collectBillingAddress": true
  },
  "sdk": {
    "sriHash": "sha256-abcdef1234567890...",
    "sriExpiresAt": "2024-01-15T12:30:00.000Z"
  },
  "installmentsSupported": true,
  "installmentOptions": {
    "credit_card": {
      "min": 2,
      "max": 12
    },
    "pix": null
  }
}

POST`/api/v1/tokens`

Auth: Public key (X-Public-Key). Seguro en el cliente — utilizable desde el navegador.

Registra un token creado vía SDK.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`encryptedCard`	object	Sí	Datos de tarjeta cifrados del Bridge SDK.
`metadata`	object	Sí	Metadatos de la tarjeta (no cifrados).
`purpose`	string	No	Finalidad del token: `one_time` (predeterminado — un solo uso, caduca a los 30 minutos) o `instrument_enrollment` (sin caducidad; puede guardarse como instrumento de pago). Se respeta solo en la tokenización independiente — una sesión del SDK creada sin `checkoutSessionId`.
`save_card`	boolean	No	Dentro de una sesión de checkout de una oferta puntual, `true` emite un token `instrument_enrollment` para que la tarjeta pueda guardarse. Se ignora para ofertas recurrentes (siempre registradas) y fuera de una sesión de checkout.
`additionalMetadata`	object	No	Metadatos adicionales opcionales para almacenar con el token.

Cómo se decide la finalidad

Contexto	`purpose` resultante
Sesión independiente (sin sesión de checkout vinculada)	Lo que envíes; `one_time` si se omite. `save_card` no tiene efecto.
Sesión de checkout, oferta recurrente	Siempre `instrument_enrollment`.
Sesión de checkout, oferta puntual	`instrument_enrollment` cuando `save_card: true`, en caso contrario `one_time`. Cualquier `purpose` que envíes se ignora.

La respuesta devuelve la finalidad que realmente se emitió. Compruébala: un token one_time lo rechazan save_payment_instrument, POST /merchants/:merchant_id/payment-instruments y POST /sessions/:sessionId/payment-instruments. El Bridge SDK expone ambos campos como saveCard y purpose en TokenizeOptions.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "encryptedCard": {
      "number": "<encrypted by the Bridge SDK>",
      "cvc": "<encrypted by the Bridge SDK>",
      "expiryMonth": "12",
      "expiryYear": "25",
      "name": "<encrypted by the Bridge SDK>"
    },
    "metadata": {
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "bin": "424242"
    },
    "purpose": "one_time",
    "save_card": true,
    "additionalMetadata": {
      "customerId": "cus_123",
      "source": "checkout"
    }
  }'

Ejemplo de respuesta — 201

{
  "tokenId": "tok_8f3c2a1b9d4e",
  "merchant_id": "mrc_123",
  "purpose": "instrument_enrollment",
  "last4": "4242",
  "card_brand": "visa",
  "exp_month": "12",
  "exp_year": "2028",
  "status": "active",
  "expires_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2025-11-28T12:00:00Z"
}

POST`/api/v1/payer-tokens`

Auth: Public key (X-Public-Key) y una sesión del SDK (X-Session-Id). Seguro en el cliente — utilizable desde el navegador.

Registra al pagador de un cargo PIX o boleto y obtén un token de pagador (ptk_…). El Bridge SDK lo llama desde pix.tokenize() y boleto.tokenize(). Después, tu servidor envía el token como payer_token_id en POST /transactions, de modo que nunca maneja el CPF/CNPJ ni la dirección del pagador.

El pagador se envía por TLS, sin cifrarse en el navegador, porque Tokeflow tiene que leerlo para validarlo y pasarlo al proveedor. Se almacena cifrado y se elimina en cuanto el token se usa o caduca.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`payment_method`	string	Sí	`pix` o `boleto`. El token solo puede cobrarse con este método.
`name`	string	Sí	Nombre completo del pagador, hasta 200 caracteres.
`email`	string	Sí	Correo electrónico del pagador.
`phone`	string	No	Número de teléfono en formato internacional, p. ej. `+5511999990000`.
`document`	string	Sí	CPF o CNPJ; se acepta la puntuación. Se verifican los dígitos de control. Se aceptan CNPJ alfanuméricos.
`document_type`	string	No	`cpf` o `cnpj`, sin distinguir mayúsculas y minúsculas. Se infiere de la longitud del documento cuando se omite.
`address`	object	Boleto	Dirección de facturación. Obligatoria para un boleto (`street`, `neighborhood`, `city`, `state`, `postal_code`; `number` y `complement` opcionales). No es necesaria para PIX. `state` es una UF de dos letras; `postal_code` es un CEP, `01310-100` o `01310100`.

Ejemplo de respuesta — 201 Created

{
  "tokenId": "ptk_abc123",
  "type": "boleto",
  "document_type": "cpf",
  "document_last_digits": "25",
  "status": "active",
  "expires_at": "2026-10-26T12:30:00.000Z",
  "created_at": "2026-10-26T12:00:00.000Z"
}

Regla	Detalle
Vigencia	De un solo uso; caduca 30 minutos después de su creación. Un cargo fallido también consume el token — vuelve a recoger los datos del pagador para reintentar.
Sesión de checkout	Cuando la sesión del SDK está vinculada a una sesión de checkout, el token solo puede cobrarse con ese `checkout_session_id`.
Errores de campo	`400` con `details` que nombra cada campo faltante o inválido.

GET`/api/v1/tokens/:tokenId`

OrgMerchant

Auth: Organization key (con merchant_id) o Merchant key.

Recupera los detalles del token.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`tokenId`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/tokens/tok_8f3c2a1b9d4e \
  -H "Authorization: Bearer sk_live_mer_…"

Ejemplo de respuesta — 200

{
  "tokenId": "tok_8f3c2a1b9d4e",
  "merchant_id": "mrc_123",
  "purpose": "instrument_enrollment",
  "last4": "4242",
  "card_brand": "visa",
  "exp_month": "12",
  "exp_year": "2028",
  "status": "active",
  "expires_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2025-11-28T12:00:00Z"
}

Errores

Los errores usan el envelope estándar. Los casos más comunes aquí:

HTTP	`type`	Causa típica
`400`	`validation_error`	Campo obligatorio ausente, o una operación que el estado actual no permite.
`401`	`authentication_error`	Clave de API ausente o inválida.
`403`	`authorization_error`	La clave no tiene el alcance requerido.
`404`	`not_found_error`	El recurso no existe o no pertenece a esta entidad.
`429`	`rate_limit_error`	Límite de tasa excedido — aplica retroceso exponencial.

Consulta Errores para el catálogo completo.

Sesiones y tokens

El objeto sesión

Endpoints

POST`/api/v1/sessions`

GET`/api/v1/sessions/checkout`

POST`/api/v1/sessions/:sessionId/payment-instruments`

POST`/api/v1/sessions/:sessionId/refresh`

POST`/api/v1/tokens`

Cómo se decide la finalidad

POST`/api/v1/payer-tokens`

GET`/api/v1/tokens/:tokenId`

Errores

Relacionados

En esta página

Sesiones y tokens

El objeto sesión

Endpoints

POST/api/v1/sessions

GET/api/v1/sessions/checkout

POST/api/v1/sessions/:sessionId/payment-instruments

POST/api/v1/sessions/:sessionId/refresh

POST/api/v1/tokens

Cómo se decide la finalidad

POST/api/v1/payer-tokens

GET/api/v1/tokens/:tokenId

Errores

Relacionados

En esta página

POST`/api/v1/sessions`

GET`/api/v1/sessions/checkout`

POST`/api/v1/sessions/:sessionId/payment-instruments`

POST`/api/v1/sessions/:sessionId/refresh`

POST`/api/v1/tokens`

POST`/api/v1/payer-tokens`

GET`/api/v1/tokens/:tokenId`