支付宝支付接入完整指南

一、支付宝支付在小程序中的价值

支付宝在移动支付领域拥有庞大活跃用户，小程序内支付宝支付无需跳转外部浏览器，用户点击付款后在本端完成，转化路径短。对本地生活、零售、出行等场景，支付成功率与收银台体验直接决定 ROI。费率以行业签约为准，常见约 0.6%，到账周期多为 T+1。需要强调的是，支付宝小程序的主支付方式就是支付宝支付，不要照搬微信生态的方案在这里接入微信支付——平台不允许，审核也过不了。

除标准支付外，花呗分期可提升客单价：在合规类目下展示 3/6/12 期等选项，由用户承担或商家贴息需在产品层明确。分期涉及额外产品开通与前端展示规范，需与标准支付一并规划。

二、接入前置条件

• 企业完成支付宝开放平台应用创建与商家认证
• 小程序 AppID 与支付应用绑定
• 签约支付宝支付（电脑/移动/小程序支付产品以实际为准）
• 配置 RSA2 密钥、应用公钥上传、支付宝公钥验签
• HTTPS 生产环境与服务端可公网访问的 notify_url

三、技术流程（小程序支付）

3.1 统一下单

服务端调用支付宝交易创建接口，传入 out_trade_no、total_amount、subject、buyer_id 或 product_code 等参数，获得 trade_no 或 orderStr（视 API 版本与 SDK）。订单号需全局唯一，金额与商品信息需与前端展示一致，否则易触发风控。

3.2 客户端调起支付

小程序端使用 my.tradePay 等官方 API 调起收银台。前端需要处理三类异常：用户主动取消（不应报错，而是保留订单并提示可再次支付）、网络超时（需允许重试并避免重复下单）、重复点击（支付请求发出后立即将按钮置为不可用并显示加载态）。收银台返回后不要立刻跳转结果页，应以服务端查询到的订单状态为准再渲染，否则弱网下容易出现「用户已付但页面显示未付」。

3.3 异步通知与订单状态

支付成功后支付宝 POST 异步通知至 notify_url。服务端必须：验签、幂等更新订单（同一 out_trade_no 多次通知只处理一次）、记录日志。勿仅依赖前端 success 回调作为发货依据。

3.4 退款与对账

实现退款接口以支持售后；每日与支付宝账单对账，发现差异及时排查（常见来源是分账、部分退款与手续费口径）。退款要支持部分退款并记录原始退款单号，避免同一订单多次退款时金额累计超过实付。

四、花呗分期要点

申请分期产品通过后，在下单参数中指定分期期数，或在收银台展示可选期数由用户选择。落地时有三个容易出问题的点。第一是费率承担方：商家贴息与用户自付在前端文案上应写清楚，「3 期免息」与「3 期可分」是完全不同的承诺，写错会引发投诉甚至监管问询。第二是类目准入：部分类目不支持分期，且准入结论可能随平台政策调整，因此代码层面要支持「分期入口可配置开关」，一旦能力被关闭，收银台应自动隐藏分期选项而不是报错。第三是订单模型：分期订单与标准订单建议共用同一套订单表，仅通过支付方式字段区分，这样对账、退款与报表都不需要写两套逻辑。分期退款的手续费与贴息结算规则与普通订单不同，财务口径要在上线前和财务确认一次。

五、安全与合规

• 私钥仅存服务端，禁止写入小程序前端或提交到代码仓库
• 所有金额计算在后端完成，前端传商品 ID 与数量而非价格
• 虚拟商品、预付费需符合类目规则并写明退款路径与有效期
• 配合芝麻信用场景时，支付与信用授权相互分离，授权范围按最小必要原则申请
• 沙箱与生产的密钥、网关、回调地址严格分环境管理，不共用配置文件

除了上述清单，还有两项容易被忽略的合规动作。一是金额与展示一致：下单时传给支付宝的 total_amount 应与用户在详情页看到的实付金额一致，包含优惠后的结果；两者不一致不仅容易触发风控，在客诉时也难以自证。二是用户授权留痕：涉及实名信息、信用授权的场景，应在服务端记录授权时间、授权范围与协议版本号，一旦平台或用户提出问询，能直接给出证据链。密钥管理建议使用云厂商的密钥管理服务而非明文配置，并至少每年轮换一次。

