Visão Geral

Visão geral das configurações

Você pode configurar uma ou todas em uma única chamada. Os campos são independentes entre si — exceto compatibilityMode e responseFormat, conforme observado mais adiante.

Gateway primário (primaryGateway)

O problema que resolve

Sem configuração, cada chamada precisa repetir o campo gateway:

{ "gateway": "pagarme", "paymentMethod": "pix", "amount": 10000 }

Com primaryGateway configurado, o campo se torna opcional:

{ "paymentMethod": "pix", "amount": 10000 }

A Toktus infere o gateway a partir da sua conta. Útil quando 95% das suas cobranças vão pro mesmo provedor — só os 5% restantes precisam de override explícito.

Configurando

curl -X PATCH https://api.toktus.com/v1/clients/settings \
  -H "Authorization: Bearer tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "pagarme",
    "gatewayFallbacks": ["asaas", "stripe"]
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "primaryGateway": "pagarme",
    "gatewayFallbacks": "[\"asaas\",\"stripe\"]",
    "responseFormat": "full",
    "compatibilityMode": null
  }
}

Como a Toktus decide qual gateway usar

flowchart TD
    A([Requisição recebida]) --> B{Campo 'gateway'<br/>no payload?}
    B -->|Sim| C[Usa o gateway do payload]
    B -->|Não| D{primaryGateway<br/>configurado?}
    D -->|Sim| E[Usa o primaryGateway]
    D -->|Não| F[Erro 400<br/>Gateway não configurado]
    C --> G([Processa a cobrança])
    E --> G

    style F fill:#fca5a5,stroke:#ef4444,color:#7f1d1d
    style G fill:#bbf7d0,stroke:#16a34a,color:#14532d

Resumindo: o payload tem precedência sobre a configuração da conta. Você sempre pode forçar um gateway específico em uma chamada individual.

Override em uma requisição específica

Mesmo com primaryGateway configurado, basta enviar o campo gateway no payload:

{ "gateway": "stripe", "paymentMethod": "credit_card", "amount": 5000 }

Casos comuns de override:

• Testes pontuais em outro gateway antes de mudar o padrão
• Cobranças internacionais que precisam ir pra Stripe enquanto o padrão é brasileiro
• Migração gradual de endpoints

Fallback automático

A lista gatewayFallbacks é tentada em ordem se o primário falhar. Exemplo: você configurou primaryGateway: "pagarme" e gatewayFallbacks: ["asaas", "stripe"]. Se a Pagar.me devolver timeout, a Toktus tenta Asaas. Se Asaas também falhar, tenta Stripe.

A resposta inclui headers que indicam o que aconteceu (ver seção Headers de rastreabilidade abaixo).

🚧

O fallback só é acionado em falhas infraestruturais (timeout, 5xx, indisponibilidade). Recusas comerciais (cartão sem saldo, antifraude, validação de CPF) não disparam fallback — são respostas legítimas do gateway primário.

Campos disponíveis em PATCH /v1/clients/settings

Modo de compatibilidade (compatibilityMode)

O problema que resolve

Migrar para a Toktus a partir de um gateway direto envolve, em geral, duas mudanças trabalhosas:

1. Reescrever o payload — cada gateway nomeia os campos de forma diferente (order.amount vs transaction_amount vs valor, por exemplo)
2. Reescrever o parsing da resposta — a estrutura do JSON de retorno também varia

Com compatibilityMode, nenhuma das duas mudanças é necessária. A Toktus converte automaticamente nos dois sentidos:

Payload no formato Pagar.me → [ Toktus ] → Resposta no formato Pagar.me

Você muda só a URL base e a autenticação. Resto continua igual.

Para quem é

• Migrações de outros gateways: você já tem um sistema rodando com Pagar.me, Stripe ou Mercado Pago e quer começar a usar a Toktus sem tocar no código
• Multi-gateway sem refactor: mantém o formato familiar do seu time e a Toktus cuida da diversidade interna
• POCs e testes A/B: compara performance entre gateways sem reescrever o cliente

Gateways suportados

Configurando

curl -X PATCH https://api.toktus.com/v1/clients/settings \
  -H "Authorization: Bearer tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "asaas",
    "gatewayFallbacks": ["stripe"],
    "compatibilityMode": "pagarme"
  }'

Com essa configuração, sua aplicação envia payloads no formato Pagar.me, a Toktus processa via Asaas (com fallback pra Stripe) e devolve respostas no formato Pagar.me. Seu código nem percebe a troca.

Fluxo completo com fallback ativo

sequenceDiagram
    participant C as Seu sistema
    participant T as Toktus
    participant P as Pagar.me (primário)
    participant A as Asaas (fallback)

    C->>T: POST /charges<br/>(payload formato Pagar.me)
    Note over T: Inbound: Pagar.me → normalizado
    T->>P: Tenta processar
    P-->>T: Timeout / 5xx
    Note over T: Fallback acionado
    T->>A: Processa com credenciais Asaas
    A-->>T: Aprovado
    Note over T: Outbound: normalizado → Pagar.me
    T-->>C: Response formato Pagar.me<br/>+ Headers X-Toktus-*

