Guia de início rápido

Este guia leva você do zero a um primeiro pagamento com a Tokeflow — a camada de orquestração por trás da sua plataforma. Você vai obter suas chaves de API, criar um cliente, abrir uma sessão de checkout, coletar dados do cartão no navegador, cobrá-lo no servidor e confirmar o resultado com um webhook.

A Tokeflow padroniza as operações de pagamento entre múltiplos provedores sob a sua própria marca. Os provedores de pagamento conectados fazem o processamento e a liquidação; a Tokeflow orquestra o roteamento, a resiliência e uma única API normalizada.

O fluxo em resumo

Passo 1 — Obtenha suas chaves de API

As chaves de API são emitidas no Dashboard da Tokeflow durante o onboarding. É lá que você provisiona merchants, registra URLs de webhook e gera chaves — não existe uma API pública para provisionamento.

Você vai trabalhar com dois tipos de chaves:

Cada chave tem escopo em exatamente uma entidade. Uma chave de Merchant (sk_live_mer_…) infere seu merchant automaticamente. Uma chave de Organization (sk_live_org_…) abrange todos os merchants da organização, então as chamadas com escopo de merchant precisam indicar o merchant de destino via merchant_id. Consulte Autenticação para a anatomia completa das chaves e seus escopos.

Passo 2 — Faça sua primeira requisição autenticada

Verifique sua chave secreta com uma leitura simples. Liste os clientes:

curl https://api.tokeflow.com/api/v1/customers?limit=1 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Toda resposta é encapsulada no envelope padrão. Uma lista retorna data como um array mais meta.pagination:

{
  "success": true,
  "data": [
    {
      "id": "cust_a1b2c3d4e5",
      "merchant_id": "mrc_a1b2c3d4e5",
      "email": "joao@example.com",
      "name": "Joao da Silva",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 1,
      "total": 42,
      "total_pages": 42,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c1a2b",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Se a chave estiver errada, você recebe o envelope de erro padrão com HTTP 401:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid.",
    "details": {},
    "request_id": "req_9a0b1c2d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Passo 3 — Crie um cliente

Crie o cliente que você está prestes a cobrar. Esta chamada é idempotente por e-mail: se o e-mail já existir, o registro existente é retornado com HTTP 200 em vez de 201.

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "document_type": "cpf",
    "document_number": "123.456.789-00"
  }'

Um recurso único omite meta:

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "created_at": "2026-01-15T12:00:00.000Z"
  },
  "request_id": "req_1f2e3d4c",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Passo 4 — Crie uma sessão de checkout

Uma sessão de checkout captura o que o cliente está comprando. Referencie uma oferta (uma configuração de preço vendável de um produto) e a Tokeflow deriva o valor e a moeda a partir dela — assim você nunca fixa preços diretamente na cobrança.

curl -X POST https://api.tokeflow.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "selected_currency": "BRL",
    "items": [
      { "offer_id": "ofr_a1b2c3d4e5", "quantity": 1, "installments": 1 }
    ]
  }'

{
  "success": true,
  "data": {
    "id": "cks_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "offer_id": "ofr_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "selected_currency": "BRL",
    "status": "initiated",
    "expires_at": null,
    "completed_at": null,
    "created_at": "2026-01-15T12:05:00.000Z",
    "updated_at": "2026-01-15T12:05:00.000Z"
  },
  "request_id": "req_2c3d4e5f",
  "timestamp": "2026-01-15T12:05:00.000Z"
}

Guarde o cks_a1b2c3d4e5 — você vai referenciá-lo quando fizer a cobrança no Passo 6.

Passo 5 — Colete o pagamento no navegador

Os dados do cartão nunca devem tocar seus servidores. O Bridge SDK executa os campos seguros da Tokeflow dentro de iframes isolados e de origem cruzada; os dados do cartão são criptografados no navegador e trocados por um token de uso único. Inicialize o SDK com sua chave pública e o id da sessão de checkout:

import { TokeflowBridge } from "@tokeflow_com/bridge-js";

