Credenciais dos gateways

A Toktus não processa pagamentos diretamente. Ela funciona como um roteador unificado que repassa cada cobrança para o gateway de pagamento da sua escolha (Stripe, Pagar.me, Asaas, Mercado Pago ou PagSeguro), usando as credenciais que você cadastra para sua conta.

Este documento explica:

• Como o armazenamento das credenciais funciona
• Pré-requisitos de cada gateway antes de obter as chaves
• Onde encontrar cada chave dentro do painel oficial
• Quais campos a Toktus espera e em que formato
• Como configurar webhooks para receber atualizações de status
• Cartões e dados de teste para validar sua integração
• Limites, requisitos de verificação e armadilhas comuns

Como funciona

graph LR
    A[Painel do gateway] -->|você copia as chaves| B[POST /v1/credentials]
    B --> C[Toktus criptografa AES-256-GCM]
    C --> D[(Postgres)]
    E[Sua aplicação] -->|POST /v1/charges| F[Toktus decifra em memória]
    F --> G[Repassa ao gateway]

As chaves nunca trafegam ou são armazenadas em texto claro depois do cadastro.

Armazenamento e segurança

A ENCRYPTION_KEY é exclusiva por deployment. Se ela for trocada, todas as credenciais ficam inacessíveis até serem recadastradas.

Antes de começar

Para usar o endpoint de credenciais você precisa:

1. Ter uma API key do Toktus

   Cadastrada via signup no dashboard. A chave tem o prefixo tk_ e é enviada no header Authorization: Bearer tk_... ou x-api-key.

2. Ter uma conta no gateway

   Cada gateway exige cadastro próprio, com aprovação de documentos e validação de CNPJ ou CPF. Os requisitos estão detalhados em cada aba abaixo.

3. Decidir o ambiente

   Toktus suporta os ambientes de teste (sandbox) e produção (live) de cada gateway. A diferenciação acontece via prefixo da chave (Stripe, Pagar.me, Mercado Pago) ou via flag sandbox (Asaas, PagSeguro).

Credenciais por gateway

Stripe

Pré-requisitos da conta

• Cadastro em stripe.com e ativação por e-mail
• Para produção: dados bancários, CNPJ ou CPF, verificação de identidade (KYC)
• Para sandbox: nenhum dado financeiro é exigido

Onde obter a Secret Key

1. Acesse o dashboard

   dashboard.stripe.com

2. Alterne o modo no topo direito

   O toggle Test mode controla se as próximas chaves serão de teste (sk_test_...) ou de produção (sk_live_...). Deixe-o ligado enquanto estiver desenvolvendo.

3. Vá em Developers → API keys

   Menu lateral esquerdo, opção Developers, depois aba API keys. URL direta: dashboard.stripe.com/apikeys.

4. Copie a Secret key

   Clique em Reveal test key (ou Reveal live key) e copie. Comece a usar imediatamente; a Stripe não exibe a chave secreta de novo.

Campos esperados pelo Toktus

O ambiente é inferido automaticamente do prefixo.

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "stripe",
    "credentials": {
      "secretKey": "sk_test_51Abc123XYZ..."
    }
  }'

Webhooks

Para receber atualizações de status (cobrança aprovada, estorno, falha em assinatura) configure um endpoint no painel da Stripe apontando para a Toktus:

1. Acesse Developers → Webhooks

   dashboard.stripe.com/webhooks

2. Add endpoint

   URL: https://api.toktus.com/webhooks/stripe/<seu-webhook-token>. O webhook-token está disponível em GET /v1/account.

3. Selecione os eventos

   Marque pelo menos: payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed.

4. Copie o Signing secret

   Após criar o endpoint, expanda-o e copie o Signing secret (whsec_...). Atualize sua credencial na Toktus enviando esse campo:

   JSON

   {
     "gateway": "stripe",
     "credentials": {
       "secretKey": "sk_live_...",
       "webhookSecret": "whsec_..."
     }
   }

   Sem o webhookSecret, a Toktus aceita o webhook mas não valida a assinatura. Use sempre em produção.

