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

# Sandbox

> Teste sua integração sem misturar validação técnica com tráfego real.

# Sandbox

O sandbox existe para você validar a integração inteira sem movimentar valores reais.

É nele que você confirma se:

* o checkout é criado do jeito certo
* o Pix aparece como esperado
* os webhooks chegam
* sua conciliação funciona

## Como identificar respostas de teste

Sempre que você usar uma chave `trq_test_`, a resposta virá com:

* `livemode: false`
* dados marcados como teste
* webhooks com `livemode: false`

<Info>
  O ambiente não muda pela URL. Ele muda pela chave que você usa na requisição.
</Info>

## O que vale a pena testar no sandbox

<Steps>
  <Step title="Criação do checkout">
    Confirme se seu backend cria a cobrança, salva `checkout.id` e relaciona tudo com `externalId`.
  </Step>

  <Step title="Exibição do Pix">
    Verifique se seu front-end mostra o `copyPaste`, o QR Code ou o checkout hospedado sem depender do backend a cada refresh.
  </Step>

  <Step title="Consulta e reconciliação">
    Teste `GET /v1/checkouts/{checkoutId}` para ler o estado mais recente. Salve sempre `checkout.id` no momento da criação — ele é o ponto de consulta canônico.
  </Step>

  <Step title="Recebimento de webhooks">
    Valide assinatura, responda `2xx` rápido e confirme que o mesmo evento não é processado duas vezes.
  </Step>

  <Step title="Simular pagamento de teste">
    No app, abra um checkout de teste e use o botão de simulação de pagamento para disparar o webhook `checkout.paid` sem precisar pagar de verdade.
  </Step>
</Steps>

## Onde revisar isso no app

No fluxo mais comum, você usa o app da TroqPay para:

* gerar uma chave `trq_test_`
* revisar se está no ambiente certo
* cadastrar um endpoint de webhook de teste
* acompanhar a configuração da conta antes de ir para produção

## Estados que você vai ver com mais frequência

| Status      | O que significa                        |
| ----------- | -------------------------------------- |
| `PENDING`   | Checkout criado e aguardando pagamento |
| `PAID`      | Pix confirmado                         |
| `EXPIRED`   | O prazo da cobrança terminou           |
| `CANCELLED` | Checkout cancelado                     |

## O que observar antes de avançar

<CardGroup cols={2}>
  <Card title="Dados que precisam bater">
    `checkout.id`, `externalId`, `amount` e `livemode` precisam estar salvos e fáceis de localizar nos seus logs.
  </Card>

  <Card title="Pix que precisa aparecer">
    Seu front-end deve conseguir exibir `copyPaste`, QR Code ou `checkoutUrl` sem depender de uma tela manual da TroqPay.
  </Card>

  <Card title="Webhook que precisa chegar">
    Seu endpoint deve validar assinatura, responder `2xx` rápido e ignorar duplicidade com segurança.
  </Card>

  <Card title="Ambientes separados">
    Mantenha teste e produção em chaves, URLs e logs separados desde o início.
  </Card>
</CardGroup>

## Checklist antes de ir para produção

* o checkout é criado sem duplicidade
* o app consegue renderizar o Pix corretamente
* o sistema processa `checkout.paid`
* a reconciliação usa `checkout.id` ou `externalId`
* seus logs e monitoramento diferenciam teste e produção

<Tip>
  Se possível, use uma URL de webhook separada para sandbox. Isso facilita debug, replay e leitura de logs.
</Tip>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Quickstart" href="/quickstart">
    Se você ainda não fez a primeira cobrança, volte e execute o fluxo completo.
  </Card>

  <Card title="Webhooks" href="/flows/webhooks">
    Aprofunde assinatura, reentregas e o processamento dos eventos.
  </Card>

  <Card title="Produção" href="/production">
    Veja o checklist para trocar a chave e subir tráfego real com segurança.
  </Card>
</CardGroup>

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Revisar erros" href="/flows/errors">
    Use a página de erros para interpretar falhas de autenticação, validação e rate limit.
  </Card>

  <Card title="Boas práticas" href="/flows/boas-praticas-checkout">
    Veja o que vale a pena salvar, monitorar e validar antes de crescer o uso.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Gere chaves de teste e mantenha sua configuração de sandbox organizada.
  </Card>
</CardGroup>