tencent cloud

腾讯云超级应用服务

文档腾讯云超级应用服务小程序开发指南服务端小程序支付

小程序支付

下载
聚焦模式
字号
最后更新时间： 2026-06-10 17:31:22

1.查询订单状态

接口描述：

通过订单号查询订单状态

调用方式：GET

请求地址：

/v3/pay/transactions/out-trade-no/:out_trade_no?mchid=xxx

请求 HEADER

参数
是否必填
描述
说明
Authorization
是
签名认证信息
签名参考 签名认证
Content-Type
是
application/json
-

路径参数

属性
类型
必填
说明
out_trade_no
string
是
商户下单时传入的商户系统内部订单号。

查询参数

属性
类型
必填
说明
mchid
string
是
商户下单时传入的商户号。



返回参数

属性
类型
必填
说明
appid
string
是
小程序 id
mch_id
string
是
支付商户号，商户下单时传入的商户号
out_trade_no
string
是
商户订单号，商户下单时传入的系统内部订单号
transaction_id
string
否
支付订单唯一标识，订单支付成功返回
trade_type
string
否
交易类型 JSAPI-小程序支付
trade_state
string
是
交易状态
WAIT_PAY-待支付
SUCCESS-支付成功
CLOSED-订单已关闭
AUTO_CLOSED-订单到期自动关闭
REFUND-已退款
PAY_ERROR-支付失败
bank_type
string
否
银行简码，非银行卡支付类型统一为 OTHERS
attach
string
否
商户数据包，商户下单时传入的自定义数据包，用户不可见，长度不超过256个字符，若下单传入该参数，则订单支付成功后此接口和支付成功回调通知以及交易账单中会原样返回；若下单未传该参数，则不会返回
success_time
string
否
支付完成时间，遵循 rfc3339 标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日；T 字符用于分隔日期和时间部分；HH:mm:ss 表示具体的时分秒；TIMEZONE 表示时区（例如，+08:00 对应东八区时间，即北京时间）
payer
payer
否
订单的支付者信息，订单支付成功后返回
amount
object
否
订单金额信息
amount.payer_total
string
否
订单总金额，单位为分
amount.total
interger
否
用户实际支付金额，整型，单位为分，用户支付金额=总金额-代金券金额。
amount.currency
string
否
货币类型 符合 ISO 4217 标准的三位字母代码
amount.payer_currency
string
否
用户支付币种 符合 ISO 4217 标准的三位字母代码

响应示例

{
    "appid": "mpco56h12e6e52hj",
    "mch_id": "mi_7b0a5e40f9",
    "out_trade_no": "2b695106b888d14328d9",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "trade_type": "JSAPI",
    "trade_state": "SUCCESS",
    "bank_type": "OTHERS",
    "attach": "attach info",
    "success_time": "2025-02-28T10:34:56+08:00",
    "payer": {
        "openid": "o910d4edeee717377adguZS89513"
    },
    "amount": {
        "payer_total": "88800",
        "total": 88800,
        "currency": "USD",
        "payer_currency": "USD"
    }
}

2.关闭订单

接口描述：

商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；
系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。

调用方式：POST

请求地址：

/v3/pay/transactions/out-trade-no/:out_trade_no/close

请求 HEADER

参数
是否必填
描述
说明
Authorization
是
签名认证信息
签名参考 签名认证
Content-Type
是
application/json
-

路径参数

属性
类型
必填
说明
out_trade_no
string
是
商户下单时传入的商户系统内部订单号。

请求参数

属性
类型
必填
说明
mchid
string
是
商户下单时传入的商户号。

返回参数

无

响应示例

无应答包体
204 No Content


3.小程序下单

接口描述：

小程序支付场景，商户需调用该接口在应用支付下单，生成用于调起支付的预支付交易会话标识(prepay_id)。

调用方式：POST

请求地址：

/v3/pay/transactions/jsapi

请求 HEADER

参数
是否必填
描述
说明
Authorization
是
签名认证信息
签名参考 签名认证
Content-Type
是
application/json
-

