Ir para o conteúdo

Como Usar o Ambiente Sandbox do 4Geeks Payments para Testes

🤖 Explicar com IA

Implementar a lógica de pagamento diretamente em um ambiente de produção acarreta riscos significativos, como cobranças acidentais em cartões de crédito reais e relatórios financeiros desorganizados. O 4Geeks Payments Sandbox fornece uma réplica segura e isolada do seu ambiente de produção. Ele permite que desenvolvedores e gestores financeiros simulem transações, testem integrações de API e validem fluxos de trabalho de faturamento complexos usando o 4Geeks Payments sem movimentar dinheiro real.

Este artigo orienta você no acesso ao sandbox, na obtenção de credenciais de teste e na realização de transações simuladas para garantir que seu sistema esteja pronto para o lançamento.

Pré-requisitos

Antes de iniciar os testes, certifique-se de ter o seguinte:

  • Acesso ao 4Geeks Console: Você deve ter uma conta ativa com acesso ao 4Geeks Console.
  • Permissões: Você precisa de permissões de nível “Desenvolvedor” ou “Admin” para visualizar as chaves de API e alternar os modos de ambiente.
  • Integração de Pagamento: Idealmente, você deve ter uma compreensão básica de como sua aplicação se conecta ao 4Geeks Payments ou estar pronto para testar transações manuais por meio do painel.

Instruções Passo a Passo

Siga estas etapas para configurar e utilizar o ambiente sandbox de forma eficaz.

Passo 1: Alternar para o Modo de Teste

A plataforma 4Geeks separa os dados “Live” (Produção) dos dados “Test” (Teste) para evitar acidentes.

  1. Faça login no 4Geeks Console.
  2. Navegue até o módulo Payments na barra lateral esquerda.
  3. Localize o Alternador de Ambiente na barra de navegação superior (geralmente exibindo “Live”).
  4. Clique no alternador para mudar para “Test” ou “Sandbox”.
  5. O banner do painel deve mudar de cor (geralmente para laranja ou azul) para indicar que agora você está trabalhando com dados fictícios.

Passo 2: Obter Credenciais de API de Teste

Suas chaves de API de produção não funcionarão no sandbox. Você deve gerar credenciais específicas para testes.

  1. Enquanto estiver no Modo de Teste, vá para Settings > API & Webhooks.
  2. Localize as seções Public Key (Chave Pública) e Secret Key (Chave Secreta).
  3. Clique em Reveal Keys para visualizar suas credenciais de teste. Essas chaves geralmente começam com um prefixo como pk_test_ ou sk_test_.
  4. Copie essas chaves e atualize seu ambiente de desenvolvimento local ou a configuração do servidor de ensaio (staging).

Nota: Nunca use suas chaves reais (pk_live_...) no código de teste, pois isso resultará em falha na autenticação ou transações reais não pretendidas.

Passo 3: Simular uma Transação

Você pode verificar sua integração processando um pagamento usando números de cartão de teste.

  1. Inicie um fluxo de pagamento por meio da sua aplicação (ex: uma página de checkout ou link de pagamento de fatura).
  2. Quando solicitados os detalhes do pagamento, use um dos Números de Cartão de Teste da 4Geeks. (Veja a documentação do 4Geeks Payments para obter uma lista completa).
    • Visa (Sucesso): 4242 4242 4242 4242
    • Mastercard (Recusado): 5100 0000 0000 0051
    • Data de Validade: Qualquer data futura.
    • CVC: Qualquer número de 3 dígitos (ex: 123).
  3. Conclua o processo de checkout.

Passo 4: Verificar os Resultados

  1. Retorne ao 4Geeks Console (certifique-se de que ainda está no Modo de Teste).
  2. Clique na guia Transactions.
  3. Você deve ver seu pagamento simulado mais recente listado.
  4. Clique no ID da transação para visualizar os detalhes, incluindo o status (Sucedido/Falhou), logs de resposta da API brutos e metadados associados.

Casos de Uso Comuns

Cenário 1: Testando a Cobrança Automática (Dunning) para Assinaturas

Se você usa o 4Geeks Payments para gerenciar faturamento recorrente, pode simular um pagamento com falha para testar sua lógica de dunning (retentativa).

  • Ação: Crie uma assinatura no sandbox usando um número de cartão de teste específico de “Recusa”.
  • Validação: Verifique se o sistema tenta refazer o pagamento de acordo com seu cronograma e se a notificação de e-mail “Falha no Pagamento” correta é disparada para o e-mail do cliente fictício.

Cenário 2: Validando Desembolsos de Folha de Pagamento

Para empresas que usam o 4Geeks Payroll, o sandbox é essencial para testar pagamentos a contratados.

  • Ação: Configure um perfil de contratado de teste e inicie um pagamento em massa usando fundos de teste em sua carteira virtual.
  • Validação: Verifique se o status da transação muda para “Pago” no console e se o webhook correspondente é disparado para seu sistema de backend, confirmando que a integração lida com os pagamentos corretamente.

Solução de Problemas

Problema 1: Erro “Chave de API Inválida”

  • Causa: Você provavelmente está usando suas chaves de API reais enquanto sua aplicação está apontando para o endpoint Sandbox, ou vice-versa.
  • Solução: Verifique seu arquivo .env ou as configurações de configuração. Certifique-se de que suas chaves correspondam ao ambiente (chaves de teste para o Sandbox, chaves reais para Produção).

Problema 2: As transações não estão aparecendo no Painel

  • Causa: O console pode estar configurado no modo errado.
  • Solução: Observe o botão de alternância no cabeçalho do 4Geeks Console. Se você processou uma transação de teste, certifique-se de que o alternador esteja configurado como Test. Transações reais nunca aparecerão na visualização de Teste.

Problema 3: Os webhooks não estão sendo disparados

  • Causa: Os endpoints de webhook devem ser configurados separadamente para os ambientes real e de teste.
  • Solução: Vá para Settings > API & Webhooks enquanto estiver no Modo de Teste. Certifique-se de que a URL do seu servidor de ensaio (staging) seja adicionada como um endpoint de webhook e que os eventos “subscription_created” ou “payment_succeeded” estejam ativados.

Conclusão

Utilizar o 4Geeks Payments Sandbox é uma etapa crucial no ciclo de vida de desenvolvimento. Isso garante que sua lógica de faturamento, desde o faturamento de pacientes no 4Geeks Health até a gestão de assinaturas no 4Geeks Assets, funcione perfeitamente antes de interagir com clientes reais. Ao isolar os testes neste ambiente, você protege seus fluxos de receita e mantém os dados limpos para relatórios precisos.

Para cenários de teste mais avançados, como simulação 3D Secure ou tratamento de disputas, consulte os Recursos Adicionais abaixo.

Recursos Adicionais