Changelog

This is the running record of changes to the Tokeflow platform — the REST API and the Bridge SDK. Entries are listed newest first, each one dated and grouped by Added, Changed, and Fixed.

Tokeflow is the orchestration layer behind your platform: the API and SDK shapes documented in this reference are stable, and we evolve them carefully. Most releases are additive — new fields, new enum values, new endpoints — and these can appear within the current major version (v1) at any time. Build clients that ignore unknown fields so additive changes never break you.

How to read this changelog

Each entry notes whether it affects the API, the SDK, or both.

---

2026-10-26 — Boleto, PIX and boleto payer tokens, rate limits by route class

PIX and boleto payers can now be collected in the browser and charged by reference, boleto joins the Bridge SDK, and rate limits are set per kind of route. All API changes are backward compatible.

Added

REST API v1 (API)

• Payer tokens — POST /payer-tokens registers the payer of a PIX or boleto charge (name, email, CPF/CNPJ and, for a boleto, the billing address) and returns a single-use ptk_… that expires after 30 minutes. Charge it with the new payer_token_id on POST /transactions, so your server never handles the payer's document or address. An unusable token is refused with 400 INVALID_PAYER_TOKEN. See PIX and boleto payers.
• Boleto options — boleto.expires_in_days (1–30, default 3) on POST /transactions; a due date on a weekend moves to the next business day.
• Boleto payment instructions — digitable_line alongside barcode, boleto_url and due_date (Brasília time, after the weekend roll-forward). See Async methods.
• boleto capability on the SDK session and in the checkout context's paymentMethods — true only when a connector the merchant routes boleto to can charge one.

Bridge SDK 2.8.0 and 2.8.1 (SDK)

• Boleto — tokeflow.boleto.tokenize(), 'boleto' in getAvailablePaymentMethods() / useAvailablePaymentMethods(), and the React <BoletoInstructions> component. See Boleto.
• New types BoletoToken, PixTokenizeParams, BoletoTokenizeParams, PaymentInstructions, PixInstructions, BoletoInstructions, and the error code INVALID_DOCUMENT. AvailablePaymentMethod gains 'boleto' — an exhaustive switch over it needs a new case.

Changed

• Rate limits by route class (API): limits are now counted per key and per route in 60-second windows, with a ceiling set by the kind of route — 600 requests per minute for payment and read routes, 1,200 for checkout events (plus a per-session limit), 600 for Bridge SDK routes (plus a per-IP limit) and 60 for SDK card verification; other routes keep 100. A 429 now carries Retry-After and X-RateLimit-* headers describing the budget that blocked it. Higher limits can be granted per key — contact the Tokeflow team. See Rate limits.
• pix.tokenize() (SDK 2.8.0): returns a payer token (ptk_…) the API can charge with payer_token_id; email is now required, document accepts a CPF or CNPJ, and the token gains documentType, documentLastDigits and expiresAt (cpfLastDigits is deprecated). Upgrade to 2.8.0 for PIX: earlier versions returned a token that could not be charged. See PIX.
• Customer matching (API): a payer token's email alone never links a charge to an existing customer; send customer_id, or the same email from your server.

Fixed

• Capture and void races (API): a capture and a void on the same authorization can no longer both take effect. The call that loses answers 409 (conflict_error); read the transaction back instead of retrying. See Capture.
• Bridge SDK 2.7.1: the published 2.7.0 package contained the 2.6.0 build, without savedCardCheckoutEnabled and SavedInstrument.reusable. Use 2.7.1 or later.
• Bridge SDK 2.8.1: the React entry imports the core instead of bundling a copy, so instanceof TokeflowError works across both entries and the React bundle is about 80% smaller.

---

2026-10-09 — Decline reasons, saved-card checkout, live/test mode

Every failed attempt now says why it failed in one provider-neutral word, saved cards can pay a checkout session, and every transaction says whether it ran on live or test credentials. All changes are backward compatible.

Added

REST API v1 (API)

• Decline reasons — decline_reason on each timeline entry and on GET /transactions/:id/attempts, and on the error envelope of payment errors that have one. Every provider's decline codes map onto one vocabulary (insufficient_funds, card_expired, do_not_honor, other, …), so the same word means the same thing whichever connector answered. The list only grows; see Decline reasons.
• Saved-card checkout — credential_on_file: true with payment_instrument_id can now pay a checkout_session_id: the session supplies amount, currency and customer, and a recurring offer starts its subscription on the connector holding the card's credential. Gated by the new merchant opt-in saved_card_checkout_enabled (off by default) on the merchant object and on PATCH /merchants/:id.
• mode on the transaction object — live or test, from the connector of the final attempt; null when the charge was refused before routing.
• payment_provider_id on the connector object, so you can read a connection's provider even after it stops being listed as active.

Bridge SDK (SDK)

• Saved-card checkout is live. savedCardCheckoutEnabled and SavedInstrument.reusable (SDK 2.7.1+) now report real values once the merchant opts in; they are no longer reserved. Use SDK 2.7.1 or later — the published 2.7.0 package contained an older build.

Dashboard

