放一个“使用 Yappy 支付”按钮是可见部分。真正避免麻烦的是不可见部分：金额在服务器计算、订单状态清晰，以及客户在支付中途关闭 app 时系统仍知道该怎么做。
本指南描述基于 Laravel 的后端优先模式。若店面是 WordPress 或 WooCommerce，CMS 只做橱窗；敏感逻辑放在主题之外。同一方法适用于 Yappy（Banco General）、BAC Credomatic、Paguelo Fácil 及统一网关。
为何在巴拿马很重要
Yappy 是常用收款方式。设计不良的流程不只是“在 staging 失败”：它会造成幽灵销售、无订单扣款，或支持与财务都无法证明的已付订单。
- 信任：客户需要明确知道是否已付款。
- 运营：团队必须能对账银行与订单，而不是无尽的表格。
- 安全：若由浏览器决定价格，就会被人篡改。
- 可扩展性：明天可能要接 BAC 或 Paguelo Fácil，而不重写整店。
Yappy 的实际运作方式
把 Yappy 想成“数字柜台”：你的服务器请求收款意图，客户在 app 或 redirect 中完成支付，你的系统通过可信渠道收到确认（不只是返回 URL）。
- 在商户门户完成商户注册并获取凭证（
merchantId/ secret）。 - 服务器用正确金额生成支付 URL 或意图。
- 用户在 Yappy 流程中完成支付（app / redirect）。
- Redirect + 端点通知在签名验证后更新订单。
黄金法则：支付从后端发起
在显示按钮之前，服务器必须完成重活：
- 创建或获取订单，包含商品、货币和税费。
- 在服务器端计算总额（绝不信任浏览器 JSON）。
- 以
pending状态保存支付记录，并关联内部order_id。 - 向 Yappy 请求带有这些金额的支付 URL / token。
- 仅向前端返回继续流程所需内容（重定向或最小数据）。
WordPress / WooCommerce：不污染主题
在使用 Elementor、定制主题或 WooCommerce 的站点中，密钥不应放在 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 | 操作超时 |
生产环境常见错误
- 仅因用户访问
/pago-exitoso就确认销售。 - 将 secret 留在已纳入 Git 的 WordPress 插件中。
- 把 Yappy、BAC 和 Paguelo Fácil 的逻辑混在一个巨大的
if里。 - 忽略“用户已付款但关闭 app”且没有可见回调的情况。
- 使用
latest标签部署并将密钥烘焙进 Docker 镜像。 - 不持久化提供商 payload：事后无法审计。
技术检查清单
- 凭证仅存放在环境变量中。
- 沙箱与生产环境分离。
- 幂等性：同一
order_id不创建两笔扣款。 - 持久化 payload 以供审计。
- 验证提供商回传的数据（签名 / 字段）。
- 对账重试任务。
- 日志中不含密钥或卡数据。
- 结果页查询后端状态。
- 部署时 healthcheck 和 worker 正常运行。
- 密钥轮换和 IPN 重处理的 runbook。
本集成与以下主题相关： Docker、CI/CD 和 Coolify、安全审计和在线支付 .