Fazer cobranças funcionarem no ambiente Sandbox do Flutterwave em uma aplicação Laravel é uma etapa importante do desenvolvimento, mas a transição para o ambiente de Produção (Live) exige cuidados que vão muito além de simplesmente trocar as chaves de API no arquivo .env.
Quando lidamos com dinheiro real, pequenos deslizes na validação de payloads, tratamento de exceções ou integridade de webhooks podem gerar cobranças duplicadas, pedidos liberados sem confirmação bancária ou falhas silenciosas de pagamento.
1. Separação Estrita de Ambientes e Credenciais
O primeiro ponto crítico é garantir que nenhuma credencial de desenvolvimento permaneça ativa ou acessível em produção. No Laravel, estruture a configuração centralizada em config/services.php:
php
‘flutterwave’ => [
‘publickey’ => env(‘FLUTTERWAVEPUBLICKEY’),
‘secretkey’ => env(‘FLUTTERWAVESECRETKEY’),
‘encryptionkey’ => env(‘FLUTTERWAVEENCRYPTIONKEY’),
‘secrethash’ => env(‘FLUTTERWAVESECRETHASH’),
‘baseurl’ => env(‘FLUTTERWAVEBASE_URL’, ‘https://api.flutterwave.com/v3’),
],
Certifique-se de executar php artisan config:cache no deploy para carregar as chaves de produção de forma rápida e segura diretamente da memória.
2. Validação Rigorosa de Webhooks (Secret Hash)
No ambiente Live, depender apenas do retorno imediato do redirecionamento do checkout do cliente é uma vulnerabilidade grave. O cliente pode fechar o navegador antes do callback ser concluído.
A confirmação definitiva deve ser processada assincronamente via webhook. O Flutterwave envia um header chamado verif-hash. Valide esse valor contra o seu hash secreto antes de processar qualquer alteração no banco de dados:
php
public function handleWebhook(Request $request)
{
$signature = $request->header(‘verif-hash’);
if (!$signature || $signature !== config('services.flutterwave.secret_hash')) {
return response()->json(['message' => 'Unauthorized'], 401);
}
$payload = $request->all();
// Despachar job para processamento assíncrono
ProcessPaymentWebhookJob::dispatch($payload);
return response()->json(['status' => 'success'], 200);
}
3. Idempotência e Prevenção de Cobranças Duplicadas
Em sistemas que desenvolvo, costumo implementar uma camada de idempotência estrita para endpoints de pagamento. Redes instáveis podem reenviar webhooks ou o próprio usuário pode clicar duas vezes no botão de pagamento.
- Armazene o
tx_refúnico gerado pela sua aplicação antes da requisição. - Ao receber o webhook, consulte a API do Flutterwave (
/transactions/{id}/verify) diretamente pelo backend para confirmar que o status retornado bate com os dados recebidos, evitando payloads forjados. - Utilize transações de banco de dados (
DB::transaction) combinadas com bloqueio pessimista (lockForUpdate) para garantir que o saldo ou pedido só seja liberado uma única vez.
Processo Seguro de Virada de Chave (Go-Live)
Para executar a migração sem interrupções indesejadas, adote um checklist metódico:
- Verificação de Conta Live: Confirme se os documentos da empresa foram validados e os limites de transação do Flutterwave estão aprovados.
- Cadastro do Webhook URL no Painel Live: Lembre-se de que as URLs de webhook configuradas no Sandbox não são migradas automaticamente para o ambiente de Produção do Flutterwave. Acesse o painel Live e cadastre a URL final com SSL ativo (HTTPS obrigatório).
- Smoke Test com Valor Real: Execute uma transação real de baixo valor usando um cartão válido. Verifique se o débito ocorreu, se o webhook foi recebido, se o log gravou os dados de reconciliação e, em seguida, realize o estorno pelo painel.
- Monitoramento Estruturado: Monitore a fila de jobs e os logs de exceção durante as primeiras 48 horas após a virada.
Precisa de suporte técnico para validar sua arquitetura de pagamentos ou conduzir a migração do Flutterwave com máxima estabilidade e segurança? Entre em contato para uma consultoria técnica especializada.
