Skip to content

Ambiente Sandbox — Cartões de Teste (Stripe + Asaas)

Guia para o time de frontend testar fluxos de pagamento no ambiente development (FDPLAY_ENV=development, padrão quando a variável não é definida) sem usar dinheiro ou cartão real.

Verificar antes de testar: Stripe dev pode estar com chaves LIVE

A seção [development.stripe] do credentials.toml do backend deve conter chaves pk_test_ / sk_test_ (ou rk_test_). Se ao consultar GET /api/v1/stripe/config a publishable_key retornada começar com pk_live_, os cartões de teste desta página não funcionam — qualquer tentativa de pagamento vai contra o Stripe real (cartões de teste são recusados; um cartão real, se usado, seria cobrado de verdade). Nesse caso, pare os testes de Stripe e avise o time de backend antes de continuar — é uma configuração incorreta do ambiente dev, não uma limitação do frontend.

Como saber em qual ambiente você está

Sinal Sandbox (development) Produção (production)
Asaas base_url https://api-sandbox.asaas.com/v3 https://api.asaas.com/v3
Asaas API key prefixo $aact_hmlg_... prefixo $aact_prod_...
Stripe publishable_key (via GET /api/v1/stripe/config) pk_test_... pk_live_...
Cobrança Simulada — nunca cai em conta real Real — dinheiro sai da conta do cliente

O frontend não define o ambiente — ele só consome o que o backend expõe. Para saber qual gateway está ativo no momento, consulte GET /api/v1/config/payment-gateway.

Stripe — cartões de teste

Só funcionam com chaves pk_test_ / sk_test_. Fonte: Stripe Testing Docs.

Número Cenário
4242 4242 4242 4242 Pagamento aprovado
4000 0025 0000 3155 Requer autenticação 3D Secure
4000 0000 0000 9995 Recusado — saldo insuficiente
4000 0000 0000 0002 Recusado — genérico (card_declined)
4000 0000 0000 0341 Aprovado na cobrança, mas gera disputa/chargeback depois
4000 0000 0000 9979 Recusado — cartão perdido/roubado (fraude)

Dados complementares (qualquer valor no formato correto funciona):

  • Validade: qualquer data futura, ex. 12/2030
  • CVC: qualquer 3 dígitos, ex. 123
  • CEP: qualquer valor válido, ex. 01310-100
  • Nome do titular: qualquer nome

Onde a publishable_key vem: o frontend nunca hardcoda a chave — busca via GET /api/v1/stripe/config e usa o flutter_stripe/Stripe Elements para tokenizar o cartão. Detalhes completos em Integração Stripe.

Asaas — cartão de teste (sandbox)

O Asaas sandbox não exige tokenização no frontend — o número do cartão vai direto no body da requisição para a FDPlay API (por isso HTTPS é obrigatório mesmo em dev). Fonte: Asaas Sandbox Docs.

{
  "holderName": "JOAO DA SILVA",
  "number": "5162306219378829",
  "expiryMonth": "05",
  "expiryYear": "2028",
  "ccv": "318"
}

Para simular um cartão recusado, altere um dígito do CCV ou da validade (ex. data já expirada) — o sandbox aplica a mesma validação de formato/consistência da produção, sem de fato cobrar. O Asaas não publica uma tabela de números reservados por cenário como a Stripe; se precisar reproduzir um código de erro específico (recusa por saldo, cartão inválido etc.), consulte o Asaas Sandbox ou o suporte deles.

PIX no sandbox

O QR code retornado (pix.qr_code_image / pix.qr_code) é simulado. O painel de sandbox (link abaixo) tem um botão para confirmar manualmente o pagamento PIX de teste sem precisar de um app de banco real.

CPF de teste

  • 24971563792 — aprovado no sandbox

Painel sandbox

Acesse https://sandbox.asaas.com (login separado do painel de produção) para ver clientes, assinaturas e cobranças criadas durante os testes, e para confirmar PIX manualmente.

Detalhes completos do fluxo (assinatura, troca de cartão, cancelamento) em Integração Asaas.

Checklist rápido antes de testar

  • [ ] Confirmar GET /api/v1/config/payment-gateway — qual gateway está ativo
  • [ ] Se Stripe: confirmar publishable_key em GET /api/v1/stripe/config começa com pk_test_
  • [ ] Se Asaas: usar CPF 24971563792 e cartão 5162306219378829 acima
  • [ ] Nunca usar cartão real, mesmo em sandbox — o objetivo é validar o fluxo, não a cobrança
  • [ ] Para PIX Asaas, usar o painel sandbox.asaas.com para confirmar o pagamento manualmente

Referências