Payfort支付网关生产环境真实卡支付流程异常求助

问题背景 #

已完成Payfort自定义页面集成，严格遵循官方文档操作，沙箱环境测试卡支付流程正常，但生产环境真实卡支付出现三类异常：

• 收到支付成功响应，但用户账户金额未实际扣除
• 触发Merchant reference already exists错误
• 触发Failed to execute service错误

生产环境商户账户配置已完成，沙箱环境的凭证信息已迁移至生产环境，技术栈为TypeScript(NodeJS)。

分问题排查与解决 #

1. 成功响应但金额未扣除 #

• 不要仅依赖前端成功提示，必须校验Payfort返回的response_code（官方定义00000为最终成功）和status字段，确认交易真实完成。
• 关键排查动作：
  • 验证回调请求的签名，确保请求来自Payfort官方，避免伪造回调导致误判。
  • 登录Payfort商户后台，直接查看该订单的实际交易状态，排查是否存在回调延迟或未触发的情况。
  • 确认代码中使用的是生产环境API地址，避免误调用沙箱接口导致交易未进入真实清算流程。

2. Merchant reference already exists错误 #

• 核心原因：商户生成的merchant_reference字段重复，Payfort要求该值在生产环境全局唯一。
• 解决措施：
  • 生产环境订单号生成逻辑需与沙箱完全隔离，禁止复用沙箱的订单序列。
  • 检查前端是否存在重复提交场景，后端需添加幂等校验，防止同一订单多次发起支付请求。
  • 若使用数据库存储订单，给merchant_reference字段添加唯一约束，从源头避免重复。

3. Failed to execute service错误 #

• 这类错误多由参数合法性、配置正确性或网络问题导致，按以下步骤排查：
  • 核对生产环境的access_code、merchant_identifier、sha_request_phrase等凭证，确保与Payfort后台完全一致，注意大小写、特殊字符无遗漏或错误。
  • 检查请求参数格式：比如金额需为最小货币单位的整数（如100迪拉姆需传10000），currency必须是Payfort生产环境支持的币种。
  • 测试服务器到Payfort生产API的网络连通性，排查是否被防火墙或代理拦截，可执行以下命令验证：

    curl -v https://paymentservices.payfort.com/FortAPI/paymentApi
    

  • 查看Payfort商户后台的错误日志，获取更详细的错误详情（如参数非法、权限不足等）。

通用排查建议 #

• 对比沙箱与生产环境的请求参数，除凭证和API地址外，确保其他参数（如command、customer_email等）格式完全一致。
• 在代码中添加详细日志，完整打印请求和响应的所有参数，便于对比分析差异。
• 若自行排查无果，直接联系Payfort技术支持，提供异常订单的fort_id或merchant_reference，获取官方的交易排查结果。

内容的提问来源于stack exchange，提问作者Aamir Abid