请求参数

属性
类型
必填
说明
appid
string
是
小程序 id
description
string
是
商品信息描述，长度不超过127个字符
out_trade_no
string
是
商户系统内部订单号，要求6-32个字符内，只能是数字、大小写字母_-|* 且在同一个商户号下唯一
time_expire
string
是
1、定义：支付结束时间是指用户能够完成该笔订单支付的最后时限，并非订单关闭的时间。超过此时间后，用户将无法对该笔订单进行支付。如需关闭订单，请调用关闭订单 API 接口。

2、格式要求：支付结束时间需遵循 rfc3339 标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日；T 字符用于分隔日期和时间部分；HH:mm:ss 表示具体的时分秒；TIMEZONE 表示时区（例如，+08:00 对应东八区时间，即北京时间）
3.参数仅在用户首次下单时可设置，且不允许后续修改，尝试修改将导致错误。
若用户实际进行支付的时间超过了订单设置的支付结束时间，商户需使用新的商户订单号下单，生成新的订单供用户进行支付。若未超过支付结束时间，则可使用原参数重新请求下单接口，以获取当前订单最新的 prepay_id 进行支付。
支付结束时间不能早于下单时间后1分钟，若设置的支付结束时间早于该时间，系统将自动调整为下单时间后1分钟作为支付结束时间。
attach
string
否
商户在创建订单时可传入自定义数据包，该数据对用户不可见，用于存储订单相关的商户自定义信息，其总长度限制在128字符以内。支付成功后查询订单 API 和支付成功回调通知均会将此字段返回给商户，并且该字段还会体现在交易账单中
notify_url
string
是
商户接收支付成功回调通知的地址，需按照 notify_url 填写注意事项规范填写。
amount
object
是
订单金额信息
amount.total
interger
否
用户实际支付金额，整型，单位为分，用户支付金额=总金额-代金券金额。
amount.currency
string
否
货币类型 符合 ISO 4217 标准的三位字母代码
payer
object
是
支付者信息
payer.openid
string
否
用户在商户 appid 下的唯一标识。下单前需获取到用户的 OpenID，详情见 小程序登录
detail
object
是
优惠功能
detail.cost_price
integer
否
订单原价
detail.goods_detail
array[object]
否
单品列表信息
detail.goods_detail.merchant_goods_id
string
否
支付定义的统一商品编号（没有可不传）
detail.goods_detail.goods_name
string
否
商品的实际名称
detail.goods_detail.quantity
integer
是
用户购买的数量
detail.goods_detail.unit_price
integer
是
整型，单位为：分。如果商户有优惠，需传输商户优惠后的单价(例如：用户对一笔100元的订单使用了商场发的纸质优惠券100-50，则活动商品的单价应为原单价-50)

返回参数

属性
类型
必填
说明
prepay_id
string
是
预支付交易会话标识，JSAPI 或小程序调起支付时需要使用的参数，有效期为2小时，失效后需要重新请求该接口以获取新的 prepay_id

响应示例

{
    "prepay_id":"pi173898442419368bhz26jn4rikpwzr1akn"
}

4.支付回调

接口描述：

当用户成功支付订单后，应用支付会通过 POST 的请求方式，向商户预先设置的回调地址支付下单接口传入的 notify_url 发送回调通知，让商户知晓用户已完成支付。

调用方式：POST

请求地址：

下单接口传入的 notify_url

请求 HEADER

参数
描述
说明
Pay-Serial
验签的 SuperAPP 平台证书序列号
验证签名参考 平台证书签名
Pay-Signature
验证签名值
-
Pay-Timestamp
验签的时间戳
-
Pay-Nonce
验签的随机字符串
-

请求参数

