在巴拿马商户中集成 Yappy，远不止添加一个支付按钮。你需要清晰的流程、在服务器端签名的金额、能在用户中断后仍然保留的状态，以及能够解释订单为何已付或未付的后端。
本文介绍基于 Laravel 的后端优先模式；当前端是 WordPress 或 WooCommerce 时，将 CMS 作为展示和结账界面，把敏感逻辑移出主题。适用于 Yappy、BAC Credomatic、Paguelo Fácil 及统一网关的集成。
Yappy 的实际运作方式
Yappy（Banco General）是巴拿马广泛使用的收款方式。典型商业集成流程：
- 在商户门户完成商户注册并获取凭证（
merchantId/ secret）。 - 由服务器生成支付 URL 或支付意图。
- 用户在 Yappy 流程中完成支付（app / redirect）。
- 系统通过 redirect + 端点通知接收结果并更新订单。
黄金法则：支付从后端发起
在前端显示按钮之前，服务器必须：
- 创建或获取订单，包含商品、货币和税费。
- 在服务器端计算总额（绝不信任浏览器 JSON）。
- 以
pending状态保存支付记录，并关联内部order_id。 - 向 Yappy 请求带有这些金额的支付 URL / token。
- 仅向前端返回继续流程所需的信息或重定向。
WordPress / WooCommerce：不污染主题
在使用 Elementor、定制主题或 WooCommerce 的 WordPress 站点中，密钥不应放在 functions.php 或页面构建器代码片段里。
推荐模式：
- WooCommerce 创建本地订单。
- 轻量端点或插件调用 Laravel API（网关）。
- Laravel 与 Yappy / BAC / Paguelo Fácil 通信。
- 后端确认后，WordPress 同步状态。
Laravel 实现
- 带规范化状态的
Order+Payment模型。 - 带接口适配器的
PaymentGateway服务。 - 受保护的支付发起端点：验证购物车、计算总额、持久化
pending。 - 回调/IPN 端点：验证签名、保证幂等、分发对账任务。
- 返回页查询数据库状态；不根据 query string 标记
paid。 - 银行延迟通知时的重试队列。
- 密钥仅存在于主机环境变量中（Coolify：服务变量，而非 Git 中的
.env）。
规范化状态
| 内部状态 | 含义 |
|---|---|
pending | 已创建意图；尚无可靠确认 |
paid | 通过回调/签名验证确认收款 |
rejected | 被提供商拒绝 |
cancelled | 用户中止 |
expired | 操作超时 |
技术检查清单
- 凭证仅存放在环境变量中。
- 沙箱与生产环境分离。
- 幂等性：同一
order_id不创建两笔扣款。 - 持久化 payload 以供审计。
- 验证提供商回传的数据。
- 对账重试任务。
- 日志中不含密钥或卡数据。
- 结果页查询后端状态。
- 部署时 healthcheck 和 worker 正常运行。
- 密钥轮换和 IPN 重处理的 runbook。
生产环境常见错误
- 仅因用户访问
/pago-exitoso就确认销售。 - 将 secret 留在已纳入 Git 版本控制的 WordPress 插件中。
- 把 Yappy、BAC 和 Paguelo Fácil 的逻辑混在一个巨大的
if里。 - 忽略"用户已付款但关闭 app"且没有回调的情况。
- 使用
latest部署并将密钥烘焙进 Docker 镜像。
本集成与以下主题相关： Docker、CI/CD 和 Coolify、安全审计和在线支付 .