Developers

Built for teams who ship.

Tokeflow provides a clean, well-structured API for the full orchestration lifecycle — merchants, connectors, routing, transactions, webhooks, and operational queries. Predictable patterns, explicit versioning, no magic — just an API that does what it says.

Get in touchView Integrations →
curl
curl -X POST https://api.tokeflow.com/v1/payments \
  -H "Authorization: Bearer tkf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "currency": "BRL",
    "method": "credit_card",
    "merchant_id": "merch_abc123",
    "routing": {
      "profile_id": "rp_smart_brl",
      "fallback": true
    },
    "customer": {
      "id": "cust_xyz789"
    },
    "payment_method": {
      "token": "tok_card_..."
    }
  }'

An API you can reason about.

Consistent resources, safe retries, actionable errors, and stable versions — so integrations don’t rot when we ship features.

Predictable structure

Every resource follows the same pattern: create, retrieve, update, list. Request and response shapes stay consistent across endpoints.

Idempotent by default

Write operations support idempotency keys — retry safely without duplicate transactions, merchants, or webhook deliveries.

Meaningful errors

Machine-readable code, human message, and a details object pointing to the exact field and fix — not opaque 500s.

Versioned & stable

Versions live in the URL. Breaking changes ship in new versions — your integration won\u2019t break on a feature launch.

Developers

API surface

One authenticated, versioned API for onboarding through operations — same patterns everywhere.

Merchants

Create and manage merchants under your organization — independent credentials, routing profiles, and webhooks per merchant.

merchants.ts
const merchant = await tokeflow.merchants.create({)
  name: 'Acme Store',
  reference_id: 'acme-001'
});
  • POST /v1/merchants — Create
  • GET /v1/merchants/:id — Retrieve
  • PATCH /v1/merchants/:id — Update
  • GET /v1/merchants — List

Connectors

Attach PSP credentials to a merchant — supported methods, currencies, and 3DS flags per connection.

connectors.ts
const connector = await tokeflow.connectors.create({
  merchant_id: 'merch_abc123', provider: 'stripe' ... }
});
  • POST /v1/connectors, GET/PATCH/DELETE /v1/connectors/:id
  • GET /v1/merchants/:id/connectors — List for merchant

Routing profiles

Define cascade rules, soft-decline handling, and termination — executed automatically on each payment.

routing.ts
await tokeflow.routing_profiles.create({ rules: { ... } });
  • POST /v1/routing-profiles, GET /v1/routing-profiles/:id
  • PUT /v1/routing-profiles/:id — Replace profile
  • GET /v1/merchants/:id/routing-profiles — List

Payments

Create, capture, void, and refund. Routing and fallback run from the profile — with full trace on read.

payments.ts
await tokeflow.payments.create({ idempotency_key: 'order_12345' ... });
  • POST /v1/payments, POST .../capture|void|refund
  • GET /v1/payments/:id — Payment + routing trace
  • GET /v1/payments — Filtered list

Webhooks

Per-merchant endpoints, signed payloads, normalized event types, and delivery retry with backoff.

webhooks.ts
await tokeflow.webhooks.create({ events: ['payment.captured'] ... });
  • POST /v1/webhooks, GET/PATCH/DELETE /v1/webhooks/:id
  • GET /v1/webhooks/:id/deliveries — Delivery attempts

Operations & queries

Trace routing decisions, filter payments, and list normalized events for support and reconciliation.

trace.ts
const trace = await tokeflow.payments.getTrace('pay_x7k9m2...');
  • GET /v1/payments/:id/trace — Full routing trace
  • GET /v1/events, GET /v1/events/:id

Authentication & API keys

Every request uses a Bearer token. Keys are scoped to the organization with permissions for merchants and operations.

Authorization
Authorization: Bearer tkf_live_...
Key typePrefixScopeUse case
Live secrettkf_live_Full, productionServer-side only
Sandbox secrettkf_sandbox_Full, sandboxDev & staging
Publishabletkf_pub_Limited, client-safeSDK / tokenization

Secret keys must never ship in client-side code, mobile apps, or version control — use environment variables and a secret manager.

SDKs & integration packages

Thin wrappers around the REST API — no hidden logic. If you can read the API docs, you can read the SDK source.

Node.js / TypeScript

install
npm install @tokeflow/node
client.ts
import { Tokeflow } from '@tokeflow/node';
const tokeflow = new Tokeflow('tkf_live_...');

Python

install
pip install tokeflow
client.py
from tokeflow import Tokeflow
tokeflow = Tokeflow('tkf_live_...')

Go

install
go get github.com/tokeflow/tokeflow-go
client.go
client := tokeflow.NewClient("tkf_live_...")

cURL / HTTP

No SDK required. Use any HTTP client — examples in documentation include cURL equivalents.

Package names and onboarding materials are provided with sandbox provisioning.

Embeddable SDK (client-side)

Tokenize on the client. Process on the server. Card data stays out of your PCI scope.

Load the JS SDK, mount card fields in isolated iframes, and exchange a one-time token with your backend for payments.create. Works with React, Vue, or plain HTML — styling matches your brand.

  • Card data never touches your servers.
  • Single-use, time-limited tokens.
checkout.html
<script src="https://js.tokeflow.com/v1/tokeflow.js"></script>
<script>
  const tf = Tokeflow('tkf_pub_...');
  const card = tf.elements.create('card', { ... });
  card.mount('#card-container');
  const { token } = await tf.tokens.create(card);
</script>

Webhook verification

Verify signatures on every request. Respond with 2xx after processing so retries stay predictable.

server.ts
app.post('/webhooks/tokeflow', (req, res) => {
  const ok = Tokeflow.webhooks.verify({ ... });
  if (!ok) return res.status(401);
  // switch (req.body.type) { ... }
  res.status(200).send('OK');
});

Non-2xx responses trigger exponential backoff retries — respond 200 OK after you've safely handled the event.

Documentation

Full reference guides, OpenAPI exports, and interactive examples will live in the public docs portal. Until then, technical documentation ships with sandbox access and demo onboarding.

Coming soon

Request docs access

Ready to start building?

Get sandbox access, explore the API, and build your first integration. Our engineering team supports technical onboarding.

Get Sandbox AccessBook a Technical Demo

Prefer to browse integrations first? See supported providers.

Get Started

See Tokeflow inside your product.

Share a few details about your use case and we'll schedule a technical demo tailored to your stack. Sandbox access included.