• Orders show a live/test badge, can be filtered by mode, and failed attempts show their decline reason next to the provider's own code. See Merchant orders.

Changed

• One routing policy for declines (API): the decline reason now decides how a decline is handled, identically for every provider — which customer-initiated declines are retried and cascaded, and which stop. On subscription renewals, a renewal is never retried within the request; only a reason that says the card can never be charged again cancels the subscription, and every other decline is dunned.
• Charges with no provider answer (API): when a provider gives no verdict on a card charge, the transaction stays pending without cascading while Tokeflow establishes the outcome, and its checkout session is settled when the final status arrives. More provider failures are now recognized as "no answer" instead of declines.
• Refused connector credentials (API): a renewal routed to a connector whose credentials the provider confirms it refuses is put on a billing hold instead of being dunned, and saving new credentials releases it. See Refused credentials.
• Inactive providers (API): a connector whose payment provider is inactive can be turned off, renamed or have its credentials rotated, but not turned back on.
• gateway_fee (API): now the fee as reported by the provider, filled in later when the provider reports it after the charge.
• Overridable merchant settings (API): network_tokens_enabled and saved_card_checkout_enabled are the merchant's own choice; Tokeflow can set either for an organization or a merchant, and that setting wins. See Settings Tokeflow can override.

Fixed

• Subscription billing dates (API): monthly and longer cycles no longer skip a month when the anchor day is the 29th–31st; the renewal falls on the month's last day. current_period_end now always equals the anchored renewal date, and a plan change keeps the existing anchor. See Billing dates.

---

2026-09-24 — One-click charges, two new providers, installments per connector

Saved cards can now be charged again with a single click, cards can be saved during a one-time purchase, and two payment providers join the catalog. All changes are backward compatible.

Added

REST API v1 (API)

• One-click stored-credential charges — credential_on_file: true on POST /transactions charges a saved payment_instrument_id with the provider credential kept at enrollment: no card data, no CVV, no checkout session. The charge is pinned to the connector that holds the credential, is always captured, and is recorded as a customer-initiated, unscheduled order. Read the guide: One-click upsells & downsells.
• Save a card while charging — save_payment_instrument: true on POST /transactions enrolls the card behind card_ciphertext_id as a payment instrument before the charge and keeps the provider's reusable credential for later one-click charges. Requires a ciphertext minted with purpose=instrument_enrollment.
• payer_ip on POST /transactions — the payer's IP address, required by some providers on card charges. Falls back to the IP of the payer's Bridge SDK session when the charge belongs to a checkout session.
• Two new payment providers in the catalog, both supporting stored-credential (one-click) charges. Availability is enabled per organization — contact the Tokeflow team for the current list; credential patterns and webhook rules are on Payment providers and Connectors.
• Installments per connector — the provider catalog now exposes installment_config (the range each provider supports per payment method), and a connector's config.installments_enabled chooses within it: unset accepts API-requested installments without offering them at checkout, true also offers them at checkout, false refuses them. See Connector config.
• Provider catalog fields — default_supported_card_brands and supported_currencies on the payment provider object.
• Network-token opt-in — network_tokens_enabled on the merchant object and on PATCH /merchants/:id. Provisioning is now an explicit per-merchant choice, off by default; merchants already using network tokens were opted in automatically.

Bridge SDK 2.6.0 and 2.7.0 (SDK)

• saveCard and purpose on TokenizeOptions — a browser integration can now mint an enrollable ciphertext: saveCard: true inside a checkout session for a one-time offer, or purpose: 'instrument_enrollment' for standalone tokenization. The returned CardToken echoes the purpose the server actually minted, and TokenPurpose is exported. See Tokenization → Options.
• savedCardCheckoutEnabled and SavedInstrument.reusable on the checkout context — reserved for saved-card checkout, which is rolling out; both read false until it is enabled for your merchant.

Changed

• Charging a saved card (API): payment_instrument_id on its own is now refused with 400. Send it with credential_on_file: true (one-click) or with a fresh card_ciphertext_id (re-typed CVV). See Card sources.
• POST /tokens (API): documented how the token purpose is decided — inside a checkout session the server derives it from the offer and save_card and ignores a client-supplied purpose; standalone tokenization keeps it.
• Connectors (API): has_webhook_secret is true for providers that sign webhooks with a key already in credentials; unknown credentials keys are refused; a key whose environment does not match is_test_mode is rejected.

Fixed

• The POST /merchants/:merchant_id/payment-instruments example sent an IP address as card_ciphertext_id; it now shows a tok_… reference.
• Example encrypted-card values on POST /tokens no longer show a raw ciphertext format.

---

2026-09-04 — Subscription reactivation and billing clarity

New subscription controls and clearer billing behavior across the REST API and the Dashboard. All changes are backward compatible.

Added

REST API v1 (API) and Dashboard

• Reactivate a subscription — a new endpoint that calls off a scheduled cancellation and keeps a live subscription on its plan, on both the public API and the merchant Dashboard. It is also the remedy when a customer tries to start a plan they already hold.
• Actor attribution on subscription transitions: admin-triggered changes now carry an actor snapshot of the dashboard user who performed them.
• Documented billing holds and the one live subscription per plan rule in the Subscriptions lifecycle.