const tokeflow = new TokeflowBridge({
  publicKey: "pk_live_mer_xxxxxxxxxxxxxxxx",
  checkoutSessionId: "cks_a1b2c3d4e5",
});
await tokeflow.init();

// Create and mount a secure card element, then tokenize on submit:
const cardElement = tokeflow.createCardElement();
cardElement.mount("#card-element");

const token = await tokeflow.cards.tokenize({ card: cardElement });
// token.tokenId => "tok_a1b2c3d4e5" — send this to YOUR server

Envie o token.tokenId (tok_…) resultante para o seu backend. Ele é de uso único e de vida curta.

Passo 6 — Cobre

Agora faça a cobrança no servidor. Referencie a sessão de checkout (o valor e a moeda vêm dela) e o token do SDK. Envie uma Idempotency-Key para que uma requisição repetida nunca cobre em dobro.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_2026_0115_attempt_1" \
  -d '{
    "checkout_session_id": "cks_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "capture": true,
    "card_ciphertext_id": "tok_a1b2c3d4e5"
  }'

A primeira submissão retorna HTTP 201; repetir a mesma Idempotency-Key retorna o resultado original com HTTP 200. Sempre leia o campo status — essa é a fonte da verdade sobre o desfecho.

{
  "success": true,
  "data": {
    "id": "tx_a1b2c3d4e5",
    "organization_id": "org_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "customer_id": "cust_a1b2c3d4e5",
    "amount_authorized": 9900,
    "amount_captured": 9900,
    "currency": "BRL",
    "payment_method": "credit_card",
    "charge_type": "payment",
    "country": "BR",
    "status": "authorized",
    "timeline": [
      {
        "attempt_number": 1,
        "is_fallback": false,
        "connector_id": "conn_a1b2c3",
        "provider_slug": "acquirer_a",
        "status": "success",
        "started_at": "2026-01-15T12:10:00.000Z",
        "finished_at": "2026-01-15T12:10:02.000Z"
      }
    ],
    "payment_instructions": null,
    "metadata": {},
    "created_at": "2026-01-15T12:10:00.000Z",
    "updated_at": "2026-01-15T12:10:02.000Z"
  },
  "request_id": "req_3d4e5f6a",
  "timestamp": "2026-01-15T12:10:02.000Z"
}

Valores de status de transação que você pode ver: pending, pre_authorized, authorized, capture_pending, failed, canceled, voided, refund_pending, refunded, partially_refunded, charged_back, expired. Para métodos assíncronos como pix e boleto, a resposta inclui payment_instructions (QR code ou código de barras) e o status começa em pending.

Passo 7 — Receba um webhook

Não é necessário fazer polling. Quando a transação chega a um estado terminal, a Tokeflow entrega um webhook normalizado ao endpoint que você registrou durante o onboarding — por exemplo transaction.authorized:

{
  "id": "evt_4e5f6a7b8c9d",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:10:02.000Z",
  "data": {
    "object": {
      "id": "tx_a1b2c3d4e5",
      "current_status": "authorized",
      "amount_captured": 9900,
      "currency": "BRL"
    }
  }
}

Cada entrega carrega um cabeçalho X-Tokeflow-Signature. Verifique-o contra o corpo bruto da requisição antes de confiar no payload e rejeite entregas cujo timestamp esteja fora da sua janela de tolerância. O código completo de verificação e o catálogo de eventos estão em Webhooks.

Você conseguiu

Uma única superfície de API, seus provedores por trás dela, sua marca por cima. A partir daqui:

• Autenticação — tipos de chave, escopos e o modelo org-vs-merchant em profundidade.
• Sessões de checkout — itens, seleção de moeda e eventos de ciclo de vida.
• Transações — captura, cancelamento, reembolso e leitura da timeline de tentativas.
• Bridge SDK — campos seguros, cartões salvos, carteiras e orquestração de 3DS.
• Webhooks — verificação de assinatura e a lista completa de eventos.