Cartões de teste

Lista completa: stripe.com/docs/testing.

Métodos suportados pela Toktus via Stripe

• Cartão de crédito e débito
• Stripe Connect (split entre destinatário único; ver account-gateway)
• Assinaturas recorrentes
• Estornos parciais e totais

PIX e boleto não são oferecidos pela Stripe no Brasil.

Armadilhas comuns

[!WARNING]
Não use a Publishable key (pk_test_...) no secretKey. A publishable é usada no frontend para tokenizar cartões; a Toktus precisa da secret para criar PaymentIntents.

[!NOTE]
A Stripe rejeita requests da Toktus com 401 se a chave estiver revogada ou se o modo (test/live) não bater com o ambiente da requisição.

Pagar.me

Pré-requisitos da conta

• Cadastro em pagar.me com aprovação comercial (CNPJ exigido para produção)
• Conta validada com dados bancários para liquidação
• Sandbox liberado imediatamente após o signup, sem aprovação

Onde obter a Secret Key

1. Acesse o dashboard

   dash.pagar.me

2. Selecione o ambiente

   No topo direito, alterne entre Sandbox e Live. Cada um tem suas próprias chaves.

3. Configurações → Chaves

   Menu superior Configurações, depois aba Chaves.

4. Copie a Secret Key

   Há duas chaves: Chave Pública (uso no frontend) e Chave Secreta (uso no servidor). Copie a Secreta — começa com sk_test_ ou sk_live_.

Campos esperados pelo Toktus

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "pagarme",
    "credentials": {
      "secretKey": "sk_test_Yxw789..."
    }
  }'

Webhooks (Postbacks)

1. Configurações → Postbacks

   Aba Postbacks no painel.

2. URL do endpoint

   https://api.toktus.com/webhooks/pagarme/<seu-webhook-token>

3. Eventos

   Marque pelo menos transaction_status_changed e subscription_status_changed.

A Pagar.me v5 assina os postbacks com um HMAC-SHA256. A Toktus valida automaticamente usando a secretKey cadastrada — não precisa enviar um campo separado.

Cartões de teste

Use qualquer validade futura. Para erros específicos, varie o valor: cobranças com final 00 em centavos são aprovadas; finais 01, 02, etc disparam diferentes recusas.

Métodos suportados pela Toktus via Pagar.me

• Cartão de crédito (com tokenização via frontend)
• PIX (com QR Code e copia e cola)
• Boleto
• Assinaturas com cobrança recorrente
• Split de pagamentos entre recebedores

Armadilhas comuns

[!WARNING]
A v5 da Pagar.me usa centavos como unidade (assim como a Toktus internamente). Não envie valores como decimais — R$ 10,00 é 1000.

[!NOTE]
Para PIX, o QR Code expira em 30 minutos por padrão. Configure o campo expiresIn se precisar de um prazo diferente.

Asaas

Pré-requisitos da conta

• Cadastro em asaas.com (produção) ou sandbox.asaas.com (testes)
• Sandbox: liberado na hora, sem validação
• Produção: exige CNPJ ou CPF, comprovante de endereço, conta bancária válida

Onde obter a API Key

1. Faça login no painel correto

   Sandbox e produção têm logins separados. Use sandbox.asaas.com durante o desenvolvimento.

2. Menu lateral → Integrações

   No menu lateral, clique em Integrações. Em algumas versões da UI está em Minha Conta → Integrações.

3. Gerar nova chave

   Botão Gerar nova chave de API. Dê um nome descritivo (Toktus produção) e confirme.

4. Copie no momento

   A chave começa com $aact_ e tem cerca de 80 caracteres. O Asaas só exibe uma vez — se perder, gere outra e revogue a anterior.