Como a transformação acontece internamente

flowchart LR
    subgraph Inbound
        A[Payload Pagar.me] --> B[Transform<br/>inbound]
        B --> C[Payload<br/>normalizado]
    end

    subgraph Processamento
        C --> D{Gateway<br/>primário OK?}
        D -->|Sim| E[Processa]
        D -->|Não| F[Fallback]
        F --> E
    end

    subgraph Outbound
        E --> G[Resposta<br/>normalizada]
        G --> H[Transform<br/>outbound]
        H --> I[Response Pagar.me<br/>+ Headers X-Toktus-*]
    end

    style A fill:#fef9c3,stroke:#ca8a04,color:#713f12
    style I fill:#fef9c3,stroke:#ca8a04,color:#713f12
    style E fill:#bbf7d0,stroke:#16a34a,color:#14532d

Headers de rastreabilidade

Independente do compatibilityMode, toda resposta inclui headers que identificam exatamente o que aconteceu por trás da abstração:

[!TIP]
Armazene sempre o X-Toktus-Charge-Id junto da sua referência local. Esse é o ID que você usa em endpoints internos da Toktus (consultas, estornos via Toktus, logs) — mesmo quando o id no body é o ID externo do gateway.

Sobre o id no body em modo compatibilidade

Em compatibilityMode, o campo id na resposta contém o ID externo do gateway que processou (não o ID interno da Toktus). Isso garante compatibilidade com sistemas que já indexam pelo ID do gateway antigo.

Exemplo de cobrança em formato Pagar.me que caiu no fallback para Asaas:

Body:    { "id": "pay_Asaas123", ... }    ← ID do Asaas (gateway que processou)
Header:  X-Toktus-Charge-Id: ch-uuid       ← ID interno Toktus
Header:  X-Toktus-Gateway: asaas
Header:  X-Toktus-Fallback-Used: true

Se você precisa do ID interno da Toktus (por exemplo, para abrir um ticket de suporte ou correlacionar com seus próprios logs), leia sempre o header X-Toktus-Charge-Id.

Migração gradual com X-Payload-Format: native

Migração completa não é sempre desejável. Às vezes você quer rodar metade do tráfego no formato legado (Pagar.me) e a outra metade no formato normalizado da Toktus — por exemplo, durante uma reescrita gradual do seu backend.

O header X-Payload-Format: native força o formato normalizado em uma chamada específica, ignorando o compatibilityMode da conta:

# Conta tem compatibilityMode: "pagarme", mas esta chamada usa o formato normalizado
curl -X POST https://api.toktus.com/v1/charges \
  -H "Authorization: Bearer tk_SUA_CHAVE" \
  -H "X-Payload-Format: native" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "pix",
    "amount": 10000
  }'

Fluxo de decisão

flowchart TD
    A([Requisição]) --> B{Header<br/>X-Payload-Format: native?}
    B -->|Sim| C[Ignora compatibilityMode<br/>Usa formato normalizado]
    B -->|Não| D{compatibilityMode<br/>configurado?}
    D -->|Sim| E[Aplica transform do gateway]
    D -->|Não| F[Usa formato normalizado]
    C --> G([Processa])
    E --> G
    F --> G

    style C fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
    style E fill:#fef9c3,stroke:#ca8a04,color:#713f12
    style F fill:#bbf7d0,stroke:#16a34a,color:#14532d

Matriz de cenários

A estratégia recomendada para migração gradual:

1. Configure compatibilityMode com o gateway de origem — todo seu tráfego continua funcionando
2. Identifique os endpoints da sua aplicação que serão reescritos primeiro
3. Para cada endpoint reescrito, envie X-Payload-Format: native e use o formato normalizado
4. Quando 100% dos endpoints estiverem migrados, remova o compatibilityMode da conta

Resumo: configurar tudo de uma vez

curl -X PATCH https://api.toktus.com/v1/clients/settings \
  -H "Authorization: Bearer tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "pagarme",
    "gatewayFallbacks": ["asaas", "stripe"],
    "compatibilityMode": "pagarme",
    "responseFormat": "normalized"
  }'

[!WARNING]
compatibilityMode e responseFormat são mutuamente exclusivos na prática. Quando compatibilityMode está ativo, o responseFormat é ignorado — a resposta segue sempre o formato do gateway configurado. O responseFormat só tem efeito quando compatibilityMode é null.

Próximos passos

• Guia de migração — mapeamento de campos e status entre gateways. Leitura essencial antes de usar compatibilityMode.
• Coprodutores e split — divisão automática entre múltiplos recebedores
• Webhooks — notificações de eventos em tempo real
• API Reference — playground interativo de todos os endpoints