属性
类型
必填
说明
id
string
是
回调通知的唯一编号。
create_time
string
是
本次回调通知创建的时间。
格式：遵循 rfc3339 标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日；T 字符用于分隔日期和时间部分；HH:mm:ss 表示具体的时分秒；TIMEZONE 表示时区（例如，+08:00 对应东八区时间，即北京时间）。
示例：2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。
resource_type
string
是
通知的资源数据类型，固定为 encrypt-resource。
event_type
string
是
支付回调通知的类型。
支付成功通知的类型为 TRANSACTION.SUCCESS。
pay_model
string
否
支付银行卡类型，非银行卡为 OTHERS
summary
string
是
应用支付对回调内容的摘要备注，长度限制64
resource
object
是
通知资源数据
resource.original_type
string
是
【原始回调类型】加密前的对象类型，为 transaction。
resource.algorithm
string
是
【加密算法类型】回调数据密文的加密算法类型，目前为 AEAD_AES_256_GCM，开发者需要使用同样类型的数据进行解密。
resource.ciphertext
string
是
【数据密文】Base64 编码后的回调数据密文，商户需 Base64 解码并解密，参考 解密回调报文。
resource.associated_data
string
否
【附加数据】参与解密的附加数据，该字段可能为空。
resource.nonce
string
是
【随机串】参与解密的随机串。

返回参数

属性
类型
必填
说明
ok
string
是
-

响应示例

{
  "ok"
}

数据类型

resource.ciphertext 解密后的数据结构

标准支付回调中 resource.ciphertext 使用 AEAD_AES_256_GCM 解密后，得到如下 JSON 对象（与查询订单返回结构一致）：
属性
类型
必填
说明
appid
string
是
小程序 ID
merchant_id
string
是
商户号
out_trade_no
string
是
商户订单号
transaction_id
string
是
Superapp 侧交易单号
trade_type
string
否
交易类型 JSAPI-小程序支付
trade_state
string
是
交易状态：SUCCESS-支付成功 CLOSED-已关闭 PAY_ERROR-支付失败
bank_type
string
否
银行简码，非银行卡支付统一为 OTHERS
attach
string
否
商户数据包，下单时传入的自定义数据
success_time
string
否
支付完成时间，格式 yyyy-MM-DDTHH:mm:ss+TIMEZONE
payer
object
否
支付者信息
payer.openid
string
否
用户在商户 appid 下的唯一标识
amount
object
否
订单金额信息
amount.payer_total
string
否
用户实际支付金额，单位为分
amount.total
string
否
订单总金额，单位为分
amount.currency
string
否
货币类型，符合 ISO 4217标准的三位字母代码
amount.payer_currency
string
否
用户支付币种

解密后数据示例

{
    "appid": "mpco56h12e6e52hj",
    "merchant_id": "mi_7b0a5e40f9",
    "out_trade_no": "2b695106b888d14328d9",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "trade_type": "JSAPI",
    "trade_state": "SUCCESS",
    "bank_type": "OTHERS",
    "attach": "attach info",
    "success_time": "2025-02-28T10:34:56+08:00",
    "payer": {
        "openid": "o910d4edeee717377adguZS89513"
    },
    "amount": {
        "payer_total": "88800",
        "total": "88800",
        "currency": "USD",
        "payer_currency": "USD"
    }
}

notify_url 填写注意事项

（1）notify_url 需要填写商户自己系统的真实地址，不能填写接口文档或 demo 上的示例地址。
（2）notify_url 必须是以 https://或 http:// 开头的完整全路径地址，并且确保 URL 中的域名和 IP 是外网可以访问的，不能填写 localhost、127.0.0.1、192.168.x.x 等本地或内网 IP。
（3）notify_url 不能携带参数。
常见错误举例：
错误描述
错误示例
URL 中只有域名，缺少具体的路径
http://www.domain.com
URL 不是以 https:// 或 http:// 开头，缺少域名或 IP
./PayNotify.aspx
URL 中填写了本地或者内网 IP
http://127.0.0.1/pay/notify.php
填写了不是 URL 格式的字符串
xxxxxxx，1234567，test
回调处理逻辑注意事项:
notify_url 的代码处理逻辑不能做登录态校验。
商户系统收到支付结果通知，需要在5秒内返回应答报文，否则应用支付认为通知失败，后续会重复发送通知。
同样的通知可能会多次发送给商户系统，商户系统必须能够正确处理重复的通知。如果已处理过，直接给应用支付返回成功。

