Sessions and tokens

The server-side endpoints behind the Bridge SDK — create a browser session, exchange encrypted card data for a single-use token reference, and read a token's non-sensitive details.

These are the endpoints the Bridge SDK calls on your behalf. A browser session scopes what the SDK may do — which merchant it acts for, which checkout it is attached to, and how long it lives. A token is the single-use reference (tok_…) that stands in for card data your servers never see.

Most integrations never call these directly: @tokeflow_com/bridge-js handles the session handshake and tokenization for you. Document them here because they define the contract — and because server-driven flows sometimes need to create a session or inspect a token's non-sensitive metadata directly. See the Bridge SDK overview for the client-side path.

Card data is collected inside isolated, cross-origin iframes and encrypted in the browser — it never reaches your servers, and neither does the raw PAN or CVC. These endpoints only ever return the non-sensitive parts of a token (brand, last four, expiry). Never attempt to send raw card data to them.

The session object

What a session exposes to the SDK once created.

Field	Type	Description
`sessionId`	string	Session ID.
`expiresAt`	string	Session expiration timestamp (ISO 8601).
`merchant`	object	Merchant information.
`capabilities`	object	Merchant payment capabilities.
`settings`	object	Merchant tokenization settings.
`sdk`	object	SDK integrity information.
`installmentsSupported`	boolean	Whether installments are supported by the merchant.
`installmentOptions`	object	Installment options supported by the merchant, keyed by payment method.

Endpoints

POST`/api/v1/sessions`

Auth: Public key (X-Public-Key). Client-safe — usable from the browser.

Create SDK session for tokenization.

Request fields

Field	Type	Required	Description
`sdkVersion`	string	No	SDK version used by the client.
`checkoutSessionId`	string	No	Checkout session to link to this SDK session. Validated against the merchant on creation; required to later read the checkout session via GET /sessions/checkout.
`metadata`	object	No	Optional metadata to store with the session.

Example request

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"
    }
  }'

Example response — 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). Client-safe — usable from the browser.

Get the full checkout context for the SDK session — the checkout session, available payment methods, and the customer saved cards.

Example request

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

Example response — 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). Client-safe — usable from the browser.

Verify a card (zero-dollar / SetupIntent) and enroll it on file for future merchant-initiated charges.

Request fields

Field	Type	Required	Description
`tokenId`	string	Yes	The single-use encrypted enrollment reference (`tok_…`) from the Bridge SDK to verify and save.
`customerId`	string	No	Tokeflow customer id (cust_*) the card belongs to. Falls back to the linked checkout customer.
`currency`	string	No	ISO 4217 currency for verification routing. Falls back to the linked checkout currency.
`country`	string	No	ISO 3166-1 alpha-2 country. Falls back to the merchant country.
`connectorId`	string	No	Verify against a specific connector; otherwise routed.

Example request

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"
  }'

Example response — 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). Client-safe — usable from the browser.

Refresh SDK session.

Path parameters

Field	Type	Required	Description
`sessionId`	string	Yes	—

Example request

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

Example response — 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). Client-safe — usable from the browser.

Request fields

Field	Type	Required	Description
`encryptedCard`	object	Yes	Encrypted card data from the Bridge SDK.
`metadata`	object	Yes	Card metadata (not encrypted).
`purpose`	string	No	Purpose of the token: `one_time` (default — single-use, expires after 30 minutes) or `instrument_enrollment` (no expiry; can be saved as a payment instrument). Honored only for standalone tokenization — an SDK session created without a `checkoutSessionId`.
`save_card`	boolean	No	Inside a checkout session for a one-time offer, `true` mints an `instrument_enrollment` token so the card can be saved. Ignored for recurring offers (always enrolled) and outside a checkout session.
`additionalMetadata`	object	No	Optional additional metadata to store with the token.

How the purpose is decided

Context	Resulting `purpose`
Standalone session (no checkout session linked)	Whatever you send; `one_time` when omitted. `save_card` has no effect.
Checkout session, recurring offer	Always `instrument_enrollment`.
Checkout session, one-time offer	`instrument_enrollment` when `save_card: true`, otherwise `one_time`. Any `purpose` you send is ignored.

The response echoes the purpose that was actually minted. Check it: a one_time token is refused by save_payment_instrument, by POST /merchants/:merchant_id/payment-instruments and by POST /sessions/:sessionId/payment-instruments. The Bridge SDK exposes both fields as saveCard and purpose on TokenizeOptions.

Example request

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"
    }
  }'

Example response — 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) and an SDK session (X-Session-Id). Client-safe — usable from the browser.

Register the payer of a PIX or boleto charge and get back a payer token (ptk_…). The Bridge SDK calls it from pix.tokenize() and boleto.tokenize(). Your server then sends the token as payer_token_id on POST /transactions, so it never handles the payer's CPF/CNPJ or address.

The payer is sent over TLS, not encrypted in the browser, because Tokeflow has to read it to validate it and pass it to the provider. It is stored encrypted and deleted once the token is used or expires.

Request fields

Field	Type	Required	Description
`payment_method`	string	Yes	`pix` or `boleto`. The token can only be charged with this method.
`name`	string	Yes	Payer's full name, up to 200 characters.
`email`	string	Yes	Payer's email.
`phone`	string	No	Phone number in international format, e.g. `+5511999990000`.
`document`	string	Yes	CPF or CNPJ; punctuation is accepted. Check digits are verified. Alphanumeric CNPJs are accepted.
`document_type`	string	No	`cpf` or `cnpj`, case-insensitive. Inferred from the document's length when omitted.
`address`	object	Boleto	Billing address. Required for a boleto (`street`, `neighborhood`, `city`, `state`, `postal_code`; `number` and `complement` optional). Not needed for PIX. `state` is a two-letter UF; `postal_code` is a CEP, `01310-100` or `01310100`.

Example response — 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"
}

Rule	Detail
Lifetime	Single use; expires 30 minutes after creation. A failed charge also spends the token — collect the payer again to retry.
Checkout session	When the SDK session is linked to a checkout session, the token can only be charged with that `checkout_session_id`.
Field errors	`400` with `details` naming each missing or invalid field.

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

OrgMerchant

Auth: Organization key (with merchant_id) or Merchant key.

Retrieve token details.

Path parameters

Field	Type	Required	Description
`tokenId`	string	Yes	—

Example request

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

Example response — 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"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTP	`type`	Typical cause
`400`	`validation_error`	Missing required field, or an operation the current state does not allow.
`401`	`authentication_error`	Missing or invalid API key.
`403`	`authorization_error`	The key lacks the required scope.
`404`	`not_found_error`	The resource does not exist or is not owned by this entity.
`429`	`rate_limit_error`	Rate limit exceeded — back off exponentially.

See Errors for the full catalog.

Sessions and tokens

The session object

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

How the purpose is decided

POST/api/v1/payer-tokens

GET/api/v1/tokens/:tokenId

Errors

Related

On this page

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`