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

# Introdução

> Entenda o que a TroqPay resolve e como pensar na API.

# Introdução

A TroqPay ajuda você a vender no Brasil com Pix e acompanhar a cobrança pelo seu backend.

Nesta documentação, você vai aprender a:

* criar um checkout Pix
* acompanhar o status da cobrança
* receber eventos por webhook
* ler o saldo da sua conta
* solicitar saques em produção (Pix ou carteira USDT)
* operar com chaves de teste e produção
* usar o SDK JavaScript e o plugin MCP para Codex/Claude

## Quando faz sentido integrar a TroqPay

Use a TroqPay quando você precisa:

* gerar cobranças Pix a partir do seu próprio backend
* conciliar pagamentos com `externalId`
* reagir ao pagamento em tempo real
* cobrar em `BRL` pela API e acompanhar saldo no mesmo lugar

<Card title="Em uma frase" horizontal>
  Seu cliente paga em `BRL` por Pix, seu sistema acompanha o checkout — e quando quiser sacar, usa o destino aprovado na conta e solicita pelo app ou pela API.
</Card>

## Tudo gira em torno do checkout

É no checkout que você encontra:

* o valor cobrado em BRL
* os dados do Pix para pagamento
* o status da cobrança
* os metadados do seu pedido
* o objeto `settlement` com a liquidação em BRL

## O que vale a pena salvar no seu sistema

<CardGroup cols={2}>
  <Card title="Identificadores">
    Salve `checkout.id` e `externalId`. Eles resolvem boa parte da sua conciliação e do suporte.
  </Card>

  <Card title="Contexto do pedido">
    Guarde também `amount`, `currency`, `description` e os campos de `metadata`
    que façam sentido para o seu fluxo.
  </Card>

  <Card title="Separação de ambiente">
    Use `livemode` para nunca misturar eventos e registros de teste com produção.
  </Card>

  <Card title="Liquidação">
    Leia `settlement.currency`, `settlement.status` e `settlement.amount` para acompanhar o estado da liquidação em BRL.
  </Card>
</CardGroup>

## Fluxo recomendado

<Steps>
  <Step title="Criar o checkout">
    Seu backend envia `POST /v1/checkouts` com valor, descrição e dados do pedido.
  </Step>

  <Step title="Exibir o Pix para o comprador">
    A API responde com `copyPaste`, `qrCodeUrl` e `checkoutUrl`, para você escolher
    o melhor formato de exibição.
  </Step>

  <Step title="Acompanhar o pagamento">
    O caminho recomendado é processar webhooks. Consulta serve para conferência,
    reconciliação e suporte.
  </Step>

  <Step title="Atualizar seu sistema">
    Quando o pagamento é confirmado, o checkout muda de status e o objeto
    `settlement` passa a refletir o estado da liquidação em BRL.
  </Step>
</Steps>

## Saldo e saques

A TroqPay também expõe a leitura do saldo agregado da sua conta:

* `GET /v1/balance` retorna o saldo separado em valores brutos, taxas, pendentes, disponíveis, reservados e bloqueados — todos como string decimal em BRL.

Saques (Pix ou carteira USDT) podem ser solicitados em produção pelo app ou por `POST /v1/withdrawals`. A criação pela API exige conta aprovada, destino de saque aprovado, saldo disponível, `Idempotency-Key` e chave com permissão de saque. No piloto atual, a solicitação reserva o saldo e passa por revisão operacional antes da conclusão.

Veja [`/flows/saldo`](/flows/saldo) para o detalhe do endpoint de saldo e [`/flows/saques`](/flows/saques) para o fluxo de saque.

## Como navegar nesta documentação

<CardGroup cols={2}>
  <Card title="Se você quer integrar rápido">
    Comece pelo Quickstart ou pelo SDK JavaScript. Eles te levam do zero até o primeiro `checkout.paid`.
  </Card>

  <Card title="Se você quer entender o modelo">
    Siga por Checkouts Pix, Webhooks e API Reference para aprofundar o comportamento da API.
  </Card>
</CardGroup>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Fazer o Quickstart" href="/quickstart">
    Valide a primeira cobrança do início ao fim.
  </Card>

  <Card title="Entender autenticação" href="/authentication">
    Veja chaves, ambiente e idempotência.
  </Card>

  <Card title="Instalar o SDK" href="/sdks/javascript">
    Use `@troqpay/sdk` no backend Node.js.
  </Card>

  <Card title="Modelar os checkouts Pix" href="/flows/checkouts-pix">
    Entenda o ciclo de vida da cobrança e o que salvar no seu sistema.
  </Card>
</CardGroup>

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Teste no sandbox" href="/sandbox">
    Use o ambiente de teste para validar checkout, webhook e reconciliação sem tráfego real.
  </Card>

  <Card title="Revise os erros" href="/flows/errors">
    Entenda o que fazer quando uma chamada falha ou um payload não passa.
  </Card>

  <Card title="Abra o app" href="https://app.troqpay.com">
    Gere chaves, reveja sua conta e mantenha teste e produção bem separados.
  </Card>
</CardGroup>