5.标准支付-申请退款

接口描述：

当交易发生后需要退款时，商户可以通过退款接口将支付金额退还给买家。支持部分退款和全额退款。

调用方式：POST

请求地址：

/spay/refund/refunds

请求 HEADER

参数
是否必填
描述
说明
Authorization
是
签名认证信息
签名参考 签名认证
Content-Type
是
application/json
-

请求参数

属性
类型
必填
说明
merchant_id
string
是
商户 ID
transaction_id
string
否
Superapp 侧交易单号（与 out_trade_no 二选一）
out_trade_no
string
否
商户订单号（与 transaction_id 二选一）
out_refund_no
string
是
商户退款单号，同一商户号下唯一
reason
string
否
退款原因
notify_url
string
否
退款结果通知 URL
amount.refund
integer
是
退款金额，单位为分
amount.total
integer
是
原订单总金额，单位为分
amount.currency
string
是
货币类型，符合 ISO 4217标准的三位字母代码
goods_detail[].merchant_goods_id
string
否
商户侧商品编码
goods_detail[].goods_name
string
否
商品名称
goods_detail[].unit_price
integer
否
商品单价，单位为分
goods_detail[].refund_amount
integer
否
退款金额，单位为分
goods_detail[].refund_quantity
integer
否
退款数量

返回参数

属性
类型
必填
说明
refund_id
string
是
Superapp 侧退款单号
out_refund_no
string
是
商户退款单号
transaction_id
string
是
Superapp 侧交易单号
out_trade_no
string
是
商户订单号
channel
string
是
退款渠道：ORIGINAL-原路退款 BALANCE-退回余额 OTHER_BALANCE-退到其他余额账户 OTHER_BANKCARD-退到其他银行卡
user_received_account
string
是
退款入账账户
success_time
string
否
退款成功时间，状态为 SUCCESS 时返回，格式 yyyy-MM-DDTHH:mm:ss+TIMEZONE
create_time
string
是
退款创建时间
status
string
是
退款状态：PROCESSING-处理中 SUCCESS-成功 CLOSED-关闭 ABNORMAL-异常
amount.total
integer
是
订单总金额，单位为分
amount.refund
integer
是
退款金额，单位为分
amount.payer_total
integer
是
用户支付金额，单位为分
amount.payer_refund
integer
是
用户退款金额，单位为分
amount.currency
string
是
货币类型

响应示例

{
    "refund_id": "rf17389154493510001",
    "out_refund_no": "refund_2b695106b888",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "支付用户零钱",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "PROCESSING",
    "amount": {
        "total": 88800,
        "refund": 44400,
        "payer_total": 88800,
        "payer_refund": 44400,
        "currency": "USD"
    }
}

6.虚拟支付-申请退款

接口描述：

虚拟支付场景的退款申请。使用虚拟支付签名验证(access_token + pay_sig)，请求参数增加 openid 和 req_from 字段。

调用方式：POST

请求地址：

/vpay/refund/refunds?access_token={access_token}&pay_sig={pay_sig}

请求 HEADER

参数
是否必填
描述
说明
Content-Type
是
application/json
-

请求参数

属性
类型
必填
说明
mch_id
string
是
商户 ID
openid
string
是
下单时的用户 openid
transaction_id
string
否
Superapp 侧交易单号（与 out_trade_no 二选一）
out_trade_no
string
否
商户订单号（与 transaction_id 二选一）
out_refund_no
string
是
商户退款单号，唯一标识一笔退款
reason
string
否
退款原因
notify_url
string
否
退款结果通知 URL
amount.refund
integer
是
退款金额，单位为分
amount.total
integer
是
原订单总金额，单位为分
amount.currency
string
是
货币类型
req_from
string
否
退款来源：1-人工客服 2-用户自己 3-其它

