孟加拉支付通道技术对接：bKash、Nagad 商户支付 API 文档核验与接口设计

对接孟加拉支付通道，难点不只是发送请求并取得响应。商户是否具备接入资格、文档是否适用于当前产品、超时后如何确认交易结果，都会影响系统能否可靠运行。围绕 bKash 商户支付 API 与 Nagad 商户支付 API，项目应先核验接入依据，再设计交易流程，避免把测试成功误认为正式可用。

本文提供技术核验与接口设计框架，不代替两家服务方的现行文档，也不代表已经核验某一版本的接口。接口地址、字段、鉴权方式及开放能力，应以客户从服务方官方或可核实授权渠道取得的资料为准。

一、商户接入资格确认：先确认能接什么

拥有钱包账户，不等于已经获得商户支付 API 权限。开发前应由客户与对应服务方确认商户主体、业务场景、产品权限及上线要求，再确定技术范围。

• 主体与场景：申请主体、实际经营业务、收款用途是否符合对应产品的接入要求。
• 能力与权限：创建支付、查询、退款或付款等能力是否分别开放，不能由收款权限推定其他权限。
• 环境与凭证：是否获得适用的测试及生产资料，密钥、商户标识和环境是否正确对应。
• 上线条件：是否需要域名登记、回调配置、网络限制、联调或其他验收。

以上项目是待确认清单，并非断言 bKash 与 Nagad 采用相同要求。涉及监管、跨境用途或资金业务安排时，客户应按自身业务模式向当地专业人士核实。

二、支付接口文档核验：建立可追溯的依据

核对来源、版本与适用产品

对 bKash 商户支付 API 和 Nagad 商户支付 API 分别建立资料档案，记录来源、获取日期、版本及适用产品。第三方教程可以帮助理解，但不能替代正式接入依据。示例代码与文档冲突时，应向服务方确认，而不是通过生产交易反复试错。

把文档整理成接口核验表

• 请求约束：环境地址、方法、内容类型、必填字段、金额单位、精度及编码规则。
• 鉴权规则：凭证生命周期、令牌刷新、签名原文、字段顺序及密钥更新方式，以适用文档为准。
• 业务语义：受理、处理中、成功、失败及未知结果如何区分，不能仅凭 HTTP 状态判断。
• 异常处理：超时、限流、重复请求、查询间隔与重试规则。
• 通知机制：是否提供异步通知、如何验证来源、怎样确认接收及处理重复通知。

尚未明确的内容应标记为待确认项，并进入上线检查清单。尤其不能把某一通道的字段、加密算法或通知应答格式直接套用到另一通道。

三、接口设计：统一业务模型，保留通道差异

用适配层隔离具体 API

业务系统可定义内部支付创建、查询和通知处理接口，由通道适配层转换为各自支持的请求。统一的是内部语义，不是强行让所有通道拥有相同能力。未开放的功能应明确返回不支持，避免用模拟流程冒充真实退款或付款。

建议分别保存商户业务订单号、内部支付单号、支付尝试记录及通道交易号。金额使用精确十进制或文档规定的整数单位，避免浮点误差；币种、商户归属和通道配置也应随订单留存，便于查询与对账。

以状态机处理不确定结果

内部状态可设计为待支付、处理中、成功、失败、关闭及结果待确认，再通过映射表对应通道状态。请求超时只表示本次通信未取得确定结果，不代表扣款失败。系统应进入待确认流程，按文档允许的方式查询或人工核查，避免立即重新发起支付。

四、支付回调验签与 API 幂等处理

验证来源，也验证交易内容

支付回调验签应严格遵循相应产品的文档：若提供签名机制，应按指定算法与原文规则验证；若采用其他通知认证机制，则按实际规则实施，不能自行假设算法。浏览器返回页、跳转参数和用户截图都不应单独作为支付成功依据。

验证通知后，还需核对商户、订单、金额、币种及交易关联关系。时间戳、随机数等防重放字段若受文档支持，应一并检查。通知先可靠持久化，再按规定格式应答，并将发货等业务动作异步执行；通知语义不足以确认最终状态时，使用获准的查询接口复核。

幂等必须覆盖请求和业务动作

API 幂等处理不能只依赖一个请求字段。内部可按租户、商户及业务订单号建立唯一约束，并保存关键参数摘要：重复请求返回已有结果，同一幂等标识携带不同金额等关键参数时应拒绝。通道若支持幂等机制，再按其规则传递，不能假定所有接口都支持。

重复回调、查询补单和人工处理可能并发发生，应通过数据库事务、唯一约束或条件更新控制状态迁移，让成功事件只触发一次。单次调用失败或超时，不应覆盖已经确认的成功记录。

五、联调验收与对账：不仅测试成功路径

1. 异常测试：覆盖超时、重复提交、通知延迟、通知乱序、鉴权失败及金额不一致。
2. 补偿测试：验证通知缺失时的查询、人工复核及防重复入账流程。
3. 对账测试：将内部订单与客户实际可取得的交易记录或对账资料比对，标记缺单、重复记录和金额差异。
4. 安全检查：隔离测试与生产凭证，落实密钥保护、日志脱敏、最小权限及操作审计。
5. 上线预案：明确异常告警、暂停入口、配置回退与未决订单处理责任。

自动订单匹配应优先使用稳定交易标识，金额和时间只作辅助条件，不能仅因同额同时间就认定为同一笔交易。支付成功、内部记账完成与资金结算也应分别记录；结算状态只能依据客户实际获得的通道资料确认。

六、BD Payment 的软件服务与责任边界

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

客户使用自己的支付通道。BD Payment 不提供银行账户、电子钱包账户、支付通道、牌照或监管授权。代收付流程等软件功能不代表提供资金服务；具体对接范围须依据客户已有资格、接口权限及文档评估，不构成与 bKash、Nagad 已有合作或已完成接入的声明。

小结

可靠的孟加拉支付通道对接，应依次完成资格确认、文档核验、状态与幂等设计、通知验证及对账验收。先把未知条件列清楚，再推进开发，才能减少重复支付、错误入账和上线后返工。

常见问题 FAQ

1. 有 bKash 或 Nagad 钱包账户就能调用商户 API 吗？

不能据此判断。需要向对应服务方确认商户产品资格、API 权限及正式接入条件。

2. 两家的 API 可以共用一套代码吗？

订单模型、权限和对账框架可以复用，但鉴权、字段、状态与通知处理应分别适配。

3. 创建支付超时后可以直接重试吗？

不宜盲目重试。应先保留待确认状态，依据文档的幂等与查询规则确认原请求结果。

4. 回调验证通过就能直接发货吗？

还须核对交易内容与最终状态，并以幂等方式执行发货。验证通过并不自动证明订单已支付成功。

5. BD Payment 能提供通道或商户账户吗？

不能。客户自行取得账户、通道及接入权限，BD Payment 提供约定范围内的软件、部署和技术/API 对接服务。