Changed

• Change offer (API): after a plan change, billing_cycle now re-syncs to the new offer's cycle instead of keeping the previous value.
• Refunds (API): clarified that pending refunds count against the refundable balance, and that a refund with no definitive provider result stays in doubt — the transaction remains refund_pending — rather than being released.
• Webhooks (API): documented the full retry window — an endpoint that fails every attempt is retried across roughly 26 hours before the delivery is abandoned — and that each delivery is timestamped when it settles.

---

2026-08-13 — Expanded API reference

A broad documentation update covering more of the /api/v1 surface, plus a new Dashboards section for the session-authenticated Dashboard and Customer Portal endpoints. No behavior changed — this release documents endpoints that were already live.

Added

REST API v1 (API)

• Merchants (mrc_) — manage merchants and their team members within an organization.
• API Keys (ak_) — create, list, inspect scopes for, and revoke API keys programmatically.
• Webhook Endpoints — register endpoints, inspect deliveries, and rotate signing secrets over the API.
• Sessions & Tokens (tok_) — the server-side session and tokenization endpoints behind the Bridge SDK.
• Connectors (conn_) and Routing Profiles — connect payment providers and define smart-routing rules and fallback order.
• Payment Providers, Audit Logs, and Health.
• New endpoints on existing resources: delete a customer, create a payment instrument, and administratively cancel a subscription.

Dashboards (API)

• Documented the session-authenticated Merchant Dashboard, Organization Dashboard, and Customer Portal endpoints — the surfaces behind the Tokeflow Dashboard and the self-service customer portal. These authenticate with a Dashboard session (JWT bearer) or a portal magic-link session, not with sk_/pk_ API keys.

Changed

• The API reference overview resource-group list now includes the newly documented resources.

2026-06-23 — Public API v1 & Bridge SDK

The first public release of the Tokeflow platform: a stable, versioned REST API and a client-side SDK for collecting payment data in the browser. Everything in this reference is generally available as of this release.

Added

REST API v1 (API)

The full /api/v1 surface is live at https://api.tokeflow.com. One consistent envelope, one set of conventions, across every payment provider you connect.

• Customers (cust_) — create and manage payers, including documents (cpf, cnpj, passport, tax_id) and contact details.
• Checkout Sessions (cks_) — hosted and embedded checkout flows with line items, customer identification, and a streamed event timeline.
• Transactions (tx_) — create, retrieve, capture, and void payments across credit_card, debit_card, pix, boleto, and wallet methods.
• Refunds (ref_) — full or partial refunds against captured transactions.
• Orders (ord_) — order records that group transactions across API, checkout, and renewal flows.
• Subscriptions (sub_) — recurring billing with lifecycle, dunning, pause/resume, and offer changes.
• Payment Instruments (pi_) — saved payment methods on file for merchant-initiated and repeat charges.
• Catalog — product families (pfa_), products (prd_), offers (ofr_), offer prices (opr_), and offer transitions (oft_).

Authentication & key scoping (API)

• Organization and Merchant API keys. Every key is scoped to exactly one entity. A Merchant key infers its merchant automatically; an Organization key spans every merchant in the org and targets one with the merchant_id parameter. See Authentication.
• Secret and public keys. Secret keys (sk_…) authorize server-to-server calls; public keys (pk_…) are restricted to client-safe scopes and are safe to ship in browser code. Permissions follow a resource:action model. See Environments and keys.

Platform conventions (API)

• Idempotency. Send an Idempotency-Key header (or idempotency_key body field) on create and charge mutations — notably POST /transactions — and replays return the original result instead of duplicating. See Idempotency and rate limits.
• Webhooks with signed delivery. Normalized, provider-agnostic event notifications, each signed with an X-Tokeflow-Signature header (HMAC-SHA256) so you can verify authenticity before acting. See Webhooks.
• Standard envelopes, errors, and pagination. A consistent success/data/meta envelope, a stable machine-readable error catalog, and page-based pagination across every list endpoint. See the API reference overview.

Bridge SDK (SDK)

The @tokeflow_com/bridge-js Bridge SDK collects sensitive payment data in the browser and exchanges it for a short-lived token reference (tok_…) — card data is encrypted in the browser and never touches your servers. See the Bridge SDK overview.

• Card collection with prebuilt, themeable secure elements. See Elements and Tokenization.
• PIX, Apple Pay, and Google Pay — every enabled method produces the same kind of token reference. See Payment methods.
• Checkout context — read the priced items, selected currency, enabled methods, and saved instruments from an open checkout session. See Checkout.
• Localization — built-in en and pt-BR packs with per-element string overrides. See Localization.
• React bindings — first-class provider, hooks, and element components. See React.
• Public-key auth — the SDK authenticates with a publishable key only; secret keys stay on your server.

Release at a glance

Next steps

• Quickstart — an end-to-end payment.
• API reference overview — base URL, auth, envelopes, and conventions.
• Bridge SDK overview — collect and tokenize payment data in the browser.
• Webhooks — receive and verify signed events.