返回参数

属性
类型
必填
说明
code
string
是
返回码，0为成功
message
string
是
返回信息
request_id
string
是
请求 ID
refund_id
string
是
Superapp 侧退款单号
out_refund_no
string
是
商户退款单号

响应示例

{
    "code": "0",
    "message": "success",
    "request_id": "req_xxxx",
    "refund_id": "rf17389154493510002",
    "out_refund_no": "vrefund_2b695106"
}

7.标准支付-查询退款

接口描述：

提交退款申请后，通过调用该接口查询标准支付退款状态。

调用方式：GET

请求地址：

/spay/refund/refunds/:out_refund_no?merchant_id={merchant_id}

请求 HEADER

参数
是否必填
描述
说明
Authorization
是
签名认证信息
签名参考 签名认证
Content-Type
是
application/json
-

请求参数

属性
类型
必填
说明
out_refund_no
string
是
商户退款单号（path 参数）
merchant_id
string
是
商户号（query 参数）

返回参数

属性
类型
必填
说明
refund_id
string
是
Superapp 侧退款单号
out_refund_no
string
是
商户退款单号
transaction_id
string
是
Superapp 侧交易单号
out_trade_no
string
是
商户订单号
channel
string
是
退款渠道：ORIGINAL-原路退款 BALANCE-退回余额 OTHER_BALANCE-退到其他余额账户 OTHER_BANKCARD-退到其他银行卡
user_received_account
string
是
退款入账账户
success_time
string
否
退款成功时间，状态为 SUCCESS 时返回，格式 yyyy-MM-DDTHH:mm:ss+TIMEZONE
create_time
string
是
退款创建时间
status
string
是
退款状态：PROCESSING-处理中 SUCCESS-成功 CLOSED-关闭 ABNORMAL-异常
amount.total
integer
是
订单总金额，单位为分
amount.refund
integer
是
退款金额，单位为分
amount.payer_total
integer
是
用户支付金额，单位为分
amount.payer_refund
integer
是
用户退款金额，单位为分
amount.currency
string
是
货币类型

响应示例

{
    "refund_id": "rf17389154493510001",
    "out_refund_no": "refund_2b695106b888",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "支付用户零钱",
    "success_time": "2025-02-28T11:05:00+08:00",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "SUCCESS",
    "amount": {
        "total": 88800,
        "refund": 44400,
        "payer_total": 88800,
        "payer_refund": 44400,
        "currency": "USD"
    }
}

8.虚拟支付-查询退款

接口描述：

提交退款申请后，通过调用该接口查询虚拟支付退款状态。

调用方式：GET

请求地址：

/vpay/refund/refunds/:out_refund_no?merchant_id={merchant_id}&access_token={access_token}&pay_sig={pay_sig}

请求参数

属性
类型
必填
说明
out_refund_no
string
是
商户退款单号（path 参数）
merchant_id
string
是
商户号（query 参数）
access_token
string
是
小程序接口访问凭证（query 参数）
pay_sig
string
是
虚拟支付签名（query 参数）

返回参数

属性
类型
必填
说明
refund_id
string
是
Superapp 侧退款单号
out_refund_no
string
是
商户退款单号
transaction_id
string
是
Superapp 侧交易单号
out_trade_no
string
是
商户订单号
channel
string
是
退款渠道：ORIGINAL-原路退款 BALANCE-退回余额 OTHER_BALANCE-退到其他余额账户 OTHER_BANKCARD-退到其他银行卡
user_received_account
string
是
退款入账账户
success_time
string
否
退款成功时间，状态为 SUCCESS 时返回，格式 yyyy-MM-DDTHH:mm:ss+TIMEZONE
create_time
string
是
退款创建时间
status
string
是
退款状态：PROCESSING-处理中 SUCCESS-成功 CLOSED-关闭 ABNORMAL-异常
amount.total
integer
是
订单总金额，单位为分
amount.refund
integer
是
退款金额，单位为分
amount.payer_total
integer
是
用户支付金额，单位为分
amount.payer_refund
integer
是
用户退款金额，单位为分
amount.currency
string
是
货币类型