Campos esperados pelo Toktus

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "asaas",
    "credentials": {
      "apiKey": "$aact_YTU5YTE0M2M2N2I4MTliNzk0YTI5N2U5MzJkaQ==",
      "sandbox": "true"
    }
  }'

Para produção:

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -d '{
    "gateway": "asaas",
    "credentials": {
      "apiKey": "$aact_PRODUCAO_AQUI",
      "sandbox": "false"
    }
  }'

Webhooks

O Asaas exige que o webhook seja configurado via API ou pelo painel:

1. No painel

   Configurações → Notificações → Webhooks.

2. URL

   https://api.toktus.com/webhooks/asaas/<seu-webhook-token>

3. Token de autenticação

   O Asaas envia um header asaas-access-token com um token que você define no painel. Adicione esse token na credencial:

   JSON

   {
     "gateway": "asaas",
     "credentials": {
       "apiKey": "$aact_...",
       "sandbox": "false",
       "webhookToken": "valor-definido-no-painel"
     }
   }

4. Eventos

   Marque os tipos PAYMENT_* (recebimento de boleto, PIX, cartão) e SUBSCRIPTION_* (ciclos de assinatura).

Métodos suportados pela Toktus via Asaas

• Boleto
• PIX
• Cartão de crédito
• Assinaturas
• Antecipação de recebíveis (configurável no painel do Asaas)

Armadilhas comuns

[!WARNING]
Cliente obrigatório. O Asaas exige cadastro prévio de cliente (POST /v1/customers) antes de criar qualquer cobrança. Outros gateways aceitam dados do pagador direto no payload da charge; o Asaas não. Veja Clientes & Assinaturas.

[!NOTE]
O Asaas sandbox tem rate limit menor que produção (cerca de 60 requisições por minuto). Em testes de carga, use a chave de produção real com valores pequenos.

[!WARNING]
Em sandbox, as confirmações de boleto/PIX são automáticas após alguns minutos. Em produção, dependem do cliente final pagar.

Mercado Pago

Pré-requisitos da conta

• Conta Mercado Pago verificada (mesma conta usada para pagamentos)
• Para produção: documento de identidade aprovado e conta bancária vinculada
• Cadastro como desenvolvedor: mercadopago.com.br/developers

Onde obter o Access Token

1. Acesse o painel de desenvolvedores

   mercadopago.com.br/developers/panel

2. Criar uma aplicação

   Clique em Criar aplicação. Preencha nome e selecione a categoria que melhor descreve seu produto (geralmente Online payments).

3. Credenciais

   Dentro da aplicação criada, clique em Credenciais no menu lateral.

4. Escolha o ambiente

   A página tem duas abas: Credenciais de teste e Credenciais de produção. Copie o Access Token da aba apropriada — formato TEST-... para sandbox ou APP_USR-... para produção.

Campos esperados pelo Toktus

Não envie sandbox — o ambiente é inferido do próprio token.

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "mercadopago",
    "credentials": {
      "accessToken": "APP_USR-1234567890-012345-abcdef1234567890-987654321"
    }
  }'

Webhooks (Notificações)

1. Dentro da aplicação

   Painel de desenvolvedores → sua aplicação → Webhooks.

2. URL

   https://api.toktus.com/webhooks/mercadopago/<seu-webhook-token>

3. Eventos

   Marque payment, subscription_preapproval e subscription_authorized_payment.

4. Secret

   Após salvar, copie o Secret da aplicação e adicione na credencial:

   JSON

   {
     "gateway": "mercadopago",
     "credentials": {
       "accessToken": "APP_USR-...",
       "webhookSecret": "..."
     }
   }

Cartões e dados de teste

O Mercado Pago só aceita cartões de teste se você usar uma conta de teste (criada em Suas integrações → Contas de teste). Não funciona com sua conta principal mesmo em sandbox.

O nome do titular controla o status — use APRO para aprovar, OTHE para recusar.

Métodos suportados pela Toktus via Mercado Pago