六、常见联调问题排查

调起支付失败：检查 AppID 与商户号绑定、密钥是否匹配环境、订单金额格式（两位小数）。通知不到达：确认 notify_url 公网可达、防火墙放行、返回 success 字符串规范。用户已付订单仍待支付：多为幂等或数据库事务未提交，需以异步通知为准更新状态。

连锁场景可在总部后台做「支付对账日结」，与门店 POS 销售数据比对，差异条目自动告警。看店通交付的项目通常附带对账脚本与运维说明。

七、测试用例清单

联调应覆盖：正常支付、用户取消、余额不足、重复点击支付、弱网中断后返回、回调延迟、重复回调幂等、部分退款、全额退款、超时关单、优惠叠加后实付金额校验。每类用例记录期望订单状态与数据库字段。沙箱与生产各跑一轮；生产用小金额真机验证。若接入花呗分期，额外测试不同期数、贴息与不免息组合。

八、预授权、分账与行业扩展

租赁、酒店押金类场景常用预授权；平台型本地生活可能需分账给门店或服务商，进件时需开通对应产品。分账规则变更会影响对账脚本，应纳入维护范围。与芝麻信用组合时，信用授权失败是否转预授权或押金，须在代码与运维手册中一致。看店通在需求阶段用泳道图区分「标准支付」与「信用/预授权」分支，避免后期补丁式开发。

九、与运营规则联动

支付成功后要触发一串动作：减库存、发券、通知门店 POS、积分到账、推送订单通知。这串动作需要定义明确的执行顺序与失败补偿策略，而不能写成一个「成功即全部完成」的同步方法。建议把强一致的部分（扣库存、改订单状态）放在事务内，把可最终一致的部分（发券、积分、通知）放进消息队列异步执行，并为每类动作准备补偿手段：例如支付成功但发券失败，应自动生成补发任务，同时在客服后台开放一个「手动补券」的工单类型，让一线不必等技术排查。大促前还要确认数据库连接池容量与幂等键索引已经就绪，否则高并发下回调会大面积超时。

十、对账与财务闭环

财务需要日账单与内部订单逐笔对齐，维度包括渠道、门店、支付方式、手续费与退款。看店通可导出对账报表并与支付宝账单勾对。差异的常见原因有三类：跨日回调（支付发生在零点前、回调落在零点后）、部分退款（内部记一笔、账单记两笔）、用户重复支付后系统自动退回。建议大促后 72 小时内完成对账，不要积压到月结才发现缺口——超过一个月再查，日志可能已经轮转清理。

十一、沙箱到生产的切换

沙箱的 AppID、密钥与生产环境应严格分离，不共用同一份配置。切换上线的检查清单至少包含四项：更换支付网关地址、更新应用公钥与支付宝公钥、关闭测试用的回调地址、确认正式回调域名的证书链完整可信。切换窗口选在业务低峰时段，切换完成后立刻做一笔小金额真实支付并当场验证退款，确认收款与退款两条链路都通。若未来业务可能扩展到跨境或外币收款，此时就应评估支付宝国际产品的接入方式与汇率展示规则，首版只做人民币境内支付，但在订单表与金额字段上预留币种扩展位，可以避免日后重构整个收银台。看店通交付时附带《生产切换记录表》模板，逐项签字留痕。

十二、日志与审计

支付相关日志建议保留至少 180 天，内容包括请求参数（敏感字段脱敏）、验签结果、订单状态变迁记录与退款单号，便于处理客诉与监管问询。禁止在日志中记录完整银行卡号、身份证号等敏感信息。看店通默认集成结构化支付日志与检索索引，支持按订单号、手机号后四位、时间区间快速定位。

十三、商户号与主体变更

企业合并、分拆或更换经营主体时，商户号可能需要重新进件，小程序的支付配置也要同步更新。这类切换应提前 30 天规划：先在新主体下完成进件与签约，再通过双跑（新单走新商户号、售后仍走旧商户号）验证一段时间，最后把流量整体切过去，可以降低资金链中断与退款失败的风险。切换期间要特别注意历史订单的退款——用旧商户号收的款仍应从旧商户号退，不宜混用。建议同时把支付联调检查表纳入上线签字文件，财务与运营各留一份，便于日后审计与人员交接。看店通可协助梳理影响面与切换步骤清单。