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,
"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,
"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,
"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.
Register a token created via SDK.
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 of one_time, instrument_enrollment. |
save_card | boolean | No | When true, a card tokenized inside a one_time checkout is minted as an instrument_enrollment token so the customer can save it for later use. Ignored for recurring offers (always enrolled) and outside a checkout session. |
additionalMetadata | object | No | Optional additional metadata to store with the token. |
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": "ev:QkTC:q6/SoVBehipxsy6j:...",
"cvc": "ev:QkTC:JfW5fyt5eOb2vXAX:...",
"expiryMonth": "12",
"expiryYear": "25",
"name": "ev:QkTC:..."
},
"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"
}GET/api/v1/tokens/:tokenId
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.