响应示例

{
    "refund_id": "rf17389154493510002",
    "out_refund_no": "vrefund_2b695106",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "out_trade_no": "2b695106b888d14328d9",
    "channel": "ORIGINAL",
    "user_received_account": "虚拟账户",
    "success_time": "2025-02-28T11:05:00+08:00",
    "create_time": "2025-02-28T11:00:00+08:00",
    "status": "SUCCESS",
    "amount": {
        "total": 100,
        "refund": 50,
        "payer_total": 100,
        "payer_refund": 50,
        "currency": "CNY"
    }
}

9.标准支付-退款结果回调

接口描述：

退款状态改变后，Superapp 平台通过 POST 方式向商户 notify_url 发送退款结果通知。

调用方式：POST

请求地址：

商户申请退款时传入的 notify_url

请求 HEADER

参数
描述
说明
Pay-Serial
SuperAPP 平台证书序列号
验证签名参考 平台证书签名
Pay-Signature
签名值
-
Pay-Timestamp
时间戳
-
Pay-Nonce
随机字符串
-

请求参数

属性
类型
必填
说明
id
string
是
通知 ID
create_time
string
是
通知创建时间
resource_type
string
是
通知资源类型，固定为 encrypt-resource
event_type
string
是
事件类型：REFUND.SUCCESS / REFUND.ABNORMAL / REFUND.CLOSED
summary
string
是
回调摘要
resource.algorithm
string
是
加密算法 AEAD_AES_256_GCM
resource.original_type
string
是
原始数据类型，为 refund
resource.ciphertext
string
是
Base64编码后的密文数据
resource.nonce
string
是
随机串
resource.associated_data
string
否
附加数据

解密后数据

解密方式参考 解密回调报文
属性
类型
必填
说明
refund_id
string
是
Superapp 侧退款单号
out_refund_no
string
是
商户退款单号
transaction_id
string
是
Superapp 侧交易单号
out_trade_no
string
是
商户订单号
refund_status
string
是
退款状态：SUCCESS / CLOSED / ABNORMAL
success_time
string
否
退款成功时间
user_received_account
string
是
退款入账账户
amount.total
integer
是
订单总金额，单位为分
amount.refund
integer
是
退款金额，单位为分
amount.payer_total
integer
是
用户支付金额，单位为分
amount.payer_refund
integer
是
用户退款金额，单位为分
amount.currency
string
是
货币类型

返回参数

处理成功后商户需返回应答以终止通知重试：
{"code": "SUCCESS", "message": "成功"}

10.虚拟支付-退款结果回调

接口描述：

虚拟支付退款完成后，SuperApp 平台通过 POST 方式通知退款结果。

调用方式：POST

请求地址：

商户申请退款时传入的 notify_url

请求参数

属性
类型
必填
说明
eventType
string
是
事件类型
event
string
是
事件名称
payMode
string
是
支付模式
payload
string
是
加密后的回调数据
payEventSig
string
是
回调数据签名

返回参数

处理成功后商户需返回应答：
{"code": "SUCCESS", "message": "成功"}

附录：退款校验规则

属性
类型
必填
说明
退款金额
校验
必须
单笔退款金额≤原订单金额
退款次数
配置
限制
单笔订单退款次数受 maxRefundCount 配置限制
退款有效期
配置
限制
须在支付后 maxRefundDays 天内（默认365天）
幂等控制
逻辑
自动
相同 merchant_id + out_refund_no 视为同一笔退款
频率限制
逻辑
自动
相同 merchant_id + out_refund_no 一分钟内不允许重复（标准支付）
分布式锁
逻辑
自动
防止并发重复提交

退款状态流转

PROCESSING → SUCCESS    （退款成功）
PROCESSING → ABNORMAL   （退款异常）
PROCESSING → CLOSED     （退款关闭）

上一篇: 订阅消息下一篇: 错误码

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