用户返回页面后，订单仍显示待支付

API支付接口文档常把“创建支付请求”放在开头：商户系统提交订单信息，支付服务返回用于继续付款的数据。但创建请求成功，只表示支付流程已经发起。用户看到付款页面、浏览器跳回商户页面，也不能单独作为发货或开通服务的依据。

文档要把这几个结果分开写清：接口受理了请求，用户完成了支付操作，商户系统确认了最终支付状态。前两者可能很快出现，最后一项却可能受通知送达时间影响。若业务同时接收服务端回调、开放主动查询接口，还要说明两条渠道返回的状态如何对应；否则前端显示“已完成”，后台仍挂着“待支付”，接入方很难判断该等通知还是发起查询。

请求字段也要服务于这条判断链。商户订单号由谁生成、重复提交同一订单号会得到什么结果、金额的单位和格式如何表达，都应在字段旁写明。只标注“必填”无法回答接入时最常见的问题：一次请求超时后，沿用原订单号重试会发生什么。具体规则取决于支付服务的实现，文档不能用“支持重试”一句带过。

同一笔支付收到多次回调

假设某接入方已收到支付成功通知，订单也已更新，但随后又收到内容相同的通知。若回调处理程序每收到一次就执行一次开通操作，同一笔支付便可能触发重复履约。此时要核对的不是用户是否付了两次，而是通知对应的支付单和商户订单，是否已经完成过处理。

回调章节应写到足以让开发人员落地：通知如何验签，订单号、支付状态和金额从哪里读取，以及商户系统用什么规则识别重复通知。验签用于确认通知内容符合平台要求，不能替代订单核对；通知显示成功时，仍要把它与本地订单关联，并核对金额。完成状态写入和业务处理后，再按接口约定返回接收结果。

这类处理还受业务系统自身限制。订单状态已经更新，但开通动作尚未完成时，简单丢弃后续通知可能留下未履约订单；重复执行开通动作又可能产生另一类错误。文档可明确支付服务在未收到有效确认时是否重发通知、重发条件是什么。商户侧则记录每次通知及处理结果，让重复消息能定位到同一笔订单，而不是依赖“回调只来一次”的假定。上述情境停在订单处理设计上，具体如何恢复未完成的业务动作，还要由接入方按自身系统决定。

联调时，文档还缺哪些可核对的信息

当测试环境里出现“接口返回成功，后台没有变更”，开发人员通常会翻三处内容：返回字段表示什么、回调发往哪个地址、查询接口此时会返回什么。文档若给出请求与响应示例，就让示例和字段说明保持一致，区分受理结果与支付结果；错误码写明哪些情形允许沿用原订单重试，哪些需要修正请求内容。不要把所有失败都写成“请稍后重试”，这会让重复下单和状态不明混在一起。

安全要求也要落在可执行的位置。签名参与字段、编码方式、验签步骤及密钥保管方式，应以实际接口规则为准写清；敏感凭证不要放进前端页面或示例仓库。若文档提供测试环境，注明它与正式环境在地址、凭证和通知配置上的区别，避免测试通过后直接照搬配置。

交付文档前，拿一笔测试订单沿着请求、返回、回调和查询走一遍，记录每一步看到的订单号与状态。若某一步需要靠开发人员猜测字段含义，就补齐该处说明；若回调重复到达后的处理仍不明确，就把确认响应与重发约定写到同一章节。