AcapaPay · Laravel SDK

Modo Sandbox — Testes Locais

O Que é o Modo Sandbox

O Modo Sandbox permite simular fluxos de pagamento completos — desde o clique de compra até ao processamento do Webhook — sem gerar faturas reais, sem debitar nenhuma conta, e sem comunicar com os gateways de pagamento externos (Pay4All, E-Kwanza, etc.).

Ativar o Sandbox

Basta adicionar ao seu ficheiro .env da aplicação em desenvolvimento:

ACAPAPAY_MODO=sandbox

O SDK envia automaticamente sandbox_mode: true na metadata do checkout. O SSO Acapadev deteta esta flag e apresenta uma interface de testes especial.

🚫 NUNCA ativar em Produção!

Com ACAPAPAY_MODO=sandbox, os utilizadores reais poderão "pagar" faturas simuladas gratuitamente. Se a variável não estiver definida no .env, o SDK assume production como padrão.

Como Testar

Defina ACAPAPAY_MODO=sandbox no .env.
Inicie o fluxo de checkout normalmente no seu projeto.
Será redirecionado para o ecrã de checkout do SSO. Verá uma aba "Sandbox" roxa com as opções de simulação.
Clique em "Simular Pagamento com Sucesso" ou "Simular Falha".
O SSO dispara imediatamente o Webhook para o URL configurado.
Verifique nos logs (storage/logs/laravel.log) se o evento AcapaPayInvoicePaid foi disparado.

Receber Webhooks Localmente

Quando desenvolve localmente (meuprojeto.test ou localhost), o servidor do SSO não consegue fazer chamadas ao seu computador. Use uma solução de túnel reverso para expor o seu servidor local à internet:

# Opção 1: Ngrok (mais popular)
ngrok http 80
# Ngrok gera um URL como: https://abc123.ngrok.io
# Configure esse URL nas Webhooks da sua App no painel SSO:
# https://abc123.ngrok.io/webhooks/acapapay

# Opção 2: Cloudflare Tunnel (recomendado para ambientes permanentes)
cloudflared tunnel --url http://localhost:80

Dica sobre SSL Local: Se está a usar o Laragon com certificados auto-assinados e o SDK reportar erros de SSL, adicione temporariamente ACAPAPAY_VERIFY_SSL=false ao .env. Nunca usar em produção.

← Webhooks Sync de Planos →