How Tokeflow works

Tokeflow is the infrastructure behind your platform. You connect multiple payment providers once, apply smart routing rules, and run every payment through a single, normalized API — under your own brand.

Tokeflow orchestrates payments. It does not process or settle funds: authorization, capture, and settlement are performed by the payment providers you connect. Tokeflow sits in front of those providers and gives you one consistent contract, smart routing, resilience, and a unified audit trail across all of them.

This page explains the moving parts and walks through what happens, step by step, when a payment is made.

The building blocks

Four primitives make up almost everything you build on Tokeflow.

API

The REST API at https://api.tokeflow.com is the server-side core. Every endpoint lives under /api/v1 (URI versioning; the current version is v1). Your backend authenticates with a secret key (Authorization: Bearer sk_live_…) and uses the API to create transactions, capture or void authorizations, issue refunds, manage the product catalog, and read back normalized results. Keys are scoped to either an Organization or a single Merchant, and every response is wrapped in a consistent success or error envelope. See Authentication.

Bridge SDK

The Bridge SDK is the browser-side companion to the API. It renders secure fields and collects sensitive card data without that data ever touching your servers. Tokeflow's secure fields run inside isolated, cross-origin iframes; card data is encrypted in the browser and never reaches your infrastructure. The SDK authenticates with a public key (pk_live_…), which is safe to expose in client code, and returns a short-lived reference your backend uses to charge the card. See the Bridge SDK.

Checkout Sessions

A Checkout Session models a hosted or embedded purchase flow. It tracks the customer, the items, the selected currency, and the lifecycle of the buying experience — from initiated through customer_identified and payment_pending to completed. Sessions emit granular events you can react to, and when a session is charged, Tokeflow runs the same orchestration as a direct API transaction. Use sessions when you want Tokeflow to coordinate the front-of-funnel experience; use the transactions API directly when your platform already owns the checkout UI. See Checkout Sessions.

Webhooks

Webhooks are how Tokeflow tells your systems what happened. Every meaningful state change — a transaction authorizing, a refund succeeding, a chargeback opening, a subscription entering dunning — is delivered as a signed, normalized event to the endpoint you register during onboarding. Because Tokeflow normalizes provider-specific notifications into one schema, your webhook handler does not change when you add or swap providers. Every payload is signed with X-Tokeflow-Signature so you can verify authenticity. See Webhooks.

Anatomy of a payment

Here is the end-to-end path of a card payment, from the customer's browser to a normalized result and webhook.

1. Collect the card client-side. Your frontend mounts the Bridge SDK's secure fields. The customer types their card details into isolated, cross-origin iframes. The data is encrypted in the browser and never touches your servers. The SDK returns a short-lived reference to the encrypted card.
2. Send the reference to your backend. Your frontend posts the reference (and the order context) to your own backend over your normal channel. No raw card data is involved.
3. Create the transaction. Your backend calls POST /api/v1/transactions with a secret key, the amount in minor units, the currency, and the card reference. Alternatively, a Checkout Session is charged, which triggers the same flow. Send an Idempotency-Key so retries never double-charge.
4. Tokeflow selects a provider. Smart routing rules pick the best provider for this transaction based on attributes like country, currency, payment method, and amount.
5. Cascade on soft declines. If the chosen provider returns a soft decline (a retriable failure such as an issuer timeout or a temporary "do not honor"), Tokeflow automatically cascades to the next eligible provider in the route. Hard declines (such as stolen card or invalid card) are not retried.
6. Return a normalized result. Tokeflow returns a single, provider-agnostic transaction object. The status field tells you the outcome, and the timeline array records every attempt — including which providers were tried and why each one succeeded or failed.
7. Emit webhooks. Tokeflow emits signed, normalized webhook events for the resulting state changes so your downstream systems stay in sync without polling.

Authorization vs capture

Card payments separate two steps: authorization reserves the funds on the customer's card, and capture actually collects them. Tokeflow lets you do both at once or split them.

• Authorize and capture together. Set capture: true on POST /api/v1/transactions. On success the transaction lands in authorized and the funds are collected in one step. This is the default for most one-shot purchases.
• Authorize now, capture later (pre-auth). Set capture: false. On success the transaction lands in pre_authorized — the funds are reserved but not collected. Later, you collect them with a capture call, or release the hold with a void.

This two-step model is useful when the final amount or fulfillment is not known at the moment of purchase — for example, reserving an amount at order time and capturing once the order ships.

The transaction lifecycle

Every transaction carries a normalized status that is identical across providers. The diagram below shows how a transaction moves between the canonical states.

Routing and resilience

Two features turn a list of connected providers into a resilient payment layer: smart routing and cascade fallback.

Smart routing

Smart routing chooses which provider handles a given transaction. You define rules in the Dashboard, and Tokeflow evaluates them per transaction using attributes such as country, currency, payment method, card brand, and amount. Routing lets you direct traffic to the provider with the best economics or approval rates for each segment of your volume — without changing a line of integration code. When a rule matches, its identifier is recorded on the transaction so every decision is auditable.

Cascade fallback

Cascade fallback decides what happens next when a provider can't complete the payment. If the selected provider returns a soft decline — a retriable failure like an issuer timeout, a temporary network error, or a transient "do not honor" — Tokeflow automatically retries the same authorization against the next eligible provider in the route. This recovers revenue that would otherwise be lost to transient failures. Hard declines (such as an invalid or stolen card) are terminal and are never retried, so customers aren't charged on a card the issuer has refused.

The result is the same normalized transaction object regardless of how many providers were tried. Your integration sees one contract; Tokeflow handles the orchestration behind it.

Next steps

• Authentication — keys, scopes, and the request envelope.
• Bridge SDK — collect cards securely in the browser.
• Transactions — create, capture, void, and refund.
• Webhooks — verify signatures and react to events.