# troqpay > A troqpay é uma API para cobrar com Pix no Brasil, acompanhar pagamentos por webhook, ler saldo e solicitar saques em produção. A URL-base é `https://api.troqpay.com`. Toda chamada autenticada usa `Authorization: Bearer `. A moeda das cobranças é sempre `BRL`. O checkout hospedado fica em `https://pay.troqpay.com/pay/{checkoutId}`. Saques (Pix ou carteira USDT) exigem conta aprovada, destino aprovado, saldo disponível, chave com permissão de saque e `Idempotency-Key`. Notas importantes: - Chaves: `trq_test_` para teste e `trq_live_` para produção. Ambas usam `Authorization: Bearer ...` e a mesma URL-base. - Acesso a produção: `trq_live_` só funciona quando a conta está marcada como `APPROVED`. O gate é aplicado em `POST /v1/checkouts`, `GET /v1/balance` e saques em produção. Em contas não-aprovadas, essas rotas retornam `403 forbidden`. `GET /v1/checkouts/{checkoutId}` continua funcionando mesmo sem `APPROVED`. - Valores: `amount` no checkout é **inteiro em centavos de BRL**. Os campos de saldo são **strings decimais** em BRL. - Saques: `POST /v1/withdrawals` cria um saque somente em produção. Body: `{ "rail": "BRL_PIX" | "USDT_WALLET", "amount": "" }`. O destino não vai no body; a API usa o destino aprovado na conta. `GET /v1/withdrawals/{withdrawalId}` consulta um saque. - Permissão de saque: a chave precisa ter permissão de saque para criar ou consultar saques pela API. Sem permissão, a API retorna `403 api_key_scope_forbidden`. - `Idempotency-Key`: opcional/recomendado em criações de checkout e obrigatório em criações de saque. A API hash o corpo com serialização JSON estável e key-sorted. Reordenar chaves equivale ao mesmo corpo. Não há expiração. Primeira criação devolve `201`; reentrega idempotente devolve `200`. - `Request-Id` (header de resposta, sempre presente): formato `req_<24 hex>`. O cliente pode mandar `Request-Id` ou `X-Request-Id` na requisição e a API ecoa o mesmo valor. - Envelope de erro: `{ "error": { "type", "code", "message", "requestId" } }`. Mensagens em inglês literais. 401 emite sempre `code: "unauthorized"`. - URL hospedada do checkout: a forma canônica é `https://pay.troqpay.com/pay/{checkoutId}`. O prefixo legacy `/c/` **não** é redirect — links externos para `/c/...` resultam em 404. - Customer no checkout: `phone` é aceito no envio mas **não é retornado** na resposta nem no payload do webhook. `document` aceita 3-32 caracteres e não é validado como CPF/CNPJ. - Webhooks: assinatura HMAC-SHA256 do corpo bruto em hex, no header `x-troqpay-signature`. Segredo único por endpoint. Até 5 tentativas, backoff `60s → 5m → 15m → 60m`, timeout de 5 segundos. O entregador **não segue redirects** — qualquer 3xx no seu endpoint vira falha. - Links de pagamento: gerenciados apenas no app (`https://app.troqpay.com`). URL pública `https://pay.troqpay.com/l/{paymentLinkId}`. Não há endpoint REST público para criar, listar ou modificar links. ## Checkouts (cobrar com Pix) - [Checkouts Pix](https://docs.troqpay.com/flows/checkouts-pix): conceito, ciclo de vida, campos da requisição e da resposta. - [POST /v1/checkouts](https://docs.troqpay.com/api-reference): cria uma cobrança Pix. Body mínimo: `{ "amount": , "description": , "externalId": }`. Aceita `customer` (com `name` mais um de `email`/`document`/`phone`), `metadata` (string-only), `expiresIn` (60-86400). `currency` é sempre `BRL`. Devolve `201` na criação ou `200` em reentrega idempotente. - [GET /v1/checkouts/{checkoutId}](https://docs.troqpay.com/api-reference): lê o checkout no formato `SerializedCheckout`. Não há endpoint de listagem. ## Saldo - [Saldo](https://docs.troqpay.com/flows/saldo): como ler `GET /v1/balance` e cada campo. - [GET /v1/balance](https://docs.troqpay.com/api-reference): retorna `{ livemode, currency, grossAmount, feeAmount, pendingAmount, availableAmount, reservedAmount, blockedAmount }`. Todos os valores monetários são strings decimais em BRL. ## Saques - [Saques](https://docs.troqpay.com/flows/saques): como criar e consultar saques em produção. - [POST /v1/withdrawals](https://docs.troqpay.com/api-reference): cria saque. Requer `trq_live_`, conta aprovada, permissão de saque, destino aprovado, saldo disponível e `Idempotency-Key`. - [GET /v1/withdrawals/{withdrawalId}](https://docs.troqpay.com/api-reference): consulta saque. Requer permissão de leitura de saque. ## Webhooks - [Webhooks](https://docs.troqpay.com/flows/webhooks): cadastro, assinatura, retentativas, restrições de endpoint. - Eventos disponíveis: `checkout.created`, `checkout.paid`, `checkout.expired`. - Envelope: `{ id, type, createdAt, livemode, data: { checkout: SerializedCheckout } }`. `data.checkout` é o checkout completo, igual ao retornado por `GET /v1/checkouts/{id}`. - Assinatura: `x-troqpay-signature = HMAC_SHA256(rawBody, signingSecret).hex()`. Segredo único por endpoint. Até 5 tentativas com backoff `60s → 5m → 15m → 60m`. Sem follow-redirect. ## Links de Pagamento - [Links de pagamento](https://docs.troqpay.com/flows/links-de-pagamento): conceito e fluxo. - Gerenciamento apenas via app. URL pública `https://pay.troqpay.com/l/{paymentLinkId}` (formato `plink_<16 hex>`). Cada uso do link cria um checkout — recuperável pelos endpoints de checkout acima. ## Erros - [Erros](https://docs.troqpay.com/flows/errors): formato do erro, status HTTP por categoria, lista completa de `code`. - Códigos emitidos no escopo público: `invalid_json` (400), `invalid_request_body` (400), `idempotency_key_required` (400, saque), `unauthorized` (401), `forbidden` (403), `api_key_scope_forbidden` (403), `test_withdrawals_not_supported` (403, saque), `withdrawal_readiness_required` (403, saque), `account_suspended` (403), `live_operations_blocked` (403, checkout), `withdrawals_blocked` (403, saque), `idempotency_conflict` (409), `invalid_expires_in` (422, checkout), `invalid_amount` (422, saque), `insufficient_balance` (422, saque), `quote_unavailable` (422, saque), `checkout_not_found` (404), `withdrawal_not_found` (404), `provider_unavailable` (503), `rate_limited` (429). ## Glossário - [Glossário](https://docs.troqpay.com/glossary): definições rápidas + subseção de prefixos de ID. - Prefixos: `chk_<20 hex>` (checkout), `evt_<24 hex>` (evento), `req_<24 hex>` (requisição), `plink_<16 hex>` (link de pagamento). --- OpenAPI canônica: https://docs.troqpay.com/api-reference/openapi.json Documentação humana: https://docs.troqpay.com App da troqpay: https://app.troqpay.com