前端对接Django支付接口开发关键注意事项

在前后端联调支付场景时，前端Vue/原生UI对接Django后端支付接口存在大量容易踩坑的细节，支付属于资金敏感业务，严禁随意调试，现将核心开发、安全、联调规范整理如下：

一、接口基础交互规范

1. 请求方式严格约定

统一使用POST请求发起支付下单，禁止GET携带订单参数。Django后端CSRF防护机制开启状态下，前端请求必须携带 X-CSRFToken 请求头；若前后端分离项目关闭CSRF，需要在后端配置白名单，不可随意关闭全局防护。

2. 订单参数脱敏传递

前端仅向上传递商品编号、购买数量、支付渠道，禁止前端直接传递订单金额。商品价格、实付金额统一由Django后端数据库核算返回，杜绝前端篡改金额造成资金损失。

3. 统一响应格式

后端约定标准返回结构：code状态码、msg提示、data业务数据。支付唤起参数、二维码链接、支付跳转地址统一放置在data内；前端不可依靠文字弹窗判断业务结果。

二、支付链路核心逻辑重点

1. 统一下单异步逻辑

前端发起下单请求后，后端调用第三方支付平台创建订单，同步返回支付凭证。前端不要同步轮询订单状态，推荐两种方案：

方案1：前端短间隔定时请求【订单状态查询接口】；

方案2：后端对接支付平台官方回调通知，支付完成后更新订单状态，前端 Websocket 推送订单结果。

2. 商户回调通知重中之重

微信/支付宝支付回调属于异步通知，Django后端必须单独开放回调接口。

开发关键：回调接口不能携带登录鉴权，第三方平台无法携带前端登录Token；需要依靠商户订单号完成订单校验，严禁依赖用户登录状态判定订单归属。

Django路由配置必须允许外网访问，同时做好验签操作，防止伪造回调请求。

三、前端页面交互风控细节

1. 支付按钮防重复提交

用户短时间连续点击支付按钮会重复创建多笔订单。前端必须增加防抖锁，发起请求后立即禁用支付按钮，支付结果返回后再解除限制。

2. 支付场景状态管控

支付页面存在多种状态：待支付、支付中、支付成功、支付超时、订单关闭。

页面路由跳转严格拦截：订单未完成支付时，禁止随意返回上一页；微信小程序、H5支付禁止用户主动关闭页面直接退出。

3. 支付渠道兜底兼容

电脑网页端、移动端H5、APP支付拉起逻辑存在差异。前端需区分场景：扫码支付展示二维码；原生APP拉起支付SDK；H5跳转支付官方页面。

四、Django后端配套开发关键规范

1. 订单幂等设计

同一商品同一用户不可重复生成有效订单。Django下单接口增加数据库唯一约束，同一个主体短时间内相同商品限制创建多笔订单。

2. 资金订单数据库分层

订单数据表独立设计，区分商品订单、支付流水两条数据表。支付流水记录第三方支付单号、交易时间、手续费；不能仅依靠商品订单记录资金流水。

3. 支付证书与密钥安全

微信支付商户证书、支付私钥禁止硬编码写在Django项目代码中，推荐放置环境变量、云密钥托管平台。禁止把密钥上传至Git仓库。

4. 订单超时自动关闭机制

Django定时任务（Celery）定期扫描超时未支付订单，自动关闭订单、释放库存。前端同步展示订单剩余支付时长。

五、联调与测试规范

1. 沙箱环境优先调试

优先使用支付平台测试沙箱，严禁直接对接线上正式商户环境。支付退款、资金分账全部在沙箱完成全链路测试。

2. 异常场景完整覆盖

前端必须处理全部异常情况：网络中断、支付中途取消、渠道系统异常、订单超时。不可只处理支付成功场景。

3. 日志完整留存

Django后端完整记录下单请求、回调通知全部原始报文，出现资金对账异常可依靠日志溯源排查问题。

六、容易忽略的高频坑点

1. 跨域问题：第三方支付回调域名、前端项目域名、后端服务域名必须完成商户平台备案；

2. 移动端H5支付存在支付原生弹窗限制，无法自主控制支付结果；

3. Django REST框架权限类组件拦截第三方回调请求，需要单独配置豁免；

4. 退款接口独立开发，退款不能依靠前端发起，全部退款操作必须后端后台发起。