Skip to main content

​
Autenticação

Toda chamada para a API da TroqPay precisa de uma chave válida. Sem ela, a requisição não passa.
A chave identifica sua conta e também define se a requisição está em teste ou em produção.

​
O que você precisa saber

Bearer token

Toda requisição autenticada usa o header Authorization: Bearer ....

Mesmo endpoint para os dois ambientes

Você continua usando https://api.troqpay.com. O ambiente muda de acordo com a chave.

Chaves de teste

Use prefixo trq_test_ para homologação e validação do fluxo.

Chaves de produção

Use prefixo trq_live_ para cobranças reais.

​
Header obrigatório

Exemplo:

​
URL-base

Isso vale para teste e produção.

​
Acesso a produção

Chaves trq_live_ só funcionam quando sua conta está marcada como APPROVED para produção. Antes disso, chamadas de produção retornam 403 forbidden com uma mensagem relacionada ao recurso chamado. Os quatro estados possíveis da sua conta são:
O bloqueio se aplica a POST /v1/checkouts, GET /v1/balance e saques em produção. A consulta GET /v1/checkouts/{checkoutId} continua funcionando mesmo em contas que não estão APPROVED, desde que a chave tenha permissão de leitura de checkout.
Veja Produção para o caminho de aprovação.

​
Permissões da chave

Nem toda chave pode chamar todos os recursos. Uma chave server-side pode receber permissões separadas para: No fluxo comum, a chave de integração de checkout já vem com criação/leitura de checkout e leitura de saldo. Para criar ou consultar saques pela API, a chave precisa ter permissão de saque.
As permissões PAYMENT_LINK:CREATE e PAYMENT_LINK:READ são emitidas por padrão em toda chave nova (teste e produção). Chaves antigas, geradas antes dessas permissões existirem, não as têm e recebem 403 api_key_scope_forbidden nas rotas de payment-links até serem reemitidas.
Trate uma chave com permissão de saque como segredo de alto impacto. Ela deve ficar somente no backend e nunca em código de front-end, app mobile, logs públicos ou repositórios.

​
Idempotência

Quando você cria um checkout, mande também o header Idempotency-Key. Para criar um saque pela API, esse header é obrigatório.
A API normaliza o corpo da requisição com uma serialização JSON estável (chaves em ordem alfabética). Isso significa que reordenar campos no JSON conta como o mesmo corpo. Mudar, adicionar ou remover qualquer campo conta como um corpo diferente e vira 409 idempotency_conflict. Outros pontos importantes:
  • a chave não tem prazo de validade — ela fica associada ao recurso para sempre
  • a primeira criação devolve 201 Created. Uma reentrega idempotente (mesma chave, mesmo corpo) devolve 200 OK com o recurso já existente
  • em checkouts, a API trima o valor; uma string vazia depois do trim é tratada como se você não tivesse enviado a chave
  • em saques, não enviar uma chave válida retorna 400 idempotency_key_required
Use um identificador estável do seu sistema (ex.: order_1001, subscription_42_invoice_3) como Idempotency-Key. Isso evita colisões e dá deduplicação útil mesmo em janelas longas.

​
Request-Id

Toda resposta da API inclui o header Request-Id no formato req_<24 hex>. Você pode também enviar seu próprio identificador na requisição em Request-Id ou X-Request-Id. Quando você manda, a API ecoa o mesmo valor de volta. Quando você não manda, ela gera um. Use esse campo para correlacionar logs do seu sistema com o que aconteceu na TroqPay quando precisar abrir um suporte.

​
Boas práticas

  • guarde suas chaves em variáveis de ambiente
  • nunca exponha segredos no front-end
  • use chaves separadas para teste e produção
  • revogue a chave imediatamente em caso de suspeita de vazamento

​
Onde isso costuma ser configurado

No fluxo mais comum, você vai:
  1. gerar a chave no app.troqpay.com
  2. salvar o segredo no seu gerenciador de segredos
  3. usar a chave no backend
  4. manter teste e produção em variáveis separadas

​
Erros comuns

​
Próximos passos

​
Precisa de ajuda para seguir?

Fazer o Quickstart

Use uma trq_test_ para validar seu primeiro checkout sem depender de produção.

Revisar o sandbox

Confirme como separar os ambientes e o que observar nas respostas de teste.

Abrir o app

Gere ou revise suas chaves diretamente no app da TroqPay.