Integração do Yappy e pagamentos no Panamá com Laravel e WordPress

Integrar o Yappy em um comércio panamenho envolve mais do que colocar um botão de pagamento. É preciso um fluxo claro, valor assinado no servidor, estados que sobrevivam a interrupções do usuário e um backend capaz de explicar por que um pedido foi pago ou não.

Este artigo descreve o padrão backend-first com Laravel e, quando o front é WordPress ou WooCommerce, mantém o CMS como vitrine e checkout visual, movendo a lógica sensível para fora do tema. Aplica-se a integrações com Yappy, BAC Credomatic, Paguelo Fácil e gateways unificados.

O que é o Yappy na prática

Yappy (Banco General) é uma forma de cobrança muito usada no Panamá. Em integrações comerciais típicas:

1. Cadastro do comércio e credenciais (merchantId / secret) no portal comercial.
2. Geração de uma URL ou intenção de pagamento a partir do servidor.
3. O usuário conclui o pagamento no fluxo do Yappy (app / redirect).
4. O sistema recebe o resultado por redirect + notificação no endpoint e atualiza o pedido.

Regra de ouro: o pagamento nasce no backend

Antes de exibir o botão no front, o servidor deve:

1. Criar ou recuperar o pedido com itens, moeda e impostos.
2. Calcular o total no servidor (nunca confiar no JSON do navegador).
3. Salvar um registro de pagamento em estado pending com order_id interno.
4. Solicitar ao Yappy a URL / token de pagamento com esses valores.
5. Redirecionar ou devolver ao front apenas o necessário para continuar.

WordPress / WooCommerce sem sujar o tema

Em sites WordPress com Elementor, temas personalizados ou WooCommerce, os secrets não devem ficar em functions.php nem em snippets do page builder.

Padrão recomendado:

• WooCommerce cria o pedido local.
• Um endpoint ou plugin fino chama a API Laravel (gateway).
• Laravel conversa com Yappy / BAC / Paguelo Fácil.
• WordPress reflete o estado quando o backend confirma.

Implementação em Laravel

1. Modelos Order + Payment com estados normalizados.
2. Serviço PaymentGateway com adapters atrás de uma interface.
3. Endpoint protegido para iniciar pagamento: valida carrinho, calcula total, persiste pending.
4. Endpoint de callback/IPN: verifica assinatura, é idempotente, despacha job de conciliação.
5. Página de retorno que consulta o estado no DB; não marca paid por query string.
6. Fila para retentativas quando o banco notifica tarde.
7. Secrets apenas no env do host (Coolify: variáveis do serviço, não .env no Git).

Estados normalizados

Checklist técnico

1. Credenciais apenas em variáveis de ambiente.
2. Sandbox vs produção separados.
3. Idempotência: o mesmo order_id não cria duas cobranças.
4. Persistir payload para auditoria.
5. Validar o que o provedor envia de volta.
6. Jobs para retentativas de conciliação.
7. Logs sem secrets nem dados de cartão.
8. Página de resultado que consulta o backend.
9. Healthcheck e workers ativos no deploy.
10. Runbook de rotação de secrets e reprocessamento de IPN.

Erros frequentes em produção

• Confirmar venda só porque o usuário chegou em /pago-exitoso.
• Deixar o secret em um plugin WordPress versionado no Git.
• Misturar lógica de Yappy, BAC e Paguelo Fácil em um único if gigante.
• Esquecer o caso "usuário pagou e fechou o app" sem callback.
• Deploy com latest e secrets embutidos na imagem Docker.

A integração conecta com Docker, CI/CD e Coolify, auditoria de segurança e pagamentos online .