巴基斯坦支付通道 API 对接指南：获准接口的鉴权、回调与幂等设计

面向巴基斯坦市场建设支付系统时，涉及 JazzCash、Easypaisa 的业务需求不能直接等同于可用的 API 能力。真正可靠的巴基斯坦支付通道对接，应从客户已经获准使用的商户接口出发，明确交易权限、认证规则和状态查询方式，再设计订单流程。

支付 API 对接不仅是发送请求，更要确保超时不误判、通知不被伪造、重试不重复扣付。本文提供一套实施框架；具体字段、算法和业务能力，均以客户所持接口的正式文档及授权范围为准，不代表任何品牌已与 BD Payment 建立合作或完成接入。

一、对接前先核实接口与业务权限

获准商户接口应具有明确的提供方、商户身份及允许使用的业务范围。测试凭证不等于生产权限，收款权限也不能自动推导出付款或退款权限。

• 业务范围：确认允许的交易类型、币种、商户主体及使用场景。
• 技术资料：准备版本化文档、测试环境、生产地址、凭证申请与轮换流程。
• 交易闭环：核实创建订单、查单、回调、账单获取等接口是否可用。
• 字段规则：确认金额单位、精度、时区、订单号长度及错误码定义。

涉及当地监管、数据处理或业务资质要求，应按自身业务模式向巴基斯坦当地专业人士核实，不能仅凭接口可调用判断业务是否合规。

二、API 鉴权：以服务端凭证和最小权限为基础

严格遵循接口规定的认证方式

不同提供方可能使用令牌、请求签名或证书认证。不要自行替换算法，也不要假设涉及不同钱包的接口采用相同规则。签名字段顺序、字符编码、空值处理和请求体序列化必须与文档一致。

密钥应保存在服务端的受控密钥存储中，不得写入网页、移动端包、代码仓库或普通日志。测试与生产凭证分别管理，并建立轮换、吊销和访问审计机制。

区分上下游鉴权边界

商户调用软件平台的凭证，与平台调用客户通道的凭证应分离。平台根据已认证身份确定商户和租户，不能仅相信请求体内填写的商户编号。若接口支持时间戳、随机数或请求有效期，应按其规则校验并防止重放；这些控制不能替代业务幂等。

三、支付回调验签：先验证，再更新订单

回调是交易通知入口，不是天然可信的结果。浏览器跳转页或前端显示的成功提示，也不应直接触发发货、余额增加或付款完成。

1. 保留验签输入：按文档获取原始请求体、请求头和签名，避免解析后重新序列化导致验签失败。
2. 验证通知来源：使用规定算法和可信密钥验签，并执行接口支持的时效、防重放检查。IP 白名单只能作为辅助。
3. 校验业务对应关系：核对商户、订单号、通道流水号、金额和币种，异常通知转入查单或人工处理。
4. 可靠保存事件：通知持久化成功后，再按文档返回确认响应；后续处理必须支持去重和失败重试。

处理重复或乱序回调时，应通过状态机和数据库条件更新防止重复记账。普通旧通知不应把已成功订单退回处理中；退款、撤销等后续变化则应建立明确事件规则。签名有效但状态冲突时，仍需查单核实。

四、幂等请求：让一次业务动作只生效一次

网络重试、用户连点和任务重启都可能产生重复请求。建议为每次独立的收款、付款或退款动作生成稳定的幂等键，同一动作的重试沿用原键，新动作使用新键。

• 限定作用域：结合租户、商户和操作类型建立幂等唯一约束。
• 绑定请求内容：保存金额、币种、业务订单等关键参数摘要；同键不同参数应拒绝。
• 控制并发：以数据库唯一约束、事务或原子状态更新保证一致性，而非只依赖内存锁。
• 保存处理结果：重复请求返回既有结果或处理中状态，不重新发起交易。

若上游支持幂等，应使用其规定的字段并确认有效期；不支持时，本地幂等只能控制本系统重复调用，不能单独保证上游不重复执行。幂等记录保留期限应覆盖重试、回调及补偿窗口，防止记录过早清理。

五、接口超时处理：把未知状态留给查单

超时表示没有及时收到响应，不等于交易失败。上游可能已经受理，尤其在付款场景，直接重发或切换另一通道可能造成重复出款。

1. 调用前落库业务订单、请求标识和幂等键。
2. 发生连接中断或读取超时后，将订单置为待确认状态。
3. 使用原订单标识查单，结合回调确认结果，并采用有上限的退避策略。
4. 只有依据接口规则确认可以安全重试后，才重新提交；超过处理时限的订单进入人工核查。

一次“未查到”未必代表未受理，还需考虑上游处理延迟。多通道管理应区分提交前路由与提交后补偿，不宜把未知交易当作失败订单自动切换。持续利用账单与本地流水对账，发现漏单、重复记录和金额差异。

六、部署选型与上线验收

BD Payment 提供支付系统软件租赁、部署和技术/API 对接，可评估独立部署或多租户部署，以及标准或定制 API 对接。软件功能可围绕订单、商户、代收付流程、多通道管理、自动订单匹配、财务对账、风险管理、代理商、报表、权限和交易查询进行配置。

客户使用自己的支付通道。BD Payment 不提供银行账户、电子钱包账户、支付通道、牌照或监管授权。软件具备某类流程管理功能，不代表客户已经取得对应交易权限。

上线前应测试签名错误、金额不符、重复与乱序回调、并发请求、超时后成功、凭证失效及服务重启等场景。多租户部署还需验证凭证、订单、日志和操作权限的隔离，确保交易全链路可追踪。

小结

巴基斯坦支付通道对接的关键，是用获准接口建立可信交易闭环：鉴权限定调用身份，验签验证通知，幂等限制重复执行，查单与对账解决未知状态。先确认权限和接口能力，再制定状态机及异常处理规则，比单纯追求快速上线更稳妥。

FAQ

1. 有 JazzCash 或 Easypaisa 账户就能对接 API 吗？

不能据此判断。应向对应提供方确认商户接口申请条件、生产权限和允许使用的业务范围，普通账户不应被视为 API 授权。

2. 回调验签通过后可以直接记账吗？

还需检查订单归属、金额、币种和当前状态，并执行去重与原子更新，避免合法通知被重复处理。

3. 接口超时后可以更换订单号重试吗？

不宜直接这样做。新订单号可能绕过原有去重机制，应先查询原交易并按上游规则确认安全重试条件。

4. 没有上游幂等接口怎么办？

加强本地唯一约束、并发控制和查单补偿。对于结果未知的请求，尤其付款请求，避免盲目重发，必要时交由人工核查。

5. BD Payment 是否提供支付通道或钱包账户？

不提供。BD Payment 提供软件租赁、部署及技术/API 对接，客户需自行取得并提供获准使用的支付通道及接口资料，具体对接方案需经过技术评估。