Testar pagamentos no sandbox

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

Abra o menu da sua conta

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.

Clique em Alternar para Sandbox

Por que essa etapa existe: é a ação que troca o ambiente — sem precisar criar uma chave nova nem fazer login de novo.

Menu Minha conta aberto com o item Alternar para Sandbox destacado — O item 'Alternar para Sandbox' fica dentro do menu Minha conta, no rodapé da barra lateral.

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.

Confirme pelo banner amarelo

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:

Banner amarelo: Você está em ambiente sandbox. Nenhuma transação real será processada. — Banner fixo no topo do dashboard enquanto o ambiente de sandbox está 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.

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:

Uma página de pagamento (a url de um payment link ou de uma checkout session), com cartão, PIX e boleto habilitados.
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

Cartão: confirmação na hora (síncrona)

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):

Página de pagamento hospedada com as abas Cartão, PIX e Boleto, formulário de cartão preenchido — Formulário de cartão na página de pagamento hospedada, com as abas Cartão, PIX e Boleto.

A aprovação é síncrona: acontece ali, durante o checkout. Segundos depois, seu endpoint recebe o checkout.session.completed já pago:

{
"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.

PIX: confirmação por evento (assíncrona)

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:

Página de pagamento hospedada mostrando QR code PIX gerado, com instruções de pagamento — PIX gerado na página hospedada: QR code, instruções e o código copia-e-cola.

Seu endpoint recebe o checkout.session.completed com:

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

Boleto: mesmo fluxo, prazo maior

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):

Página de pagamento hospedada mostrando boleto gerado, com código de barras e linha digitável — Boleto gerado na página hospedada: código de barras, linha digitável e link para o PDF.

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.

Simule expiração

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:

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.
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.
Cadastre o endpoint de webhook no ambiente live. Endpoints e secrets são separados por ambiente.

Próximos passos

Aceitar seu primeiro pagamento

Produto, link de pagamento e o receiver de webhook que este guia reaproveita.

API keys

Ambientes live vs. test, escopos e rotação de chaves.

Sandbox

Cartões e e-mails especiais para todos os cenários de pagamento.

Entrega de webhooks

Assinatura, retries, idempotência e reentrega manual — o contrato completo.

Comece aqui

Primeiros passos

Migração

Testar pagamentos no sandbox

As peças e o papel de cada uma

Ative o sandbox no dashboard

Crie uma chave de teste

Antes de testar pagamentos

Teste cada método de pagamento

Síncrono vs. assíncrono, lado a lado

Ir para produção

Próximos passos

Aceitar seu primeiro pagamento

API keys

Sandbox

Entrega de webhooks

​As peças e o papel de cada uma

​Ative o sandbox no dashboard

​Crie uma chave de teste

​Antes de testar pagamentos

​Teste cada método de pagamento

​Síncrono vs. assíncrono, lado a lado

​Ir para produção

​Próximos passos

Aceitar seu primeiro pagamento

API keys

Sandbox

Entrega de webhooks

As peças e o papel de cada uma

Ative o sandbox no dashboard

Crie uma chave de teste

Antes de testar pagamentos

Teste cada método de pagamento

Síncrono vs. assíncrono, lado a lado

Ir para produção

Próximos passos