Configuração de Gateway da Conta

Por padrão, o Toktus API exige que você informe o gateway em cada requisição. Com a configuração de conta, você define isso uma única vez — e todas as chamadas seguintes ficam mais limpas e flexíveis.

Há duas configurações principais:

Ambas são configuradas via PATCH /api/v1/clients/settings — o mesmo endpoint acessível pelo dashboard.

Gateway Principal (primaryGateway)

O que resolve

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

// Toda chamada precisa informar o gateway
{ "gateway": "pagarme", "paymentMethod": "pix", "amount": 10000 }

Com primaryGateway configurado, o campo se torna opcional:

// Gateway inferido da conta automaticamente
{ "paymentMethod": "pix", "amount": 10000 }

Como configurar

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

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

Fluxo de seleção de gateway

flowchart TD
    A([Requisição recebida]) --> B{Campo 'gateway'\nno payload?}
    B -->|Sim| C[Usa o gateway do payload]
    B -->|Não| D{primaryGateway\nconfigurado na conta?}
    D -->|Sim| E[Usa o primaryGateway da conta]
    D -->|Não| F[Erro 400\nGateway não configurado]
    C --> G([Processa a cobrança])
    E --> G

    style F fill:#fca5a5,stroke:#ef4444
    style G fill:#bbf7d0,stroke:#16a34a

Override por requisição

Mesmo com primaryGateway configurado, você pode usar outro gateway em qualquer chamada específica:

// Esta chamada usa Stripe, ignorando o primaryGateway da conta
{ "gateway": "stripe", "paymentMethod": "credit_card", "amount": 5000 }

Isso é útil para:

• Testes pontuais em outro gateway
• Operações específicas que precisam de um gateway diferente
• Migração gradual de endpoints

Campos disponíveis no PATCH /settings

Modo de Compatibilidade (compatibilityMode)

O que resolve

Clientes migrando de um gateway direto para o Toktus API normalmente precisam:

1. Reescrever o payload de entrada (campos com nomes diferentes)
2. Reescrever o parsing da resposta (estrutura diferente)

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

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

Migração zero-código: você muda a URL base e a autenticação. Nada mais.

Gateways suportados

Como configurar

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

Com essa configuração, sua integração existente com a Pagar.me funciona no Toktus API sem nenhuma alteração de código.

Fluxo completo com fallback

sequenceDiagram
    participant C as Seu Sistema
    participant RG as Toktus API
    participant P as Pagar.me (primário)
    participant A as Asaas (fallback)

    C->>RG: POST /charges<br/>(payload no formato Pagar.me)
    Note over RG: Inbound: Pagar.me → normalizado
    RG->>P: Tenta processar
    P-->>RG: Falha
    Note over RG: Fallback acionado
    RG->>A: Processa com credenciais Asaas
    A-->>RG: Aprovado
    Note over RG: Outbound: normalizado → Pagar.me
    RG-->>C: Response (formato Pagar.me)<br/>Headers: X-RG-Gateway: asaas<br/>X-RG-Fallback-Used: true

Fluxo de transformação

flowchart LR
    subgraph Inbound
        A[Payload Pagar.me] --> B[Transform\nInbound]
        B --> C[Payload\nNormalizado]
    end

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

    subgraph Outbound
        E --> G[Resposta\nNormalizada]
        G --> H[Transform\nOutbound]
        H --> I[Response Pagar.me\n+ Headers X-RG-*]
    end

    style A fill:#fef9c3,stroke:#ca8a04
    style I fill:#fef9c3,stroke:#ca8a04
    style E fill:#bbf7d0,stroke:#16a34a

Headers de rastreabilidade

Toda resposta inclui headers que identificam o que aconteceu, independente do compatibilityMode:

[!NOTE]
O X-RG-Charge-Id é o ID interno do Toktus API. Armazene-o para cruzar com logs, mesmo quando compatibilityMode está ativo e o body retorna o ID externo do gateway.

Identificação do ID na resposta

Em compatibilityMode, o campo id na resposta contém o ID externo do gateway que processou (não o ID interno do Toktus API):

Exemplo com fallback para Asaas:

Body:    { "id": "pay_Asaas123", ... }  ← ID do Asaas
Header:  X-RG-Charge-Id: ch-rg-uuid     ← ID interno do Toktus API
Header:  X-RG-Gateway: asaas
Header:  X-RG-Fallback-Used: true

Isso garante que o id seja compatível com o formato que seu sistema já espera.

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

Se você quer migrar endpoint por endpoint ao invés de tudo de uma vez, use o header X-Payload-Format: native em chamadas específicas para forçar o formato normalizado independente do compatibilityMode da conta:

# Esta chamada usa o formato normalizado, mesmo com compatibilityMode: "pagarme" configurado
curl -X POST https://api.toktus.com/api/v1/charges \
  -H "x-api-key: tk_SUA_CHAVE" \
  -H "X-Payload-Format: native" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "pix",
    "amount": 10000
  }'

flowchart TD
    A([Requisição]) --> B{Header\nX-Payload-Format: native?}
    B -->|Sim| C[Ignora compatibilityMode\nUsa formato normalizado]
    B -->|Não| D{compatibilityMode\nconfigurado?}
    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
    style E fill:#fef9c3,stroke:#ca8a04
    style F fill:#bbf7d0,stroke:#16a34a

Resumo das configurações de conta

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

[!WARNING]
compatibilityMode e responseFormat são independentes. Quando compatibilityMode está ativo, o responseFormat é ignorado — a resposta segue o formato do gateway configurado. O responseFormat só se aplica quando compatibilityMode é null.

Próximos Passos

• Guia de Migração — Mapeamento de campos e status por gateway — essencial para usar o compatibilityMode
• Coprodutores e Split — Configure divisão de recebimento entre múltiplos beneficiários
• Webhooks — Receba notificações de pagamento em tempo real
• API Reference — Documentação completa de todos os endpoints