Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Authorization: Bearer trq_test_xxxxxxxxx
Exemplo: 
curl https://api.troqpay.com/v1/checkouts \
  -H "Authorization: Bearer trq_test_xxxxxxxxx"

​
URL-base

https://api.troqpay.com
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:
EstadoO que significa
NOT_REQUESTEDVocê ainda não pediu acesso à produção
PENDING_REVIEWVocê pediu, e o time da troqpay está analisando
APPROVEDVocê pode usar trq_live_ em todas as rotas suportadas
REJECTEDA troqpay rejeitou; veja o motivo no app
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, para você ler checkouts antigos.
Veja Produção para o caminho de aprovação.

​
Permissões da chave

Nem toda chave pode chamar todos os recursos. Por padrão, uma chave server-side permite criar/consultar checkouts e ler saldo conforme o ambiente dela. Para criar ou consultar saques pela API, a chave precisa ter permissão de saque.
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. 
Idempotency-Key: order_1001
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

HTTPCódigoO que normalmente significa
401unauthorizedChave ausente, mal formatada, inválida ou revogada. A API sempre devolve unauthorized em 401 — confira a message para o detalhe.
403forbiddenSua conta ainda não tem acesso a produção, ou a chave não tem permissão para o recurso.
403api_key_scope_forbiddenA chave não tem permissão para o recurso chamado.
403test_withdrawals_not_supportedSaques só estão disponíveis em produção.
429rate_limitedLimite de requisições excedido. Faça retry com backoff.

​
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.