虎咚支付宝支付

📋 服务说明

服务目的：

本微服务用于避免重复开发支付宝集成，是无数据库存储的接口转发应用，对上层业务屏蔽支付宝签名细节。

退款对接说明：

如需使用退款功能，请先联系平台管理员配置退款相关权限和通道。

项目	说明
公网服务域名	https://alipay.hudongbot.com
内网服务地址	由平台分配提供
请求格式	Content-Type: application/json
响应格式	application/json

⚠️ 安全规范

🔒 我们已做到（服务端已实现）

私钥仅在服务端：所有支付签名、回调验签全部在服务端完成
私钥不记日志：私钥不会出现在任何日志中
异步通知先验签：收到支付宝通知后先验签再处理

📋 接入方需要做到

私钥禁止存客户端：构造交易数据并签名必须在你的服务端完成，私钥绝对不能保存在你的APP客户端中
前台支付结果不可信：前台同步跳转结果不可信，必须以支付宝异步通知或调用交易查询接口获取结果为准
未确认不重付：在未确认支付结果前，不能要求用户再次付款，必须先通过异步通知或查询接口确认支付结果
AK/SK 妥善保管：Access Key、Secret Key 请妥善保管，不要泄露

🔄 支付流程说明

三方应用集成流程

获取凭证：从平台获取 Access Key (ak)、Secret Key (sk)、以及渠道标识 (channel)
选择网络：根据业务需要选择使用公网地址或内网地址发起请求（内网地址由平台提供）
构造请求：构造包含认证信息和业务信息的请求体，确保：
- outTradeNo 必须以 {channel}_ 开头
- 金额单位为分（正整数）
计算签名：使用 SHA256 算法计算 sign = SHA256(channel + ak + sk + timestamp)
发起支付：POST 请求发送到 /payment 接口
获取支付链接/参数：根据不同的 payType，获取对应的支付链接或参数
用户支付：引导用户在浏览器/APP/小程序内完成支付
接收结果：支付服务接收支付宝回调，然后转发到你的 notifyUrl（支持内/外网）

📡 回调转发机制

双网络支持：

支付服务同时支持公网和内网调用，你的 notifyUrl 无论是公网地址还是内网地址都能正常工作！

回调流程：

支付宝回调支付服务的公网回调接口
支付服务验签成功后，转发回调通知到你的 notifyUrl
不管你的 notifyUrl 是公网还是内网都没问题

🔐 安全认证 — AK/SK 签名

所有业务接口请求需在请求体中携带认证字段。请从平台获取 Access Key (ak)、Secret Key (sk)、以及渠道标识 (channel)。

参数名	类型	必填	说明
channel	string	必填	渠道标识，从平台获取
ak	string	必填	Access Key，从平台获取
sk	string	必填	Secret Key，从平台获取
timestamp	string	必填	毫秒级时间戳，允许误差范围 5 分钟
sign	string	必填	SHA256(channel + ak + sk + timestamp)，结果为小写 hex

签名算法说明：

待签名串 = channel + ak + sk + timestamp，字符串拼接后取 SHA256，结果为小写十六进制

签名算法示例（Node.js）

const crypto = require('crypto');
const channel = 'your_channel';
const ak = 'your_ak';
const sk = 'your_sk';
const timestamp = String(Date.now());
const sign = crypto.createHash('sha256')
  .update(channel + ak + sk + timestamp)
  .digest('hex');
          

签名算法示例（Python）

import hashlib
import time
channel = 'your_channel'
ak = 'your_ak'
sk = 'your_sk'
timestamp = str(int(time.time() * 1000))
sign = hashlib.sha256((channel + ak + sk + timestamp).encode()).hexdigest()
          

📦 订单接口

💳 发起支付 POST /payment

请求参数

参数名	类型	必填	说明
channel	string	必填	渠道标识，由平台分配
ak	string	必填	Access Key，由平台分配
sk	string	必填	Secret Key，由平台分配
timestamp	string	必填	毫秒级时间戳
sign	string	必填	SHA256(channel + ak + sk + timestamp)
payType	string	必填	支付方式：pc / h5 / app / jsapi / qr
amount	string	必填	支付金额，单位：分，必须为正整数
subject	string	必填	订单标题
outTradeNo	string	必填	商户订单号，必须以 {channel}_ 开头
notifyUrl	string	可选	异步回调地址
returnUrl	string	可选	同步跳转地址，仅 pc / h5 有效
buyerId	string	可选	买家支付宝 user_id，jsapi 支付时必填

请求示例

{
  "channel": "your_channel",
  "ak": "your_ak",
  "sk": "your_sk",
  "timestamp": "1715000000000",
  "sign": "xxx",
  "payType": "pc",
  "amount": "100",
  "subject": "订单标题",
  "outTradeNo": "your_channel_1715000000000",
  "notifyUrl": "https://example.com/notify"
}

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "payUrl": "https://openapi.alipay.com/gateway.do?xxx"
  }
}

⚠️ 重要提示：

1. 金额单位为分，必须为正整数字符串
2. outTradeNo 必须以 {channel}_ 开头
3. 建议优先使用内网地址进行请求

🔍 查询订单 POST /payment/query

接口信息

项目	说明
接口地址	POST /payment/query
鉴权方式	请从平台获取 Access Key (ak)、Secret Key (sk)、以及渠道标识 (channel)
网络访问	支持内网和外网

请求参数