• Cartão de crédito (com tokenização obrigatória via MercadoPago.js v2)
• PIX
• Boleto (no Brasil)
• Assinaturas (preapproval)

Armadilhas comuns

[!WARNING]
Tokenização obrigatória de cartão. O Mercado Pago não aceita dados brutos de cartão (número, CVV, validade) na API. Você precisa tokenizar via MercadoPago.js v2 no frontend e enviar o token para a Toktus. Requests com cartão raw retornam HTTP 422.

[!WARNING]
E-mail obrigatório em assinaturas. Diferente dos outros gateways, o Mercado Pago exige o e-mail do assinante (mesmo que o cliente já esteja cadastrado).

[!NOTE]
Em produção, o Mercado Pago aplica análise antifraude automática. Cobranças podem ficar como in_process por horas antes da decisão final — sua aplicação deve tratar esse estado intermediário.

PagSeguro (PagBank)

Pré-requisitos da conta

• Conta PagBank verificada com CNPJ ou CPF
• Para produção: dados bancários e documentos aprovados
• Sandbox: cadastro em sandbox.pagseguro.uol.com.br com mesma estrutura

Onde obter o Token

1. Acesse o painel

   minhaconta.pagseguro.uol.com.br ou pagbank.com.br.

2. Vá em Integrações

   Menu lateral Vendas → Integrações. Em contas mais novas pode estar em Mais → Integrações.

3. Token de Segurança

   Clique em Gerar Token. Se já houver um, será exibido — o PagSeguro permite ter apenas um token ativo por vez (gerar novo invalida o anterior).

4. Copie e armazene com segurança

   O token tem 40 caracteres alfanuméricos. Não é mostrado de novo após sair da tela.

Campos esperados pelo Toktus

Cadastrando

curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "pagseguro",
    "credentials": {
      "token": "A1B2C3D4E5F6789012345678901234567890ABCD",
      "sandbox": "true"
    }
  }'

Webhooks (Notificações)

O PagSeguro envia notificações HTTP POST automaticamente para a URL cadastrada:

1. No painel

   Integrações → Notificações.

2. URL

   https://api.toktus.com/webhooks/pagseguro/<seu-webhook-token>

3. Validação

   O PagSeguro envia um notificationCode no body. A Toktus consulta o status via API usando esse código e seu token cadastrado.

Cartões de teste

Para forçar status específicos no sandbox, o PagSeguro usa o valor da cobrança como gatilho — consulte a documentação oficial para a tabela atual.

Métodos suportados pela Toktus via PagSeguro

• Cartão de crédito (com tokenização via PagSeguro.js)
• PIX
• Boleto
• Assinaturas recorrentes (endpoint separado sandbox.api.assinaturas.pagseguro.com)

Armadilhas comuns

[!WARNING]
Assinaturas usam URL diferente. O endpoint de assinaturas (/recurring/plans) roda em api.assinaturas.pagseguro.com, não no domínio principal. A Toktus gerencia isso internamente, mas se você consultar a API do PagSeguro fora dela, atente-se.

[!NOTE]
O PagSeguro está migrando produtos para a marca PagBank. URLs antigas com pagseguro.uol.com.br ainda funcionam, mas alguns recursos novos só existem em pagbank.com.br.

Cadastrar várias credenciais

Cada cliente Toktus pode ter credenciais ativas em múltiplos gateways simultaneamente. Basta repetir o POST trocando o gateway:

# Stripe
curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_..." \
  -d '{"gateway":"stripe","credentials":{"secretKey":"sk_live_..."}}'

# Pagar.me
curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_..." \
  -d '{"gateway":"pagarme","credentials":{"secretKey":"sk_live_..."}}'

# Asaas
curl -X POST https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_..." \
  -d '{"gateway":"asaas","credentials":{"apiKey":"$aact_...","sandbox":"false"}}'

Use o campo primaryGateway em PATCH /v1/account para definir qual gateway recebe cobranças por padrão quando o campo gateway é omitido no payload.

