> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Testar pagamentos no sandbox
> Guia passo a passo pelo ambiente de sandbox da Chargefy: como ativar, separar dados de teste e validar cartão, PIX e boleto de ponta a ponta.
Sandbox é um ambiente de teste completo: os mesmos endpoints, os mesmos objetos e os mesmos webhooks da produção — só que sem dinheiro real. Dados criados com uma chave `ch_test_...` ficam separados de produção e retornam `livemode: false`.
Duas coisas tornam o sandbox o caminho mais seguro para validar a integração: **isolamento financeiro**, porque nenhuma transação movimenta dinheiro real, e **resultados determinísticos**, porque e-mails de teste controlam sucesso, expiração ou permanência em `pending` para PIX e boleto.
O sandbox funciona de ponta a ponta **antes mesmo da ativação** da
organização. Enquanto o cadastro está em análise, você já cria payment links,
checkout sessions e payment intents de teste, paga com os dados de teste e
recebe os webhooks — a integração inteira pode ficar pronta em paralelo. A
ativação só é exigida para receber pagamentos reais no ambiente live.
## As peças e o papel de cada uma
| Peça | Onde vive | Papel |
| ----------------- | -------------------------------- | -------------------------------------------------------------------------------- |
| Ambiente `test` | Toggle no menu da sua conta | Alterna o dashboard inteiro e as chamadas de API entre dados reais e de sandbox. |
| `ch_test_...` | Developers → Chaves de API | Chave que autentica chamadas em sandbox — nunca processa dinheiro real. |
| Banner de sandbox | Topo de toda página do dashboard | Indicador fixo de que você está em test mode. |
| E-mails de teste | Campo de e-mail do cliente | Determinam o resultado de PIX e boleto sem criar uma API paralela. |
## Ative o sandbox no dashboard
**Por que essa etapa existe:** o ambiente não fica numa página separada de
configurações — ele vive dentro do menu do seu usuário, sempre visível.
No rodapé da barra lateral do dashboard, clique no seu avatar (nome e
e-mail) para abrir **Minha conta**.
**Por que essa etapa existe:** é a ação que troca o ambiente — sem precisar
criar uma chave nova nem fazer login de novo.
O mesmo toggle troca o ambiente do dashboard inteiro: pagamentos, produtos,
clientes, tudo passa a mostrar dados de teste (`livemode: false`) até você
sair. O item vira **Sair do sandbox** para reverter quando quiser — a troca
é sempre livre, inclusive antes da ativação. Contas que ainda não ativaram
já começam no sandbox por padrão.
**Por que essa etapa existe:** é a garantia visual de que você não vai
processar nada de verdade por engano.
Um banner fixo aparece no topo de toda página enquanto o sandbox estiver
ativo:
Esse banner é o seu lembrete: se ele sumiu, você está de volta ao ambiente
live — e qualquer pagamento processa de verdade.
## Crie uma chave de teste
O toggle acima muda o **dashboard**; para chamar a API você precisa de uma chave `ch_test_...`. No dashboard, abra **Developers → Chaves de API**, clique em **Nova chave** e selecione o ambiente `test`. Detalhes em [API keys](/api-reference/api-keys).
Você pode criar a chave e validar a integração inteira enquanto o cadastro é
analisado — o sandbox não exige ativação. Só o ambiente live exige a
organização ativa para confirmar pagamentos.
## Antes de testar pagamentos
Você precisa de duas coisas prontas — as duas saem de
[Aceitar seu primeiro pagamento](/accept-your-first-payment):
1. **Uma página de pagamento** (a `url` de um payment link ou de uma checkout
session), com cartão, PIX e boleto habilitados.
2. **Um receiver de webhook** tratando `checkout.session.completed`,
`checkout.session.async.payment.succeeded` e
`checkout.session.async.payment.failed`.
## Teste cada método de pagamento
**Por que essa etapa existe:** é a linha de base — o caminho mais simples,
sem esperar nenhum evento assíncrono. Todo o resto deste guia compara PIX e
boleto contra esse comportamento.
Abra a `url` do seu link, preencha os dados e pague com o cartão de teste
`4242 4242 4242 4242` (qualquer CVC de 3 dígitos, qualquer validade futura):
A aprovação é **síncrona**: acontece ali, durante o checkout. Segundos
depois, seu endpoint recebe o `checkout.session.completed` já pago:
```json theme={"theme":"css-variables"}
{
"id": "evt_o5pgYv1B73HT5rWc",
"object": "event",
"created_at": "2026-07-14T12:05:00Z",
"data": {
"object": {
"id": "cs_ay9PvVa23xDAxPeo",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 4990,
"amount_tax": 0,
"amount_total": 4990,
"cancel_url": null,
"client_reference_id": null,
"client_secret": "57aac57b1b1895113021cb6269c20fc6dcc4d9f52b3921ab4b732927f8bc29b5",
"created_at": "2026-07-14T12:05:00Z",
"currency": "brl",
"customer": "cus_tqQSqt3xHqF9J9Uu",
"customer_document": null,
"customer_document_type": null,
"customer_email": "nome@email.com",
"customer_name": "Nome do Cliente",
"discount": null,
"expires_at": "2026-07-15T12:05:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_NG2wRiPmrQrkzp5G",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 4990,
"amount_tax": 0,
"amount_total": 4990,
"currency": "brl",
"description": null,
"metadata": {},
"position": 0,
"price": "price_V11e8uD4C4z8aMBP",
"price_data": null,
"product": "prod_m2YBjmHLg9ePfHDe",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"unit_amount": 4990
}
],
"livemode": false,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"payment_data": {
"installments": 1,
"payment_method": "credit_card",
"status": "succeeded"
},
"payment_method_collection": "if_required",
"payment_status": "paid",
"status": "complete",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"url": "https://pay.chargefy.io/cs_ay9PvVa23xDAxPeo"
}
},
"livemode": false,
"organization": "org_VVy68SMPFLZ5rVoZ",
"request": {
"id": null
},
"type": "checkout.session.completed"
}
```
`payment_status: "paid"` — pode entregar. Repare que não existe um segundo
evento aqui: com cartão, um único `checkout.session.completed` já basta.
Quer testar uma recusa em vez de uma aprovação? A lista completa de
cartões de teste (recusa por saldo, cartão vencido, CVC inválido etc.) está
em [Sandbox → Simular cartões](/api-reference/sandbox).
**Por que essa etapa existe:** é o primeiro caso em que "checkout concluído"
e "dinheiro confirmado" são dois momentos diferentes — o ponto central deste
guia.
Abra o link de novo e escolha a aba **PIX**. O comprador recebe um QR
code — e o checkout termina **antes** do pagamento acontecer:
Seu endpoint recebe o `checkout.session.completed` com:
```json theme={"theme":"css-variables"}
"payment_status": "unpaid"
```
É isso que "assíncrono" significa: concluir o checkout e pagar são dois
momentos diferentes. Use `succeed_delayed@meusite.com` como e-mail do
cliente. O QR code nasce com o pagamento em `pending` e, após cerca de 3
minutos, chega o `checkout.session.async.payment.succeeded` com
`payment_status: "paid"` e `payment_data.payment_method: "pix"` — o sinal
para entregar.
Para testar a resposta imediata sem esperar, use
`succeed_immediately@meusite.com`. Para manter o QR pendente sem uma
transição automática de teste, use `pending@meusite.com`.
No checkout hospedado em sandbox, a barra amarela do topo também oferece
**Simular pagamento** e **Simular expiração** depois que o QR ou boleto é
criado. Use os botões para testes manuais rápidos; use os e-mails acima em
testes automatizados.
**Por que essa etapa existe:** confirma que boleto segue exatamente o
mesmo desenho do PIX — só muda o relógio, não o código do seu receiver.
A aba **Boleto** segue o mesmo caminho do PIX: o comprador recebe um boleto
com código de barras (o checkout exige CPF/CNPJ e endereço nesse método):
O `checkout.session.completed` chega `unpaid`, e a confirmação vem depois
por `checkout.session.async.payment.succeeded`. Use o mesmo
`succeed_delayed@meusite.com`; a diferença em produção é o relógio, pois a
compensação de um boleto pago leva normalmente 1–2 dias úteis. CPF/CNPJ e
endereço continuam obrigatórios e precisam ser válidos. Detalhes do método
em [Boleto](/payments/boleto).
**Por que essa etapa existe:** nem todo PIX ou boleto termina em sucesso —
o comprador desiste, o boleto vence. Testar isso evita pedidos presos em
"pendente" para sempre.
Use `expire_delayed@meusite.com` para começar em `pending` e receber
`checkout.session.async.payment.failed` cerca de 3 minutos depois. Use
`expire_immediately@meusite.com` quando quiser que a confirmação já retorne
o `payment_intent` como `canceled`.
Esses resultados percorrem o mesmo processamento financeiro e os mesmos
webhooks do ambiente live; o e-mail só escolhe o evento que o processador
de teste vai produzir.
## Síncrono vs. assíncrono, lado a lado
| Método | Durante o checkout | Confirmação do dinheiro | Evento que libera a entrega |
| ------ | ---------------------------- | -------------------------------------- | --------------------------------------------------------- |
| Cartão | Aprovado ou recusado na hora | Imediata (síncrona) | `checkout.session.completed` com `payment_status: "paid"` |
| PIX | Comprador recebe o QR code | Segundos após o pagamento (assíncrona) | `checkout.session.async.payment.succeeded` |
| Boleto | Comprador recebe o boleto | 1–2 dias úteis após pagar (assíncrona) | `checkout.session.async.payment.succeeded` |
**Regra de ouro:** entregue o produto quando `payment_status` virar `"paid"` —
nunca quando o comprador voltar para a página de sucesso. Em PIX e boleto, ele
volta **antes** de pagar, e pode nunca pagar. O redirect é UX; o webhook é a
verdade.
## Ir para produção
Sandbox e produção usam o mesmo código — só o ambiente muda:
1. **Confirme a ativação da organização.** O sandbox funciona sem ela, mas o
ambiente live recusa a confirmação de pagamento (`organization_not_activated`)
até `activation_status` chegar a `active`. Revise também os dados do negócio
e a conta para saques — veja [KYC](/business-model/kyc).
2. **Saia do sandbox** no mesmo menu (**Minha conta → Sair do sandbox**) e
crie uma chave live (`ch_live_...`). Dados de teste não migram: recrie
produto, preço e link com a chave live.
3. **Cadastre o endpoint de webhook no ambiente live.** Endpoints e secrets
são separados por ambiente.
## Próximos passos
Produto, link de pagamento e o receiver de webhook que este guia
reaproveita.
Ambientes live vs. test, escopos e rotação de chaves.
Cartões e e-mails especiais para todos os cenários de pagamento.
Assinatura, retries, idempotência e reentrega manual — o contrato completo.