参数名	类型	必填	说明
channel	string	必填	渠道标识
ak	string	必填	Access Key
sk	string	必填	Secret Key
timestamp	string	必填	毫秒时间戳
sign	string	必填	SHA256(channel + ak + sk + timestamp)
outTradeNo	string	必填	商户订单号

响应字段

字段名	说明
code	状态码，0 为成功
msg	状态信息
data	订单数据，包含 tradeStatus, alipayTradeNo 等

重要说明：

查询接口返回的是支付宝实时订单状态，结果真实可靠，建议优先使用内网地址查询

🚫 关闭订单 POST /payment/close

接口信息

项目	说明
接口地址	POST /payment/close
鉴权方式	请从平台获取 Access Key (ak)、Secret Key (sk)、以及渠道标识 (channel)

请求参数

参数名	类型	必填	说明
channel	string	必填	渠道标识
ak	string	必填	Access Key
sk	string	必填	Secret Key
timestamp	string	必填	毫秒时间戳
sign	string	必填	SHA256(channel + ak + sk + timestamp)
outTradeNo	string	必填	商户订单号

� 退款接口（两步式退款）

重要说明：

退款接口需要单独配置权限。请先联系平台管理员开通退款权限。

🔐 退款鉴权说明

退款接口使用与普通接口相同的认证参数，验签方式相同：

参数名	类型	必填	说明
channel	string	必填	渠道标识，从平台获取
ak	string	必填	Access Key，从平台获取
sk	string	必填	Secret Key，从平台获取
timestamp	string	必填	毫秒时间戳
refund_sign	string	必填	退款签名：SHA256(channel + ak + sk + timestamp)

🔄 两步退款流程

预校验：调用 /alipay/refund/precheck 校验退款规则，获取 precheckToken
执行退款：携带 precheckToken 调用 /alipay/refund/execute 执行真实退款

📋 退款预校验 POST /alipay/refund/precheck

参数名	类型	必填	说明
channel	string	必填	渠道标识，从平台获取
ak	string	必填	Access Key，从平台获取
sk	string	必填	Secret Key，从平台获取
timestamp	string	必填	毫秒时间戳
refund_sign	string	必填	SHA256(channel + ak + sk + timestamp)
outTradeNo	string	必填	商户订单号
refundAmount	string	必填	退款金额，单位：分
outRequestNo	string	必填	退款请求号

预校验响应示例

{
  "code": 0,
  "msg": "ok",
  "precheckToken": "eyJkYXRhIjp7...",
  "needCheck": false,
  "refundableAmount": 100
}

⚡ 执行退款 POST /alipay/refund/execute

参数名	类型	必填	说明
channel	string	必填	渠道标识，从平台获取
ak	string	必填	Access Key，从平台获取
sk	string	必填	Secret Key，从平台获取
timestamp	string	必填	毫秒时间戳
refund_sign	string	必填	SHA256(channel + ak + sk + timestamp)
precheckToken	string	必填	预校验接口返回的 token
outTradeNo	string	必填	商户订单号（必须与预校验一致）
refundAmount	string	必填	退款金额（必须与预校验一致）
outRequestNo	string	必填	退款请求号（必须与预校验一致）

执行退款响应示例

{
  "code": 0,
  "msg": "ok",
  "refundNo": "2026050422001498661234567890",
  "outTradeNo": "hd_1715000000000",
  "outRequestNo": "refund_123",
  "tradeStatus": "REFUND_SUCCESS"
}

⚠️ 退款注意事项：

1. precheckToken 有效期 5 分钟
2. 执行退款时的参数必须与预校验时完全一致
3. 退款金额不能超过可退金额
4. 部分渠道可能不允许部分退款，预校验时会检查

� 回调接口

支付宝异步回调 POST /payment/notify

说明：该接口由支付宝调用，用于接收支付结果通知，然后支付服务会转发通知到你的 notifyUrl。

notifyUrl 配置方式（二选一）：

方式一（推荐）：请求时传入
在发起支付请求时，通过 notifyUrl 参数传入你的回调地址，该地址会保存在 passback_params 中。

方式二：环境变量配置
通过环境变量 NOTIFY_URLS 配置，格式：channel1:url1,channel2:url2
例如：hdpay:https://example.com/notify

接收回调要求：

1. 请确保你的 notifyUrl 可以正常接收 POST 请求
2. 处理完成后，返回字符串 "success"（必须），否则支付宝会不断重试
3. 建议收到回调后，主动调用查询订单接口获取真实状态

❌ 错误码说明

code	说明	处理建议
0	成功	-
400	请求参数错误	检查必填参数是否完整
401	签名验证失败	检查 AK/SK 是否正确
403	渠道无退款权限	联系平台管理员开通退款权限
404	渠道配置不存在	检查 channel 是否正确
500	服务内部错误	联系平台排查问题

🐯 虎咚支付宝支付

📋 服务说明

⚠️ 安全规范

🔄 支付流程说明

三方应用集成流程

📡 回调转发机制

🔐 安全认证 — AK/SK 签名

签名算法示例（Node.js）

签名算法示例（Python）

📦 订单接口

💳 发起支付 POST /payment

请求参数

请求示例

响应示例

🔍 查询订单 POST /payment/query

接口信息

请求参数

响应字段

🚫 关闭订单 POST /payment/close

接口信息

请求参数

� 退款接口（两步式退款）

🔐 退款鉴权说明

🔄 两步退款流程

📋 退款预校验 POST /alipay/refund/precheck

预校验响应示例

⚡ 执行退款 POST /alipay/refund/execute

执行退款响应示例

� 回调接口

支付宝异步回调 POST /payment/notify

❌ 错误码说明