Upsert (cadastrar ou atualizar)

O endpoint POST /v1/credentials é idempotente por (cliente, gateway):

• Primeira chamada: cria o registro
• Chamadas subsequentes para o mesmo gateway: atualiza as credenciais e retorna updated: true

{
  "success": true,
  "data": {
    "id": "cred_2H8jJ...",
    "gateway": "stripe",
    "updated": true
  }
}

A versão anterior é preservada como soft-deleted no banco (isActive: false), o que mantém referência para estornos de cobranças antigas que foram processadas pela credencial antiga.

Listar credenciais cadastradas

curl https://api.toktus.com/v1/credentials \
  -H "Authorization: Bearer tk_sua_api_key"

{
  "success": true,
  "data": [
    {
      "id": "cred_2H8jJ...",
      "gateway": "stripe",
      "isActive": true,
      "webhookVerifiedAt": "2026-04-12T18:23:45Z",
      "createdAt": "2026-04-01T10:00:00Z"
    },
    {
      "id": "cred_3K9pL...",
      "gateway": "asaas",
      "isActive": true,
      "webhookVerifiedAt": null,
      "createdAt": "2026-04-15T11:30:00Z"
    }
  ]
}

[!NOTE]
As chaves secretas nunca são retornadas. Os endpoints de listagem só expõem metadados.

O campo webhookVerifiedAt indica quando a Toktus recebeu o primeiro webhook válido do gateway — útil para confirmar que a configuração de notificações está funcionando.

Validar credenciais antes de cadastrar

O endpoint POST /v1/credentials/test valida a credencial fazendo uma chamada real ao gateway sem salvar:

curl -X POST https://api.toktus.com/v1/credentials/test \
  -H "Authorization: Bearer tk_..." \
  -d '{
    "gateway": "stripe",
    "credentials": {"secretKey": "sk_test_..."}
  }'

Resposta:

{
  "success": true,
  "data": {
    "valid": true,
    "gateway": "stripe",
    "accountInfo": {
      "country": "BR",
      "currency": "brl"
    }
  }
}

Use isso no seu fluxo de onboarding para dar feedback imediato ao usuário.

Remover credenciais

curl -X DELETE https://api.toktus.com/v1/credentials/stripe \
  -H "Authorization: Bearer tk_sua_api_key"

[!WARNING]
A remoção é soft (marca isActive: false). Cobranças e assinaturas existentes continuam funcionando até o gateway estornar ou cancelar; novas cobranças retornam MISSING_CREDENTIALS.

Erros

401 GATEWAY_AUTH_ERROR

{
  "success": false,
  "error": {
    "code": "GATEWAY_AUTH_ERROR",
    "message": "Credenciais do gateway inválidas ou expiradas.",
    "gateway": "stripe"
  }
}

Causas possíveis:

• Secret key incorreta ou com typo
• Token revogado no painel do gateway
• Ambiente errado (chave de teste tentando processar cobrança real)
• Credencial Asaas/PagSeguro sem flag sandbox correta

Use POST /v1/credentials/test para isolar o problema.

400 MISSING_CREDENTIALS

{
  "success": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Credenciais do gateway 'stripe' não cadastradas."
  }
}

Cadastre as credenciais antes de tentar operar no gateway.

422 INVALID_CREDENTIAL_FORMAT

Você enviou um campo com nome ou formato errado. Exemplos:

• Para Stripe: enviou apiKey em vez de secretKey
• Para Asaas: omitiu apiKey e enviou só token
• Para PagSeguro: enviou o token sem a flag sandbox

Consulte a tabela de campos esperados em cada aba acima.

Tabela resumo

Próximos passos

• Configurar webhooks — Receber atualizações de status em tempo real.
• Clientes e assinaturas — Cadastrar pagadores e criar cobranças recorrentes.
• Tratamento de erros — Conhecer todos os códigos de erro da API.