Integrar Yappy e pagamentos no Panamá sem surpresas (Laravel + WordPress)

Colocar um botão “Pagar com Yappy” é a parte visível. O que evita dor de cabeça é o invisível: o valor é calculado no servidor, o pedido tem estados claros, e o sistema sabe o que fazer se o cliente fechar o app no meio do pagamento.

Este guia descreve um padrão backend-first com Laravel. Se a vitrine é WordPress ou WooCommerce, o CMS permanece como escaparate; a lógica sensível fica fora do tema. A mesma abordagem serve para Yappy (Banco General), BAC Credomatic, Paguelo Fácil e gateways unificados.

Por que importa no Panamá

Yappy é uma forma de cobrança muito usada. Um fluxo mal desenhado não só “falha no staging”: gera vendas fantasma, cobranças sem pedido, ou pedidos pagos que ninguém consegue provar para suporte ou contabilidade.

• Confiança: o cliente precisa saber se pagou ou não, sem ambiguidade.
• Operação: a equipe deve reconciliar banco vs pedidos sem Excel eterno.
• Segurança: se o navegador decide o preço, alguém o manipula.
• Escalabilidade: amanhã você pode querer BAC ou Paguelo Fácil sem reescrever a loja.

O que é o Yappy na prática

Pense no Yappy como um “guichê digital”: seu servidor pede uma intenção de cobrança, o cliente completa o pagamento no app ou redirect, e seu sistema recebe a confirmação por um canal confiável (não só pela URL de retorno).

1. Cadastro do comércio e credenciais (merchantId / secret) no portal comercial.
2. O servidor gera URL ou intenção de pagamento com o valor correto.
3. O usuário conclui o pagamento no fluxo do Yappy (app / redirect).
4. Redirect + notificação no endpoint atualizam o pedido após validação de assinatura.

Regra de ouro: o pagamento nasce no backend

Antes de exibir o botão, o servidor deve fazer o trabalho pesado:

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 com esses valores.
5. Devolver ao front apenas o necessário para continuar (redirect ou dados mínimos).

WordPress / WooCommerce sem sujar o tema

Em sites com Elementor, temas sob medida ou WooCommerce, os secrets não devem viver em functions.php nem em snippets do page builder. É como colar a chave do cofre na vitrine.

• 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 (passos)

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

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 visível.
• Deploy com tag latest e secrets embutidos na imagem Docker.
• Não persistir o payload do provedor: impossível auditar depois.

Checklist técnico

1. Credenciais apenas em variáveis de ambiente.
2. Sandbox e 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 (assinatura / campos).
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.

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