Início rápido

Este guia leva você do zero à primeira cobrança aprovada em poucos minutos. Para contexto sobre o que é a Toktus, comece pelo Bem-vindo à Toktus.

Gateways suportados

A Toktus API roteia cobranças para cinco gateways diferentes. Cada um tem suas particularidades, detalhadas em páginas próprias na categoria Gateways.

Stripe —

Gateway internacional. Cobranças em mais de 135 moedas.
Pagar.me —

Gateway brasileiro com cartão, boleto, PIX e split nativo.
Asaas —

Especializado em boletos e cobranças recorrentes.
Mercado Pago —

Maior gateway da América Latina, forte presença no Brasil.
PagSeguro —

PagBank — gateway brasileiro tradicional.

Como funciona

Em vez de implementar cinco SDKs diferentes, você integra uma única API REST padronizada:

// Em vez de cinco implementações distintas:
// stripe.customers.create(...)
// pagarme.customers.create(...)
// asaas.customers.create(...)
// mercadopago.customers.create(...)
// pagseguro.customers.create(...)

// Você usa uma única chamada:
await fetch('https://api.toktus.com/api/v1/customers', {
  method: 'POST',
  headers: { 'x-api-key': 'tk_sua_chave' },
  body: JSON.stringify({
    gateway: 'stripe', // ou 'pagarme', 'asaas', etc
    name: 'João Silva',
    email: '[email protected]'
  })
});

Quatro etapas até a primeira cobrança

1. Obter sua API Key

A criação de conta acontece no painel da Toktus, não pela API.

Cadastre-se em app.toktus.com

Faça signup com e-mail em app.toktus.com e confirme via link recebido na sua caixa de entrada.
Gere sua API Key

No painel, vá em Configurações → API e clique em Gerar nova chave. A chave (formato tk_...) é exibida uma única vez — armazene em local seguro.

Detalhes completos sobre como usar a chave em cada request: Autenticação.

2. Cadastrar credenciais do gateway

Conecte o gateway que você quer usar. Cada um tem campos próprios — abaixo um exemplo com Stripe:

curl -X POST https://api.toktus.com/api/v1/credentials \
  -H "x-api-key: tk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "credentials": {
      "secretKey": "sk_test_51Abc..."
    }
  }'

Para os outros gateways (Pagar.me, Asaas, Mercado Pago, PagSeguro), veja Credenciais dos gateways ou a página específica de cada um na categoria Gateways.

3. Cadastrar o cliente final

curl -X POST https://api.toktus.com/api/v1/customers \
  -H "x-api-key: tk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "name": "João Silva",
    "email": "[email protected]",
    "document": "12345678900"
  }'

A resposta inclui o externalId do cliente no gateway escolhido — use esse ID nas próximas cobranças.

[!WARNING]
Asaas exige cadastro prévio de cliente antes de qualquer cobrança. Em outros gateways o cliente pode ser criado junto da cobrança no mesmo payload.

4. Criar a cobrança

curl -X POST https://api.toktus.com/api/v1/charges \
  -H "x-api-key: tk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "paymentMethod": "credit_card",
    "amount": 10000,
    "customerId": "cus_abc123",
    "creditCard": {
      "paymentMethodId": "pm_1Abc2Def3Ghi"
    }
  }'

[!NOTE]
Valores trafegam sempre em centavos. R$ 100,00 = 10000.

[!WARNING]
Stripe não aceita dados brutos de cartão (número, CVV) por restrição de PCI DSS. Você precisa tokenizar com Stripe.js no frontend e enviar o paymentMethodId ou token resultante. Detalhes em Gateway Stripe.

Próximos passos

Autenticação — Como obter e usar sua API Key
Credenciais — Cadastrar gateways de pagamento
Configurações da conta — Gateway padrão, fallbacks e modo de compatibilidade
Webhooks — Receber notificações em tempo real