皓臻支付 - 支付接口怎样对接?支付宝/微信集成

支付接口怎么对接？支付宝与微信集成的完整实操指南

很多团队做支付集成，代码写得飞快，上线后却卡在验签失败、回调丢失、退款对不上账。问题根源在于——支付不是普通的HTTP调用，它是一套带状态、带资金、带对账责任的分布式协作。下面按真实落地顺序讲清楚每一步。💡

一、开工前先把资质和场景确认清楚

资质材料：营业执照、法人身份证、对公结算账户（个体户可用法人账户）、经营场景证明（网站备案信息、App截图、小程序AppID或线下门店照片）。行业类目要如实填，与实际经营不符会在风控环节被拦。

选对支付产品，这一步选错，后面全是返工：

服务商模式还是直连模式？多商户平台必须走服务商（ISV）模式，为每个子商户单独进件、拿子商户号；自营业务走普通商户直连即可。

二、密钥与证书配置（事故高发区）⚠️

微信支付目前主推APIv3：需要商户API证书（apiclient_cert.pem / apiclient_key.pem）、APIv3密钥、以及微信支付平台证书。签名算法为 SHA256-RSA，请求头需携带 Authorization 字段，内含商户号、随机串、时间戳、证书序列号和签名值。平台证书有有效期，必须实现自动定时更新，否则某天凌晨会突然全线验签失败。

支付宝使用 RSA2（SHA256withRSA） 密钥对，可选普通公钥模式或应用公钥证书模式。自己生成密钥对，私钥留在服务端，公钥上传到开放平台。

三条铁律：私钥绝不写进前端；绝不提交到代码仓库；生产与沙箱密钥严格隔离。🔐

三、标准支付流程怎么跑

第一步：本地建单。用户下单后先在自己数据库落一条订单，生成全局唯一的商户订单号（建议：业务前缀 + 时间戳 + 随机位），状态置为"待支付"。不要用支付渠道的单号做主键。

第二步：调统一下单接口。微信调 /v3/pay/transactions/{类型}，支付宝调 alipay.trade.create 或 alipay.trade.page.pay 等。注意金额单位：两家的金额字段都不接受随意的浮点数，微信以「分」为单位传整型，支付宝以「元」为单位、最多两位小数。内部运算一律用整型分或高精度类型，float 迟早出精度问题。

第三步：前端拉起收银台。微信JSAPI返回 prepay_id 后需二次签名，前端调 WeixinJSBridge 或小程序 wx.requestPayment；支付宝App支付返回订单串，交由SDK拉起。

第四步：处理异步通知。这是整套系统最关键的地方，四条不可省略：

• ✅ 验签：不验签等于把订单状态开放给公网任何人修改
• ✅ 解密：微信APIv3的回调报文是加密的，需用APIv3密钥做 AES-256-GCM 解密
• ✅ 幂等：同一笔通知会重复推送多次，用订单号加数据库唯一索引兜底，重复直接返回成功
• ✅ 核对金额：拿通知里的实付金额与本地订单金额逐笔比对，不一致立刻告警并挂起

处理完成后按渠道规范返回响应体（微信返回 200 及 code=SUCCESS，支付宝返回纯文本 success），否则会被持续重推。

第五步：主动查询兜底。网络抖动会导致通知丢失。用定时任务扫描超过一定时间仍未终态的订单，调用查询接口补齐状态，形成双保险。

第六步：每日对账。下载渠道账单，与本地流水逐笔核对，重点盯单边账、金额差异、状态不一致三类。这是财务合规的底线。📊

四、退款与关单不能漏

退款需传原商户订单号或渠道流水号，并生成独立的退款单号。退款同样是异步结果，必须处理退款回调，不能拿接口同步返回就当成功。另外要设置订单超时关单逻辑，避免用户在过期订单上完成支付造成资金悬挂。

五、高频踩坑清单 🔍

• 回调地址必须是公网可访问的 HTTPS 地址，不能带查询参数
• 服务器时间要做NTP同步，时间戳偏差过大直接验签失败
• 签名字段顺序严格按文档，多传少传都会失败
• 日志脱敏：请求响应留档，但身份证、卡号、密钥必须脱敏存储
• 沙箱先行：把下单、支付、查询、退款、关单五个动作全部跑通再切生产

六、合规提醒 🚫

资金必须由持牌机构直接结算至真实商户，不做二次清算、不出借商户号、不为无真实交易背景的资金往来提供通道。技术再完美，触碰清算红线一切归零。

以上是支付宝、微信官方通道的通用集成规范。关于皓臻支付的具体接口字段、SDK版本、费率与对接文档，我没有可核实的一手资料，请直接向其官方索取最新技术文档，并核验其持牌主体或收单外包备案信息后再启动集成。文档版本对不上，写多少代码都是白写。