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.

​
Saques

POST /v1/withdrawals cria uma solicitação de saque em produção. Saques pela API são uma operação sensível: use apenas no backend, com uma chave trq_live_ que tenha permissão de saque.
Saques estão disponíveis somente em produção. Use o ambiente de teste para validar checkouts, saldo, webhooks e tratamento de erros sem movimentar fundos reais.

​
Antes de chamar a API

Para criar um saque pela API, sua conta precisa atender a todos estes pontos:
  • conta aprovada para produção
  • telefone verificado
  • destino de saque cadastrado e aprovado para o trilho escolhido
  • saldo disponível suficiente em availableAmount
  • chave de API com permissão de saque
  • header Idempotency-Key enviado na criação
O destino do saque não é enviado no corpo da requisição. A API usa o destino já cadastrado e aprovado na sua conta.

​
Criar saque

curl https://api.troqpay.com/v1/withdrawals \
  -X POST \
  -H "Authorization: Bearer trq_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdrawal_1001" \
  -d '{
    "rail": "BRL_PIX",
    "amount": "100.00"
  }'
Campos do corpo:
CampoTipoObrigatórioDescrição
railstringSimTrilho do saque. Use BRL_PIX ou USDT_WALLET.
amountstring decimalSimValor bruto solicitado em BRL.
O retorno usa o mesmo recurso de saque para criação e consulta: 
{
  "id": "wd_4a8b3c1d5e6f2a9b0c1d",
  "livemode": true,
  "rail": "BRL_PIX",
  "currency": "BRL",
  "status": "REQUESTED",
  "requestedAmount": "100.00",
  "destination": {
    "summary": "Pix CPF • 1234...7890",
    "label": "Maria Silva"
  },
  "quote": {
    "sourceAmount": "100.00",
    "sourceCurrency": "BRL",
    "withdrawalFeeAmount": "2.99",
    "withdrawalFeeCurrency": "BRL",
    "netSourceAmount": "97.01",
    "netSourceCurrency": "BRL",
    "destinationAmount": "97.01",
    "destinationCurrency": "BRL",
    "quotedRateBrlPerUsdt": null,
    "quotedAt": null,
    "quoteSource": "BRL_PIX_TERMS_V1",
    "network": null,
    "feePolicyVersion": "v1",
    "monthlyWithdrawalCountAtRequest": 0,
    "appliedFeeTier": "STANDARD"
  },
  "requestedAt": "2026-05-09T12:00:00.000Z",
  "approvedAt": null,
  "processingAt": null,
  "completedAt": null,
  "failedAt": null,
  "cancelledAt": null,
  "failure": null
}

​
Tarifa do saque BRL

Cada saque em BRL via Pix tem uma tarifa que vem direto no quote da resposta. Você não precisa calcular nada. Por padrão, a tarifa é R2,99∗∗porsaque.Sevoce^fizermaisde20saquesnomesmome^s,apartirdo21ºovalorpassaaser∗∗R 2,99** por saque. Se você fizer mais de 20 saques no mesmo mês, a partir do 21º o valor passa a ser **R 3,50. O contador zera no início de cada mês, e saques recusados ou cancelados não contam. A tarifa fica travada no momento da criação do saque. Os campos relevantes na resposta são:
  • quote.withdrawalFeeAmount: o valor cobrado, em BRL
  • quote.appliedFeeTier: STANDARD para R2,99ou‘OVERTHRESHOLD‘paraR 2,99 ou `OVER_THRESHOLD` para R 3,50
Se você quiser acompanhar quantos saques já fez no mês, leia quote.monthlyWithdrawalCountAtRequest. É o contador imediatamente antes do saque atual.

​
Consultar saque

curl https://api.troqpay.com/v1/withdrawals/wd_4a8b3c1d5e6f2a9b0c1d \
  -H "Authorization: Bearer trq_live_xxxxxxxxx"

​
Idempotência

Idempotency-Key é obrigatório em POST /v1/withdrawals.
  • mesma chave e mesmo corpo retornam o mesmo saque
  • mesma chave com corpo diferente retorna 409 idempotency_conflict
  • use uma chave estável do seu sistema para a tentativa de saque, como withdrawal_1001

​
Erros comuns

HTTPcodeQuando aparece
400idempotency_key_requiredFalta o header Idempotency-Key.
403test_withdrawals_not_supportedA chave usada não é de produção.
403api_key_scope_forbiddenA chave não tem permissão de saque.
403withdrawal_readiness_requiredA conta ainda não completou a configuração necessária para sacar.
403withdrawals_blockedSaques estão temporariamente bloqueados para a conta.
409idempotency_conflictA mesma Idempotency-Key foi usada com outro corpo.
422insufficient_balanceO saldo disponível não cobre o valor solicitado.
429rate_limitedO limite de requisições foi excedido. Faça retry com backoff.

​
Próximos passos

Consultar saldo

Use availableAmount para decidir se o saque pode ser solicitado.

Revisar autenticação

Entenda chaves, produção, idempotência e permissões.

Entender erros

Veja o envelope de erro e como tratar cada code.