TransferEasy接口规范跨境收单接口

1.引言

本部分对TransferEasy跨境收单接口进行详细地描述，通过该文档可以对本接口有个全面地了解，使商户技术人员尽快掌握本接口，并能够在此基础上进行开发。

1.1概述

本部分详细介绍了TransferEasy跨境收单接口进行了详细描述。接口采用https+数据签名的方式来保证商户与交易平台间的身份验证、中间信息传递的完整性，以便进行电子商务安全当中非常重要的交易身份辨识、不可抵赖、防止篡改等功能。

1.2使用对象

TransferEasy商户的网上应用开发人员、维护人员和管理人员，他们应具备以下基本知识:

了解上述系统上的网站设置和网页制作方法;
了解HTML语言或了解JAVA、PHP、.NET 等开发语言;
了解信息安全的基本概念。
PHP语言SDK

1.3需求栏

标记	含义
M	必填
C	有条件的
O	可选

1.4接入规范

TransferEasy所有的数据提交和接收的方式皆是以post方式提交和接收，我们的异步回调是以流的方式返回,接口地址:https://api.transfereasy.com

１)数字签名

i.若无特殊说明，Transfereasy API均需签名，以便Transfereasy确认使用者身份

ii.生成私钥
用途：商户端请求API时对参数进行签名的重要参数
存储：请商户端妥善保存，切勿泄露
本地生成私钥：
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out private.key

iii.生成公钥
用途：Transfereasy对请求签名验证的重要参数
存储：登录Transfereasy商户后台系统填写保存
本地生成公钥：openssl rsa -pubout -in private.key -out public.key

iv.生成待签名字符串
a.将请求参数（GET请求的query string，POST请求的form内容）按照参数名ASCII码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成参数字符串，注意：键值中的value需要进行URL编码。

b.在参数字符串后面拼接上Timestamp，用,隔开,得到待签名字符串。

v.生成签名

a.将待签名字符串用RSA加密，哈希算法采用SHA256，密钥使用申请服务时提交的密钥对的私钥。
b.将加密结果使用base64进行编码，得到最终的签名结果。
vi.添加请求头

每个接口的请求和响应header中都包含以下参数：

header参数	说明	生成方法
ContentType	内容编码类型	固定值：application/json
MerchantNO	商户号	由Transfereasy统一生成分配
ProductCode	产品号	由Transfereasy开通权限的产品号，详见产品编号
Timestamp	时间戳	即生成待签名字符串时的Timestamp
Signature	API签名	即生成签名中得到的结果

vii.在接收Transfereasy的异步通知时，商家应该用平台公钥核验签名，以确认通知是Transfereasy发出且未被篡改，验签方法如下:

a.将收到的支付结果回调通知POST请求的form内容按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成签名字符串，注意：需要对键值中的value值进行URL编码。

b.在签名字符串后面拼接上POST请求header中的Timestamp值，用,隔开，得到query_string。

c.将query_string以及POST请求header中的Signature值，先进行base64解码后，再使用SHA-256验签。

应答机制（订单异步返回）是指当贵公司系统收到TransferEasy的支付成功或者取消数据通知（服务器点对点通讯形式）时，必须响应“success”，TransferEasy收到 “success”便认为贵公司已收到,不在继续发送通知；否则将继续发送通知，以递增的时间间隔再次重发 9 次；时间间隔分别为 1s/5s/10s/30s/1m/2m/3m/4m/5m，以确保订单通知成功。(特别提醒：同样的通知可能会多次发送给商户、商户侧系统必须能够正确处理重复的通知，即做幂等处理。推荐的做法是，当商户侧系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理，如果未处理，则进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免造成数据混乱。如果在所有通知频率后没有收到我方回调，商户应调用查询订单接口确认订单状态。)

２)支付回调和查单实现指引

由于网络异常或者系统的波动，可能会导致用户支付成功，但是商户侧未能成功接收到支付结果通知，进而显示订单未支付的情况。商户侧的订单状态更新不及时，容易造成用户投诉，甚至是重复支付的情况发生。
商户在未能收到支付结果通知时，商户可以以订单下单成功为基准设置定时轮询规则，调用《订单查询》接口核实订单状态。系统记录订单查询的次数，在多次查询之后状态还是未支付成功，则停止后续查询，并调用《取消订单接口》取消订单。（轮询时间间隔和次数，商户可以根据自身业务场景灵活设置），方便能及时、准确地获取到订单的支付状态，提升商户系统的健壮性，减少因为订单状态不同步导致的用户投诉。

３)notifyUrl填写注意事项

i.notifyUrl需要填写商户自己系统的真实地址，不能填写接口文档或demo上的示例地址。

ii.notifyUrl必须是以https://或http://开头的完整全路径地址，并且确保url中的域名和IP是外网可以访问的，不能填写localhost、127.0.0.1、192.168.x.x等本地或内网IP。

iii.常见错误举例：

错误示例错误描述
http://www.xxxxx.com url中只有域名，缺少具体的路径
/apspay/payment url不是以https://或http://开头，缺少域名或IP
http://127.0.0.1/apspay/payment url中填写了本地或者内网IP
xxxxxxx，1234567，test 填写了不是url格式的字符串

2.TransferEasy跨境收单钱包列表查询接口

2.1功能描述

TransferEasy跨境收单钱包列表查询接口用于在商户端确认支持钱包时使用，通讯采用https协议，商户通过向TransferEasy指定的URL发送请求参数数据，获取钱包支持列表接口。
注：此接口为选做接口，产品编码为A+系列时使用，其它产品系列无需调用

2.2接口地址

请求地址：/V1/transaction/consultPayment

2.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
amount	订单金额	long	支付单金额，取值币种的最小货币单位，详见货币列表说明	M
currency	订单币种	String(3)	支持币种，详见货币列表	M
presentmentMode	展示类型	String(8)	商家收银页面的展示类型 TILE 单一钱包 UNIFIED 统一支付模式	M
tradeType	支付方式	String(10)	支付方式，详见支付方式	M
osType	终端类型	String(10)	使用终端类型，非WEB时，必填，可选项：IOS,ANDROID	C
settleCurrency	结算币种币种	String(3)	订单对应结算币种	M

以上参数值中不能包含以下特殊字符’”&<>()

2.4示例

{
  "amount": 500,
  "currency": "PHP",
  "presentmentMode": "UNIFIED",
  "settleCurrency": "USD",
  "tradeType": "WEB"
}

2.5请求同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收
		失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

2.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
paymentOptions	付款方式列表	见表：paymentOptions，付款方式列表

2.5.2响应参数（paymentOptions，付款方式列表）

参数名称	参数中文名称	参数说明
paymentMethodType	付款方式类型	付款方式类型，返回值对应使用在下单接口中walletBrand参数传值
enabled	是否可用	指定付款选项是否可用
disableReason	付款选项不可用的原因	付款选项不可用的原因
logoName	logo名称	logo名称
logoUrl	logourl	logourl
logoPattern	logo图案	logo图案
logoWidth	logo宽度	logo宽度
logoHeight	logo高度	logo高度
brandName	支付宝+品牌名称	支付宝+品牌名称
promoNames	促销名称列表	以 JSON 格式。键是语言，例如en_US，而值是促销名称，例如RM1 Voucher

2.6示例

{
  "code": 1000,
  "data": {
    "paymentOptions": [
      {
        "brandName": "Alipay+",
        "disableReason": null,
        "enabled": "true",
        "logoHeight": "190",
        "logoName": "Alipay+",
        "logoPattern": "default",
        "logoUrl": "https://cdn.marmot-cloud.com/storage/aplus-checkout-prod/icon/prod/CONNECT_WALLET.png",
        "logoWidth": "810",
        "paymentMethodType": "CONNECT_WALLET",
        "promoNames": [
          {
            "en_US": "公司-gcash-test"
          }
        ]
      }
    ]
  },
  "msg": "Sucess",
  "status": "SUCCESS"
}

3.TransferEasy人民币参考汇率查询接口

3.1功能描述

商户平台外币计价时，通过该接口可以实时查询到人民币使用的转换汇率。汇率更新时间为北京时间上午10:00，一天更新一次。

3.2接口地址

请求地址：/V1/transaction/searchRate

3.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
feeType	币种	String(10)	外币币种，详细请见详见货币列表	M
date	日期	String(14)	格式为yyyyMMdd，如2022年05月25日表示为20220525。时区为GMT+8 beijing	M

3.4示例

{
"feeType":"USD",
"date":"20220525"
}

3.5汇率查询返回参数列表

参数名称	参数中文名称	参数说明
feeType	币种	外币币种，详细请见详见货币列表
rateTime	汇率时间	格式：yyyyMMdd
rate	汇率值	汇率值如：美元兑换人民币汇率为：6.6971

3.6示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "feeType": "USD",
        "rateTime": "20220525",
        "rate":"6.6971",
    }
}

4.TransferEasy跨境收单下单提交接口

4.1功能描述

TransferEasy跨境收单下单订单提交接口用于在商户端选择支付方式后，通讯采用https协议，商户通过向TransferEasy指定的URL发送请求参数数据，支付完成以后接收异步通知结果。

4.2接口地址

请求地址：/V1/transaction/payment

4.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号，为商户自行拟定，提交的请求单号必须在自身平台交易中唯一，Transfereasy系统中商户已经创建的订单，商户不能以相同的请求单号再次提交，示例:“201901021232211023”	M
merOrderNo	商户订单号	String(64)	商户订单号为商户自行拟定，提交的商户订单号可重复可为空示例:“201901021232211023”	O
amount	订单金额	long	支付单金额，取值币种的最小货币单位，详见货币列表说明	M
currency	订单币种	String(3)	支付单币种，详见货币列表	M
tradeType	支付方式	String(10)	支付方式，[详见支付方式]	M
settleCurrency	结算币种	String(3)	订单对应结算币种产品编码为A+系列时，不传默认结算币种：USD；产品编码为微信系列时结算币种必传	C
osType	终端类型	String(10)	使用终端类型，非WEB时，必填，可选项：IOS,ANDROID	C
authCode	支付授权码	String(30)	支付授权码，反扫时必填	C
productInfo	商品信息	Json数组	见表：productInfo，商品信息	M
clientIp	客户端IP	String(100)	客户端设备IP地址示例：“10.129.35.61”产品编码为微信系列时为必传	C
notifyUrl	通知地址	String(256)	服务器通知：支付成功后会向该地址发送成功通知，该地址不可以带参数(发送机制见：应答机制)，如:`https://www.transfereasy.com/notifyurl.action`.注意：如不填notifyUrl的参数值支付成功后您的服务器将得不到支付成功的通知。	M
returnUrl	回调地址	String(256)	页面回调：支付成功后会向该地址进行跳转，如: `https://www.transfereasy.com/returnurl.action`。	O
walletBrand	钱包名称	String(20)	支付的电子钱包，详见电子钱包，产品编码为A+系列时，不传默认为: “CONNECT_WALLET”；产品编码为微信时，可为空；产品编码为支付宝系列时必传ALIPAY_CN或ALIPAY_HK	O
remark	备注	String(300)	商户在TransferEasy为订单进行备注，通过支付结果返回商户	O
subAppId	微信APPID	String(32)	微信分配给商户应用的唯一ID标识支付方式为：APP、JSAPI、MINI_PROGRAM必填	C
openid	用户标识	String(128)	微信端必填，用户在商户appid下的唯一标识支付方式为：JSAPI、MINI_PROGRAM必填	C
storeTerminalId	商店设备 ID	String(64)	产品编码为A+系列，或支付方式NATIVE或MICROPAY 时必传，有扫描设备填设备id，没有自定义一个即可	C
storeId	门店ID	String(32)	产品编码为A+系列，且支付方式NATIVE_ENTYR_CODE 时必传	C
productId	产品id	String(32)	产品编码为微信系列，且支付方式NATIVE 时必传，商户侧产品id,自定义即可	C
isProfitSharing	是否分账	String(3)	分账：Y，表示该订单为分账订单，支付成功后，允许分账；否则，不传这个参数或者传参数值为:“N”，表示该订单为标准订单，支付成功后，不能调用分账。注：该参数仅支持微信产品	O
以上参数值中不能包含以下特殊字符’”&<>()/

4.3.1请求参数（productInfo，商品信息）

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
name	商品名称	String(127)	商品名称，需传递真实产品名称。	M
quantity	商品数量	long	商品数量	M
amount	商品单价	long	格式与总金额保持一致，此项为单个商品的价格。	M
description	商品描述	String	商品描述	O
订单金额=商品数量*商品单价，订单金额一定要和商品总金额保持一致，如果有其他费用也要按照商品的格式传入为新的一列商品。

4.4示例

{
    "amount": 3000,
    "clientIp": "127.0.0.1",
    "currency": "HKD",
    "notifyUrl": "http://103.100.64.194:7777/demo/paymentNotify",
    "osType": "IOS",
    "outTradeNo": "DE20211206000002",
    "merOrderNo": "DE20211206000002",
    "productInfo": [
        {
            "amount": 1000,
            "description": "测试商品1个",
            "name": "测试商品",
            "quantity": 1
        },
        {
            "amount": 2000,
            "description": "测试商品1个",
            "name": "测试商品2",
            "quantity": 1
        }
    ],
    "remark": "测试remark",
    "returnUrl": "http://103.100.64.194:7777/demo/result/",
    "tradeType": "APP",
    "walletBrand": "ALIPAY_HK"，
    "subAppId":"wx8888888888888888"，
    "openid"："oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
    "isProfitSharing":"Y"
}

4.5请求同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

4.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
paymentNo	支付单号	TransferEasy平台支付单号
outTradeNo	订单号	商户请求单号
merOrderNo	商户订单号	商户订单号
tradeType	支付方式	同请求参数
paymentUrl	支付链接	支付链接
scanCode	二维码值	请求成功时返回，需要转换成二维码图片，进行支付。
nonceStr	随机字符	当支付方式为MINI_PROGRAM、JSAPI时有返回，拉起微信支付需要此参
timeStamp	时间戳	当支付方式为MINI_PROGRAM、JSAPI时有返回，拉起微信支付需要此参
paySign	签名	当支付方式为MINI_PROGRAM、JSAPI时有返回，拉起微信支付需要此参,注：拉起支付时为当前两种支付方式(MINI_PROGRAM、JSAPI)的签名方式均为MD5
prepayParams	预支付参数	当支付方式为APP时有返回，APP端拉起支付需要此参数，[详见prepayParams]
prepayId	预支付交易会话标识	当支付方式为MINI_PROGRAM、JSAPI时有返回，拉起微信支付需要此参
walletBrand	钱包名称	支付的电子钱包，详见电子钱包示例：“TRUEMONEY”
orderStatus	订单状态	订单状态初始化INIT,取消CANCEL,关闭CLOSED,成功SUCCESS,处理中 PROCESSING，待支付 USERPAYING，失败FAIL;
remark	订单备注	同请求参数值

4.6响应参数（prepayParams，参数列表）

参数名称	参数中文名称	参数说明
package	扩展字段	暂填写固定值Sign=WXPay
sign	签名	微信返回的签名
nonceStr	随机字符串	微信返回的随机字符串
timeStamp	时间戳	预支付订单时间戳
appId	应用ID	微信开放平台审核通过的应用APPID
prepayId	预支付交易会话标识	微信返回的支付交易会话ID
partnerId	商户号	微信支付分配的商户号

4.7示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "paymentNo": "20211206132417P3336838851",
        "outTradeNo": "DE20211206000002",
        "tradeType": "WEB",
        "paymentUrl": "https://psp.ac.alipay.com/page/simulation-wallet/index.html?url=alipayconnect%3A%2F%2Fplatformapi%2Falipayconnectcode%3Fcode%3D281666040091jSLG7O9c32tD2a0bsZMv4IxG%26pspName%3DALIPAY_HK&webUrl=https%3A%2F%2Fpsp.ac.alipay.com%2Fpage%2Fsimulation-wallet%2Facwallet%2Falipayconnectcode.html%3Fcode%3D281666040091jSLG7O9c32tD2a0bsZMv4IxG%26pspName%3DALIPAY_HK&loadMode=2",
        "scanCode": null,
        "walletBrand": "ALIPAY_HK",
        "remark": "测试remark",
        "orderStatus": "USERPAYING"，
    }
}

4.8订单异步返回参数列表

注意：此表格的参数为NotifyUrl的服务器返回参数

参数名称	参数中文名称	参数说明
paymentNo	支付单号	TransferEasy平台支付单号
outTradeNo	订单号	商户请求单号
merOrderNo	商户订单号	商户订单号
amount	计价金额	下单时的计价金额
currency	计价币种	下单时的计价币种
payAmount	支付金额	实际支付金额，支付成功后返回
payCurrency	支付币种	实际支付币种，支付成功后返回
tradeType	支付方式	支付方式，详见货币列表
orderStatus	订单状态	订单状态成功SUCCESS
walletBrand	钱包名称	支付的电子钱包，详见电子钱包示例：“TRUEMONEY”
completeDateTime	完成时间	支付完成时间
settleExchangeRate	汇率	订单对应结算汇率
settleAmount	结算金额	订单对应结算金额
settleCurrency	结算币种	订单对应结算币种
customerId	用户ID	订单支付用户ID
remark	订单备注	同请求参数值

4.9示例

{
        "amount": "1000",
    "completeDateTime": "1658710726000",
    "settleAmount": "843",
    "settleCurrency": "USD",
    "orderStatus": "SUCCESS",
    "remark": "remark——DE20220725085816",
    "paymentNo": "20220725085823P2081",
    "walletBrand": "AlipayHK",
    "payAmount": "1000",
    "outTradeNo": "DE20220725085816",
    "outTradeNo": "DE20220725085816",
    "settleExchangeRate": "1.18632790",
    "customerId": "2102209000000675295F2",
    "payCurrency": "HKD",
    "currency": "HKD",
    "tradeType": "WEB"
}

5.TransferEasy跨境收单订单查询接口

5.1功能描述

商户通过跨境收单订单查询接口查询TransferEasy平台的订单状态，并且通过主动查询订单来获知订单信息。

5.2接口地址

请求地址：/V1/transaction/searchPayment

5.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号	M

5.4示例

{"outTradeNo":"DE20211206000003"}

5.5订单查询返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

5.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
paymentNo	支付单号	TransferEasy平台支付单号
outTradeNo	订单号	商户请求单号
amount	计价金额	下单时的计价金额
currency	计价币种	下单时的计价币种
payAmount	支付金额	实际支付金额，支付成功后返回
payCurrency	支付币种	实际支付币种，支付成功后返回
paymentUrl	支付链接	支付链接
tradeType	支付方式	支付方式，详见支付方式
orderStatus	订单状态	订单状态初始化INIT,取消CANCEL,关闭CLOSED,成功SUCCESS,处理中 PROCESSING，待支付 USERPAYING，失败FAIL;
walletBrand	钱包名称	支付的电子钱包，详见电子钱包示例：“TRUEMONEY”
completeDateTime	完成时间	支付完成时间
settleExchangeRate	汇率	订单对应结算汇率
settleAmount	结算金额	订单对应结算金额
settleCurrency	结算币种	订单对应结算币种
dueSettleAmount	应结金额	订单应结金额
serviceFee	服务费	订单对应服务费
serviceFeeCurrency	服务费币种	订单对应服务费币种
customerId	用户ID	订单支付用户ID
remark	订单备注	同请求参数值

5.6示例

{
 "status": "SUCCESS",
        "code": 1000,
        "msg": "Sucess",
        "data": {
                "paymentNo": "20220720167840P6851",
                "outTradeNo": "202207564318242153277033056256",
                "paymentUrl": "https://open-sea.alipayplus.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?charset=UTF-8&codeValue=281654740091lejP5AYmN9hKBH6HJbb48dt8&loadMode=2",
                "scanCode": "281654740091lejP5AYmN9hKBH6HJbb48dt8",
                "walletBrand": "Alipay",
                "remark": "test",
                "orderStatus": "SUCCESS",
                "prepayId": null,
                "appId": null,
                "timeStamp": null,
                "nonceStr": null,
                "paySign": null,
                "tradeType": "WEB",
                "prepayParams": null,
                "amount": 10,
                "currency": "HKD",
                "payAmount": 62,
                "payCurrency": "CNY",
                "completeDateTime": "2022-07-20 17:19:01",
                "settleExchangeRate": null,
                "settleAmount": 10,
                "settleCurrency": "HKD",
                "dueSettleAmount": 2,
                "serviceFeeCurrency": "HKD",
                "serviceFeeCurrency": "0",
                "customerId": "2102256347000876773F2"
        }
}

6.TransferEasy跨境收单订单取消接口

6.1功能描述

对于未终态的订单，可以进行取消操作，调用TransferEasy跨境收单取消接口，取消后，此订单不可以再发起支付。

6.2接口地址

请求地址：/V1/transaction/closePayment

6.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号	M

6.4示例

{"outTradeNo":"DE20211206000003"}

6.5请求同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

6.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
paymentNo	支付单号	TransferEasy平台支付单号
outTradeNo	订单号	商户请求单号
OrderStatus	订单状态	订单状态取消CANCEL
completeDateTime	完成时间	取消完成时间

6.6示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "paymentNo": "20211206140132P3336846566",
        "outTradeNo": "DE20211206000003",
        "orderStatus": "CANCEL",
        "completeDateTime": "2021-12-06T06:02:01.000+00:00"
    }
}

7.TransferEasy跨境收单退款接口

7.1功能描述

提交跨境收单退款申请接口用于商户端通过应用接口程序，实现提交退款申请的业务处理，TransferEasy平台通过JSON格式方式返回退款申请提交的结果响应。其操作功能与现有TransferEasy商户后台输入退款申请功能相同。

注意：在退款接口中，仅分账订单添加两个退款参数 orderRefundAmount(退款金额自分账订单余额)， fundsRefundAmount(退款金额自分账结算余额)，这两个退款金额合计需要等于 refundAmount(退款金额)，但是只能退款分账订单余额资金和结算出境资金，分给非自己的资金无法退款，所以分账前请先注意保证订单完成(无需再发起退款的订单)，再发起非自己接收方分账。
退款频次限制：同一笔订单多次退款的请求需相隔1分钟

7.2接口地址

请求地址：/V1/transaction/refund

7.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	退款订单号	String(64)	商户退款请求单号，为商户自行拟定，Transfereasy系统中商户已经创建的退款订单，商户不能以相同的订单号再次提交	M
paymentNo	原支付单号	String(30)	商户支付订单号在TransferEasy平台对应的支付单号	M
refundAmount	金额	varchar(18)	退款金额，币种为原支付单币种，单位为币种的最小单位，退款金额等于支付金额时为全额退款	M
orderRefundAmount	退款金额自分账订单余额	varchar(18)	退款金额自分账订单余额，单位为币种的最小单位，原支付单非分账单不传	O
fundsRefundAmount	退款金额自分账结算余额	varchar(18)	退款金额自分账结算余额，单位为币种的最小单位，原支付单非分账单不传	O
remark	备注	varchar(300)	商户在TransferEasy为订单进行备注，通过支付结果返回商户	O

7.4示例

{
    "paymentNo": "20211206140132P3336846566",
    "outTradeNo": "DR20211206000003",
    "remark": "测试退款",
    "refundAmount": 1000,
    "orderRefundAmount":400,
    "fundsRefundAmount":600
}

7.5退款请求同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

7.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
refundNo	退款单号	TransferEasy平台退款单号
paymentNo	原支付单号	商户订单号在TransferEasy平台对应的支付单号
outTradeNo	订单号	商户请求单号
merOrderNo	商户订单号	商户订单号
refundAmount	退款金额	退款金额
orderRefundAmount	退款金额自分账订单余额	分账单返回参数
fundsRefundAmount	退款金额自分账结算余额	分账单返回参数
refundCurrency	退款币种	退款币种
settleAmount	结算金额	结算金额
settleCurrency	结算币种	结算币种
serviceFee	服务费	服务费
serviceFeeCurrency	服务费币种	服务费币种
orderStatus	退款状态	退款状态初始化INIT,成功SUCCESS,处理中 PROCESSING，失败FAIL;
orderStatusMsg	退款状态描述	退款状态描述
remark	备注	同请求参数
completeDateTime	完成时间	退款完成时间

7.6示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "refundNo": "20211206144042R3336850476",
        "paymentNo": "20211206140132P3336846566",
        "outTradeNo": "DR20211206000004",
        "merOrderNo": "",
        "refundAmount": 1000,
        "orderRefundAmount":400,
        "fundsRefundAmount":600，
        "refundCurrency": "HKD",
        "settleAmount": 1000,
        "settleCurrency":HKD,
        "serviceFee":0，
        "serviceFeeCurrency": "HKD",
        "orderStatus": "SUCCESS",
        "orderStatusMsg": "Success",
        "remark": "测试退款",
        "completeDateTime": "2021-12-06T06:40:43.000+00:00"
    }
}

8.TransferEasy跨境收单退款查询接口

8.1功能描述

商户通过跨境收单退款订单查询接口查询TransferEasy平台的订单退款交易明细。商户通过主动查询订单获知订单退款信息。

8.2接口地址

请求地址：/V1/transaction/searchRefund

8.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号	M

8.4示例

{"outTradeNo":"DR20211206000005"}

8.5退款查询同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

8.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
refundNo	退款单号	TransferEasy平台退款单号
paymentNo	原支付单号	商户订单号在TransferEasy平台对应的支付单号
outTradeNo	订单号	商户请求单号
merOrderNo	商户订单号	商户订单号
refundAmount	退款金额	退款金额
orderRefundAmount	退款金额自分账订单余额	分账单返回参数
fundsRefundAmount	退款金额自分账结算余额	分账单返回参数
refundCurrency	退款币种	退款币种
settleAmount	结算金额	结算金额
settleCurrency	结算币种	结算币种
serviceFee	服务费	服务费
serviceFeeCurrency	服务费币种	服务费币种
orderStatus	退款状态	退款状态初始化INIT,成功SUCCESS,处理中 PROCESSING，失败FAIL;
orderStatusMsg	退款状态描述	退款状态描述
remark	备注	同请求参数
completeDateTime	完成时间	退款完成时间

8.6示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "refundNo": "20211206144042R3336850476",
        "paymentNo": "20211206140132P3336846566",
        "outTradeNo": "DR20211206000004",
        "merOrderNo": "",
        "refundAmount": 1000,
        "orderRefundAmount":400,
        "fundsRefundAmount":600，
        "refundCurrency": "HKD",
        "settleAmount": 1000,
        "settleCurrency":HKD,
        "serviceFee":0，
        "serviceFeeCurrency": "HKD",
        "orderStatus": "SUCCESS",
        "orderStatusMsg": "Success",
        "remark": "测试退款",
        "completeDateTime": "2021-12-06T06:40:43.000+00:00"
    }
}

9.TransferEasy跨境收单导出对账单接口

9.1功能描述

商户通过跨境收单导出对账单接口获取TransferEasy平台的账户交易明细。

9.2接口地址

请求地址：/bill/download

9.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
billDate	对账单日期	String(10)	导出对账单日期，示例：2021-12-06	M
currency	对账币种	String(3)	导出对账的结算币种	M

9.4示例

{
"billDate":"2021-12-06",
"currency":"USD"
}

9.5对账单导出响应

该接口只能查询一天的记录，以流的形式返回一个csv文件

9.6示例

商户号,商户交易号,交易单号,计价金额,计价币种,结算金额,结算币种,汇率方式,汇率,手续费,手续费币种,交易类型,创建时间,完成时间,产品编码,支付方式,支付钱包,商户订单号,商户支付单号,支付单号,应结金额
80000001,DE20220106134829,20220106134832P2236841266,100,CNY,16,USD,USD/CNY,6.415262,2,USD,支付,2022-01-06 13:48:32,2022-01-06 13:48:48,CP0001,WEB,Alipay,Pay1000001,DE20220106134829,20220106134832P2236841266,14
80000001,DE20220106135401,20220106135404P2236841838,200,CNY,31,USD,USD/CNY,6.415262,2,USD,支付,2022-01-06 13:54:05,2022-01-06 13:54:22,CP0001,WEB,Alipay,Pay1000002,DE20220106134829,20220106134832P2236841266,14
80000001,DE20220106140443,20220106140447P2236846881,100,CNY,16,USD,USD/CNY,6.415262,2,USD,支付,2022-01-06 14:04:47,2022-01-06 14:04:59,CP0001,WEB,Alipay,Pay1000003,DE20220106134829,20220106134832P2236841266,14
80000001,DR20220106112908,20220106112909R2236819343,10,HKD,1,USD,USD/HKD,7.843078,0,USD,退款,2022-01-06 11:29:10,2022-01-06 11:29:09,CP0001,WEB,Alipay,Pay1000003,DE20220106134829,20220106134832P2236841266,1

10.TransferEasy跨境收单报关接口

10.1功能描述

商户通过跨境收单报关接口，实现提交报关申请的业务处理，强烈建议以拆单方式进行申报，TransferEasy平台通过JSON格式返回报关申请的结果。

10.2接口地址

请求地址：/V1/customs/declare

10.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号	M
paymentNo	原支付单号	String(64)	商户订单号在TransferEasy平台对应的支付单号	M
customs	海关编号	varchar(18)	如：SHENZHEN，详见海关列表	M
merchantCustomsCode	商户海关备案号	varchar(24)	商户海关备案号	M
merchantCustomsName	商户海关备名称	varchar(24)	商户海关备名称	M
isSplit	是否拆单	varchar(5)	是否拆单,拆单true,上送自订单号和子订单申报金额，不拆单false，按原单金额申报	M
subOrderNo	商户子订单号	varchar(64)	拆单必填	C
subOrderAmount	商户子订单申报金额	varchar(11)	1. 取值币种的最小货币单位2. 拆单必填,且subOrderAmount= transportAmount+productAmount	C
transportAmount	物流费	varchar(11)	1. 取值币种的最小货币单位2. 原单为微信支付时必填	C
productAmount	商品价格	varchar(11)	1. 取值币种的最小货币单位2. 原单为微信支付时必填	C
duty	关税	varchar(11)	关税，币种最小单位，非必填项，不会提交给海关	C
若要身份验证则需要填以下参数:
certId	身份证号	varchar(360)	身份证号（需加密）	C
name	姓名	varchar(360)	姓名（需加密）	C
敏感信息加密：要加密字段，请参考以下加密算法：1、使用平台的公钥证书对参数值进行RSA加密。使用 `RSA/ECB/PKCS1Padding` 作为填充模式。2、使用base64编码的加密密文作为请求中相应参数的值。

10.4示例

{
  "certId": "iFL2hC158WTiWpB2DITzA5zFZ7oQWQ745pa0y/3kgF4BW/pJfz1Cpv5i0X3m+hOUPySgyn7uw+2wc1D4VIeinEWomwMGEM6kj/3sxiBArrE1K9+/V0Cvj9IwDxG5Ol9En+JI+mObUyy0ftsMkr50EkRRIfe9qMj3/dGXomEEOGOGGyiHpavmXiVDwTbnRqLiikDz52rQQMxSLNi5anbYNkmf9ZNru4aeEw/xPf6eJBkCowO7YNoGgoSPt106bMyC4mk9s0gVpUxfXxZGFbF9grtTZFOwEX46SZQOe3GCLqnC1lX2EZZBqEr3hhF+WbHmdHd9b76Bdh1jqoO6Xkf/Jw\u003d\u003d",
  "customs": "HANGZHOU",
  "isSplit": "true",
  "merchantCustomsCode": "test",
  "merchantCustomsName": "test_code",
  "name": "ATQ7dIsceI78yfns0utjGwCSHejMzj6eFF9fjWBQdubf3DwF8eiO8kQFJzFsFFnmvQIzPnA2HKBn6zwGQ1hAlgjKVv/x4P5RYURxWQvVvXbjNhi6J40kbgUuI8kx3Qh+LwflArjFoqi4R+ZAYB8Y7wVErK8JV1ij0vWuzmCjvgF1zUcTKNrTSwwH21VjUqP07xvLkHuA5ppSjEQG43xA1+6oTzLEYMAwWjQxf/X5CSVlYHjf60R8n3KwuKzkb7QJbI/3zFM0Xz3kN5Rzpfua1hk34qHgn+JxdPlCCn/XUAuTFCNwIjD7p7Lw98bKMruYAPwHffhg2eWj1IdfE/vLWQ\u003d\u003d",
  "outTradeNo": "DE20220705171413",
  "paymentNo": "20220705171428P1641",
  "subOrderAmount": "500",
  "subOrderNo": "20211231160019",
}

10.5报关同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

10.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
outTradeNo	原支付单号	商户支付单号
paymentNo	原支付单号	商户订单号在TransferEasy平台对应的支付单号
customs	海关	海关
state	申报状态	申报状态SENDING– 申报中, SUCCESS – 申报成功, FAIL– 申报失败, UNDECLARED–未申报,SUBMITTED-已修改申报,EXCEPT-海关接口异常
clearingChannel	核验机构	核验机构包括：银联-UNIONPAY、网联-NETSUNION、其他-OTHERS
clearingTransactionId	核验机构流水	核验机构流水
pspPaymentId	数字钱包提供给海关的支付ID	数字钱包提供给海关的支付ID(微信产品编码无需关注)
pspDeclarationRequestId	数字钱包提供给海关的报关单ID	数字钱包提供给海关的报关单ID(微信产品编码拆单，使用该ID报备海关)
pspCustomsCode	数字钱包在海关系统中的注册号	数字钱包在海关系统中的注册号(微信产品编码无需关注)
subOrderNo	商户子订单号	商户子订单号
modifiedTime	最后修改时间	最后修改时间
explanation	申报结果说明	申报结果说明，如果状态是失败或异常，显示失败原因
若进行身份验证会返回以下结果：
certCheckResult	身份验证结果	T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。

10.6示例

{
  "status": "SUCCESS",
  "code": 1000,
  "msg": "Sucess",
  "data": {
    "outTradeNo": "DE20220705171413",
    "paymentNo": "20220705171428P1641",
    "customs": "HANGZHOU",
    "pspPaymentId": "20220705198881010001E0000281712",
    "pspDeclarationRequestId": "20220705181446C885270940",
    "pspCustomsCode": "HANGZHOU",
    "state": "SENDING",
    "clearingChannel": "OTHERS",
    "clearingTransactionId": "vRlbkzGBQgaSqqDRui",
    "subOrderNo": "20211231160019",
    "certCheckResult": "T"
  }
}

11.TransferEasy跨境收单报关重推接口

11.1功能描述

商户通过跨境收单报关重推接口，实现对出现异常报关订单进行报关信息修改，然后重新发起报关，TransferEasy平台通过JSON格式返回报关重推的结果。
注：
如果某笔交易已请求报送海关，但电子口岸丢单，可以使用重推修改功能，重新向海关推送。
如果某笔交易已请求报送海关，但商户备案号、备案名称、海关编码填错、申报金额，可以使用重推修改功能，重新向海关推送。

11.2接口地址

请求地址：/V1/customs/redeclare

11.3请求参数列表

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
outTradeNo	订单号	String(64)	商户请求单号	M
paymentNo	原支付单号	String(64)	商户订单号在TransferEasy平台对应的支付单号	M
customs	海关编号	varchar(18)	如：SHENZHEN	M
merchantCustomsCode	商户海关备案号	varchar(24)	商户海关备案号	M
merchantCustomsName	商户海关备名称	varchar(24)	商户海关备名称	M
isSplit	是否拆单	varchar(24)	是否拆单,拆单true,上送自订单号和自订单申报金额，不拆单false，按原单金额申报	M
subOrderNo	商户子订单号	varchar(24)	拆单必填	C
subOrderAmount	商户子订单申报金额	varchar(24)	1. 取值币种的最小货币单位2. 拆单必填,且subOrderAmount = transportAmount+productAmount	C
transportAmount	物流费	varchar(24)	1. 取值币种的最小货币单位2. 原单为微信支付时必填	C
productAmount	商品价格	varchar(24)	1. 取值币种的最小货币单位2. 原单为微信支付时必填	C
duty	关税	varchar(24)	关税，币种最小单位，非必填项，不会提交给海关	C
若要身份验证则需要填以下参数:
certId	身份证号	varchar(24)	身份证号（需加密）	C
name	姓名	varchar(24)	姓名（需加密）	C

11.4示例

{
  "certId": "iFL2hC158WTiWpB2DITzA5zFZ7oQWQ745pa0y/3kgF4BW/pJfz1Cpv5i0X3m+hOUPySgyn7uw+2wc1D4VIeinEWomwMGEM6kj/3sxiBArrE1K9+/V0Cvj9IwDxG5Ol9En+JI+mObUyy0ftsMkr50EkRRIfe9qMj3/dGXomEEOGOGGyiHpavmXiVDwTbnRqLiikDz52rQQMxSLNi5anbYNkmf9ZNru4aeEw/xPf6eJBkCowO7YNoGgoSPt106bMyC4mk9s0gVpUxfXxZGFbF9grtTZFOwEX46SZQOe3GCLqnC1lX2EZZBqEr3hhF+WbHmdHd9b76Bdh1jqoO6Xkf/Jw\u003d\u003d",
  "customs": "HANGZHOU",
  "isSplit": "true",
  "merchantCustomsCode": "test",
  "merchantCustomsName": "test_code",
  "name": "ATQ7dIsceI78yfns0utjGwCSHejMzj6eFF9fjWBQdubf3DwF8eiO8kQFJzFsFFnmvQIzPnA2HKBn6zwGQ1hAlgjKVv/x4P5RYURxWQvVvXbjNhi6J40kbgUuI8kx3Qh+LwflArjFoqi4R+ZAYB8Y7wVErK8JV1ij0vWuzmCjvgF1zUcTKNrTSwwH21VjUqP07xvLkHuA5ppSjEQG43xA1+6oTzLEYMAwWjQxf/X5CSVlYHjf60R8n3KwuKzkb7QJbI/3zFM0Xz3kN5Rzpfua1hk34qHgn+JxdPlCCn/XUAuTFCNwIjD7p7Lw98bKMruYAPwHffhg2eWj1IdfE/vLWQ\u003d\u003d",
  "outTradeNo": "DE20220705171413",
  "paymentNo": "20220705171428P1641",
  "subOrderAmount": "500",
  "subOrderNo": "20211231160019",
}

11.5报关重推同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

11.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
outTradeNo	原支付单号	商户支付单号
paymentNo	原支付单号	商户订单号在TransferEasy平台对应的支付单号
customs	海关	海关
state	申报状态	申报状态PROCESSING – 申报中, SUCCESS – 申报成功, FAIL– 申报失败, UNDECLARED - 未申报, SUBMITTED - 已修改未申报, EXCEPT - 海关接口异常
clearingChannel	核验机构	核验机构
clearingTransactionId	核验机构流水	核验机构流水
pspPaymentId	数字钱包提供给海关的支付ID	数字钱包提供给海关的支付ID(微信产品编码无需关注)
pspDeclarationRequestId	数字钱包提供给海关的报关单ID	数字钱包提供给海关的报关单ID(微信产品编码无需关注)
pspCustomsCode	数字钱包在海关系统中的注册号	数字钱包在海关系统中的注册号(微信产品编码无需关注)
subOrderNo	商户子订单号	商户子订单号
modifiedTime	最后修改时间	最后修改时间
explanation	申报结果说明	申报结果说明，如果状态是失败或异常，显示失败原因
若进行身份验证会返回以下结果：
certCheckResult	身份验证结果	T表示商户传入的订购人姓名和身份证号和支付人的姓名和身份证号一致。F代表商户传入的订购人姓名和身份证号和支付人的姓名和身份证号不一致。

11.6示例

{
  "status": "SUCCESS",
  "code": 1000,
  "msg": "Sucess",
  "data": {
    "outTradeNo": "DE20220705171413",
    "paymentNo": "20220705171428P1641",
    "customs": "HANGZHOU",
    "pspPaymentId": "20220705198881010001E0000281712",
    "pspDeclarationRequestId": "20220705181446C885270940",
    "pspCustomsCode": "HANGZHOU",
    "state": "SENDING",
    "clearingChannel": "CUP",
    "clearingTransactionId": "vRlbkzGBQgaSqqDRui",
    "subOrderNo": "20211231160019",
    "certCheckResult": "T"
  }
}

12.TransferEasy跨境收单报关查询接口

12.1功能描述

商户通过跨境收单报关查询接口查询TransferEasy平台订单报关明细。商户通过主动查询报关订单获知报关订单信息。

12.2接口地址

请求地址：/V1/customs/declareQuery

12.3请求参数列表

以下二个订单号二选一，若拆单则传subOrderNo，若未拆单则传outTradeNo

参数名称	参数中文名称	类型& 长度	参数说明	是否必填
paymentNo	原支付单号	String(64)	商户订单号在TransferEasy平台对应的支付单号	M
outTradeNo	订单号	String(64)	商户请求订单号	O
subOrderNo	子单号	String(64)	子订单号	O

12.4示例

{"outTradeNo":"DR20211206000005"}

12.5报关查询同步返回参数列表

参数名称	参数中文名称	参数说明
status	请求状态	成功SUCCESS,请求已接收失败FAILED
code	状态码	请求状态码，详见业务状态码
msg	状态描述	状态描述
data	数据信息	返回数据对象信息，在请求状态为成功时返回

12.5.1响应参数（data，响应信息）

参数名称	参数中文名称	参数说明
outTradeNo	原支付单号	商户支付单号
paymentNo	原支付单号	商户订单号在TransferEasy平台对应的支付单号
customs	海关	海关
state	申报状态	申报状态SENDING– 申报中, SUCCESS – 申报成功, FAIL– 申报失败, UNDECLARED - 未申报, SUBMITTED - 已修改未申报, EXCEPT - 海关接口异常
clearingChannel	核验机构	核验机构
clearingTransactionId	核验机构流水	核验机构流水
pspPaymentId	数字钱包提供给海关的支付ID	数字钱包提供给海关的支付ID(微信产品编码无需关注)
pspDeclarationRequestId	数字钱包提供给海关的报关单ID	数字钱包提供给海关的报关单ID(微信产品编码无需关注)
subOrderNo	商户子订单号	商户子订单号
modifiedTime	最后修改时间	最后修改时间
explanation	申报结果说明	申报结果说明，如果状态是失败或异常，显示失败原因

12.6示例

{
  "status": "SUCCESS",
  "code": 1000,
  "msg": "Sucess",
  "data": {
    "outTradeNo": "DE20220705171413",
    "paymentNo": "20220705171428P1641",
    "customs": "HANGZHOU",
    "pspPaymentId": "20220705198881010001E0000281712",
    "pspDeclarationRequestId": "20220705171428P1641",
    "state": "SUCCESS",
    "subOrderNo": "20211231160019",
    "modifiedTime": "2022-07-05T18:20:54+08:00",
    "declarationAmount": "500",
    "explanation": "支付单新增申报成功，逻辑校验通过"
  }
}

13. 创建商家券

13.1 功能描述

商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户，商户可调用发券接口【小程序发券】、【H5发券】发放该批次商家券。

13.2 接口地址

请求地址：/V1/stocks/create
请求方式：POST

13.3 请求参数列表

参数名

变量

类型[长度限制]

必填

描述

商家券批次名称

stockName

string[1,21]

M

批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：10月1日活动券

结算币种

settleCurrency

string[3]

M

支持币种，详见货币列表。
示例值：HKD

批次备注

comment

string[1,20]

O

仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：活动使用

适用商品范围

goodsName

string[1,15]

M

用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx商品使用

批次类型

stockType

string[1,32]

M

批次类型
NORMAL：固定面额满减券批次
DISCOUNT：折扣券批次
EXCHANGE：换购券批次
示例值：NORMAL

-核销规则

couponUseRule

object

M

券核销相关规则

参数名

变量

类型[长度限制]

必填

描述

-券可核销时间

couponAvailableTime

object

M

日期区间内可以使用优惠。

参数名

变量

类型[长度限制]

必填

描述

开始时间

availableBeginTime

string[1,32]

M

批次开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：商家券有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

结束时间

availableEndTime

string[1,32]

M

批次结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：商家券有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

生效后N天内有效

availableDayAfterReceive

int

O

日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推。注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合waitDaysAfterReceive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。
示例值：3

- 固定周期有效时间段

availableWeek

object

O

可以设置多个星期下的多个可用时间段，比如每周二10点到18点，用户自定义字段。

参数名

变量

类型[长度限制]

必填

描述

可用星期数

weekDay

array[int]

C

0代表周日，1代表周一，以此类推
当填写availableDayTime时，weekDay必填
示例值：1, 2

- 当天可用时间段

availableDayTime

array

O

可以填写多个时间段，最多不超过2个。

参数名	变量	类型[长度限制]	必填	描述
当天可用开始时间	beginTime	int	O	当天可用开始时间，单位：秒，1代表当天0点0分1秒。示例值：3600
当天可用结束时间	endTime	int	O	当天可用结束时间，单位：秒，86399代表当天23点59分59秒。示例值：86399

- 无规律的有效时间段

irregularyAvaliableTime

array

O

无规律的有效时间，多个无规律时间段，用户自定义字段。

参数名	变量	类型[长度限制]	必填	描述
开始时间	beginTime	string[1,32]	O	开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00
结束时间	endTime	string[1,32]	O	结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

领取后N天开始生效

waitDaysAfterReceive

int

O

日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推。用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合availableDayAfterReceive一同填写，不可单独填写。
注：最大不能超过30天
示例值：7

-固定面额满减券使用规则

fixedNormalCoupon

object

三选一

stockType为NORMAL时必填。

参数名	变量	类型[长度限制]	必填	描述
优惠金额	discountAmount	int	C	优惠金额，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：5
消费门槛	transactionMinimum	int	C	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-折扣券使用规则

discountCoupon

object

stockType为DISCOUNT时必填。

参数名	变量	类型[长度限制]	必填	描述
折扣比例	discountPercent	int	C	折扣百分比，例如：86为八六折。示例值：86
消费门槛	transactionMinimum	int	C	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-换购券使用规则

exchangeCoupon

object

stockType为EXCHANGE时必填。

参数名	变量	类型[长度限制]	必填	描述
单品换购价	exchangePrice	int	C	单品换购价，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100
消费门槛	transactionMinimum	int	C	消费门槛，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100

核销方式

useMethod

string[1,128]

M

枚举值：
OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。
PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
示例值：OFF_LINE

小程序appid

miniProgramsAppid

string[1,32]

C

核销方式为线上小程序核销才有效。
示例值：wx23232232323

小程序path

miniProgramsPath

string[1,128]

C

核销方式为线上小程序核销才有效。
示例值：/path/index/index

-发放规则

stockSendRule

object

M

券发放相关规则

参数名	变量	类型[长度限制]	必填	描述
批次最大发放个数	maxCoupons	int	M	批次最大可发放个数限制特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100
用户最大可领个数	maxCouponsPerUser	int	M	用户可领个数，每个用户最多100张券。示例值：5
单天发放上限个数	maxCouponsByDay	int	O	单天发放上限个数（stockType为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限）。特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100
是否开启自然人限制	naturalPersonLimit	bool	O	不填默认否，枚举值： true：是 false：否注：自然人防刷即同证件号下的所有账户合并计算的限领次数（限领次数指的是参数字段“用户最大领取个数”填写的值）示例值：false
可疑账号拦截	preventApiAbuse	bool	O	不填默认否，枚举值： true：是 false：否如：黑灰产账号示例值：false
是否允许转赠	transferable	bool	O	不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false
是否允许分享链接	shareable	bool	O	不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false

商户请求单号

requestSerialNo

string[1,100]

M

商户请求单号，同一天商户侧需保持唯一性。
示例值：100002322019090134234sfdf

-自定义入口

customEntrance

object

O

卡详情页面，可选择多种入口引导用户。

参数名

变量

类型[长度限制]

必填

描述

-小程序入口

miniProgramsInfo

object

O

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。
appid要与归属商户号有M-A or M-m-suba关系。

参数名	变量	类型[长度限制]	必填	描述
商家小程序appid	miniProgramsAppid	string[1,32]	C	商家小程序appid要与归属商户号有M-A or M-m-suba关系。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID 或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx234545656765876
商家小程序path	miniProgramsPath	string[1,128]	C	商家小程序path 示例值：/path/index/index
入口文案	entranceWords	string[1,5]	C	入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购
引导文案	guidingWords	string[1,6]	O	小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠

商户公众号appid

appid

string[1,32]

O

可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID 或传入的APPID得是归属商户号有绑定关系的APPID
示例值：wx324345hgfhfghfg

营销馆id

hallId

string[1,64]

O

填写微信支付营销馆的馆id，用户自定义字段。
示例值：233455656

可用门店id

storeId

string[1,64]

O

填写代金券可用门店id，用户自定义字段。
示例值：233554655

code展示模式

codeDisplayMode

string[1,8]

O

枚举值：
NOT_SHOW：不展示code
BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

-样式信息

displayPatternInfo

object

O

创建批次时的样式信息。

参数名

变量

类型[长度限制]

必填

描述

使用须知

description

string[1,1000]

O

用于说明详细的活动规则，会展示在代金券详情页。
示例值：xxx门店可用

商户logo

merchantLogoUrl

string[1,128]

O

若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。
商户logo的URL地址，仅支持通过《图片上传API》接口获取的图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式，且图片小于1M。
示例值：https://qpic.cn/xxx

商户名称

merchantName

string[1,16]

O

不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。
示例值：微信支付

背景颜色

backgroundColor

string[1,16]

O

券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值：Color020

券详情图片

couponImageUrl

string[1,128]

O

券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。
示例值：https://qpic.cn/xxx

- 视频号相关信息

stocksFinderInfo

object

O

视频号相关信息

参数名	变量	类型[长度限制]	必填	描述
视频号ID	finderId	string[1,32]	C	关联视频号将展示在优惠券详情的顶部右侧，作为跳转去视频号的入口，请求参数请配置视频号ID，请前往视频号助手管理查看视频号ID 示例值：sph6Rngt2T4RlUf
视频号视频ID	finderVideoId	string[1,256]	C	券详情视频内容，支持配置关联视频号下的具体视频内容，请求参数请配置视频ID，请前往视频号助手管理后台复制具体视频ID 示例值：export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
视频号封面图	finderVideoCoverImageUrl	string[1,256]	C	截取的视频号图片将在券到期提醒消息、券详情中展示。 1.图片尺寸：1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。 2.仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://wxpaylogo.qpic.cn/xxx

券code模式

couponCodeMode

string[1,128]

M

枚举值：
WECHATPAY_MODE：系统分配券code。（固定22位纯数字）
MERCHANT_API：商户发放时接口指定券code。
MERCHANT_UPLOAD：商户上传自定义code，发券时系统随机选取上传的券code。
特殊规则：
1、券code模式为WECHATPAY_MODE时，是微信自动分配券code，商户不需要预存code；适用于多种场景
2、券code模式为MERCHANT_API时，无需调用上传预存code接口，调用发券接口时需指定券code；更多用在商家自有流量场景（例如：商家自有小程序、H5网页等）
3、券code模式为MERCHANT_UPLOAD，需要调用上传预存code接口上传code，调用发券接口时无需指定code；更多适用在微信支付平台流量场景（例如：支付有礼、支付有优惠等）
示例值：WECHATPAY_MODE

-事件通知配置

notifyConfig

object

O

事件回调通知商户的配置。

参数名	变量	类型[长度限制]	必填	描述
事件通知appid	notifyAppId	string[1,64]	O	用于回调通知时，计算返回操作用户的openid（诸如领券用户），支持小程序or公众号的APPID；如该字段不填写，则回调通知中涉及到用户身份信息的openid与unionid都将为空。示例值：wx23232232323

是否允许营销补贴

subsidy

bool

O

该批次发放的券是否允许进行补差，默认为false
示例值：false

卡券背景颜色图

商家券样式图

券详情信息展示

13.3.1 示例

{
    "comment":"仅限活动使用",
    "couponCodeMode":"MERCHANT_UPLOAD",
    "couponUseRule":{
        "couponAvailableTime":{
            "availableBeginTime":"2022-10-20T13:29:35+08:00",
            "availableEndTime":"2022-11-20T13:29:35+08:00"
        },
        "fixedNormalCoupon":{
            "discountAmount":10,
            "transactionMinimum":100
        },
        "miniProgramsAppid":"",
        "miniProgramsPath":"",
        "useMethod":"PAYMENT_CODE"
    },
    "goodsName":"xxx商店可用",
    "merchantNo":"",
    "outRequestNo":"12336",
    "productCode":"",
    "settleCurrency":"HKD",
    "stockName":"双十一活动",
    "stockSendRule":{
        "maxCoupons":10,
        "maxCouponsByDay":5,
        "maxCouponsPerUser":2,
        "naturalPersonLimit":false,
        "preventApiAbuse":false,
        "shareable":false
    },
    "stockType":"NORMAL",
    "subsidy":false
}

13.4 返回参数列表

参数名	变量	必填	描述
请求状态	status	是	成功SUCCESS,请求已接收失败FAIL 示例值：SUCCESS
状态码	code	是	请求状态码
状态描述	msg	是	状态描述
批次号	stockId	否	微信为每个商家券批次分配的唯一ID。示例值：98065001
请求单号	outRequestNo	否	请求创建商家券的唯一标识
流水号	requestSerialNo	否	请求流水号
券code模式	couponCode	否	WECHATPAY_MODE：系统分配券code。（固定22位纯数字） MERCHANT_API：商户发放时接口指定券code。 MERCHANT_UPLOAD：商户上传自定义code，发券时系统随机选取上传的券code。

13.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "status":"SUCCESS",
        "couponCode":"MERCHANT_UPLOAD",
        "outRequestNo":"12336",
        "requestSerialNo":"148888473784832312336",
        "stockId":"123222222200000006"
    }
}

14.上传商家券预存code

14.1 功能描述

商家券的Code码可由微信后台随机分配，同时支持商户自定义。如商家已有自己的优惠券系统，可直接使用自定义模式。即商家预先向微信支付上传券Code，当券在发放时，微信支付自动从已导入的Code中随机取值（不能指定），派发给用户。

14.2 接口地址

请求地址：/V1/stocks/uploadStockCodes
请求方式：POST

14.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
批次号	stockId	string[1,20]	M	微信为每个商家券批次分配的唯一ID 示例值：98065001
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表。示例值：HKD
券code列表	couponCodeList	array	O	商户上传的券code列表，code允许包含的字符有0-9、a-z、A-Z、-、_、\、/、=、\|。特殊规则：单个券code长度为【1，32】，条目个数限制为【1，200】。示例值：ABC9588200，ABC9588201
请求业务单据流水号	uploadSerialNo	string[1,128]	M	商户上传code的凭据号，商户侧需保持唯一性。示例值：100002322019090134234sfdf

14.3.1 示例

{
    "settleCurrency":"HKD",
    "uploadRequestNo":"123",
    "stockId":"1232200000000386",
    "couponCodeList":[
        "a123",
        "a321"
    ]
}

14.4 返回参数列表（data，响应信息）

参数名

变量

类型[长度限制]

必填

描述

批次号

stockId

string[1,20]

M

微信为每个商家券批次分配的唯一ID。
示例值：98065001

去重后上传code总数

totalCount

uint64

M

本次上传操作，去重后实际上传的code数目。
示例值：500

上传成功code个数

successCount

uint64

M

本次上传操作上传成功个数。
示例值：20

上传成功的code列表

successCodes

array

O

本次新增上传成功的code信息。
特殊规则：单个券code长度为【1，32】，条目个数限制为【1，200】。
示例值：MMAA12345

上传成功时间

successTime

string[1,32]

M

上传操作完成时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

上传失败code个数

failCount

uint64

O

本次上传操作上传失败的code数。
示例值：10

-上传失败的code及原因

failCodes

array

O

本次导入失败的code信息，请参照错误信息，修改后重试。

参数名	变量	类型[长度限制]	必填	描述
上传失败的券code	couponCode	string[1,32]	M	商户通过API上传的券code。示例值：ABCD23456
上传失败错误码	code	string[1,32]	M	对应券code上传失败的错误码。示例值：LENGTH_LIMIT
上传失败错误信息	message	string[1,128]	M	上传失败的错误信息描述。示例值：长度超过最大值32位

已存在的code列表

existCodes

array

O

历史已存在的code列表，本次不会重复导入。
特殊规则：单个券code长度为【1，32】，条目个数限制为【1，200】。
示例值：ABCD2345

本次请求中重复的code列表

duplicateCodes

array

O

本次重复导入的code会被自动过滤，仅保留一个做导入，如满足要求则成功；如不满足要求，则失败；请参照报错提示修改重试。
特殊规则：单个券code长度为【1，32】，条目个数限制为【1，200】。
示例值：AACC2345

14.4.1

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "stockId":"1232232323200386",
        "totalCount":2,
        "successCount":2,
        "successCodes":[
            "a123",
            "a321"
        ],
        "successTime":"2022-11-07T18:36:46+08:00",
        "failCount":0,
        "failCodes":[
        ],
        "existCodes":[
        ],
        "duplicateCodes":[
        ]
    }
}

15.发券

15.1 功能描述

微信支付为商户提供H5发券接口，可在H5页面为指定用户发放指定批次的微信支付商家券。推荐使用 JSAPI H5发券功能，两者区别如下：

JSAPI H5发券功能发券后会回调领券结果给到商家，方便商家做对应的处理；该H5发券不回调信息给商家，依赖商家主动去查询。
支持小程序嵌套H5场景的发券，该H5发券不支持在小程序内进行调用。
原理：H5发券的领券页面是带有weixin域名的一个H5页面，不支持在商家小程序调用（因为商家没有这个域名的备案资质）；而jsapi发券的领券页面是原生页面，不受小程序框架约束。

15.2 接口地址

请求地址：/V1/stocks/send
请求方式：POST

15.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
批次号	stockId	string[1,20]	M	微信支付商家券批次号
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表。示例值：HKD
发券凭证	requestSerialNo	string[1,64]	M	发券凭证，商户侧需保证发放凭据号唯一性
用户openid	openid	string[1,128]	O	目标发券的用户openid 校验规则： 1，可用归属商户号绑定的APPID获取的openid 2，可用发券商户绑定的APPID获取的openid
自定义领取时间	customizeSendTime	string[1,32]	O	商家券在商户业务系统里的实际领取时间，仅针对有设置相对领取时间的批次生效（即批次有设置“生效后N天内有效”或“领取后N天开始生效”时间字段）。传入后，将使用传入的时间点，做为商家券领取时间来计算有效期，而非用户在微信支付系统中点击领取的时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。注：该字段未启用示例值：2015-05-20T13:29:35+08:00
券 code	couponCode	string[1,128]	O	如果批次配置了 code 模式为“商户发放时接口指定券 code”，则必填，其他模式无需填写示例值：75345199

15.3.1 示例

{
    "couponCode":"",
    "customizeSendTime":"",
    "openid":"o2q5Z5Iw8M",
    "requestSerialNo":"1212",
    "settleCurrency":"HKD",
    "stockId":"1232222222000386"
}

15.4 返回参数列表（data，响应信息）

参数名	变量	类型[长度限制]	必填	描述
批次号	stockId	string[1,20]	M	微信支付券批次id 示例值：123
发券凭证	outRequestNo	string[1,128]	M	发券凭证，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号，需在单个批次单个用户下确保唯一性示例值：1234567
发券商户号	sendCouponMerchant	string[8,15]	M	调用发券接口的商户号示例值：10016226
签名	sign	string	M	签名计算值。示例值：9A0A8659F005D6984697E2CA0A9CF3B79A0A8659F005D6984697E2CA0A9CF3B7
用户openid	openid	string[1,128]	M	目标发券的用户openid 示例值：10011212261
券 code	couponCode	string[1,128]	O	如果批次配置了 code 模式为“商户发放时接口指定券 code”，则必填，其他模式无需填写示例值：75345199

15.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "outRequestNo":"1400000000812312",
        "sendCouponMerchant":"128888888",
        "openid":"o2fdfdfdfdfff",
        "stockId":"1232200000000386",
        "sign":"FAB24CE065FBA21E339C22B61ADF20B1C5FBAF2A57CC2E",
        "couponCode":""
    }
}

16.商家券核销用户券

16.1 功能描述

在用户满足优惠门槛后，商户可通过该接口核销用户微信卡包中具体某一张商家券。

16.2 接口地址

请求地址：/V1/stocks/writeOffCoupon
请求方式：POST

16.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
券code	couponCode	string[1,32]	M	券的唯一标识。示例值：sxxe34343434
结算币种	currency	string[3]	M	支持币种，详见货币列表
批次号	stockId	string[1,20]	O	微信为每个商家券批次分配的唯一ID，当你在创建商家券接口中的coupon_code_mode参数传值为MERCHANT_API或者MERCHANT_UPLOAD时，则核销接口中该字段必传，否则该字段可不传示例值：100088
公众账号ID	appId	string[1,32]	M	支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。核销接口返回的openid会在该传入appid下进行计算获得。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx1234567889999
核销请求流水号	requestSerialNo	string[1,32]	M	每次核销请求的唯一标识，商户需保证唯一。示例值：10026006200190
用户标识	openid	string[1,128]	O	用户的唯一标识，做安全校验使用，非必填。校验规则：传入的openid得是调用方商户号（即请求头里面的商户号）有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。示例值：xsd3434454567676
请求核销时间	useTime	string[1,32]	M	商户请求核销用户券的时间。遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

16.3.1 示例

{
    "appId":"wx234323532dfdswd",
    "couponCode":"a321",
    "currency":"HKD",
    "requestSerialNo":"1233",
    "stockId":"12322222222000006",
    "useTime":"2015-05-20T13:29:35+08:00"
}

16.4 返回参数列表（data，响应信息）

参数名	变量	描述
状态码	code	请求状态码
状态描述	message	状态描述
券code	couponCode	券的唯一标识。示例值：sxxe34343434
批次号	stockId	微信为每个商家券批次分配的唯一ID 示例值： 100088
用户标识	openid	用户在公众号内的唯一身份标识。示例值：dsadas34345454545
系统核销券成功的时间	wechatpayUseTime	系统成功核销券的时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

16.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":null,
        "couponCode":null,
        "stockId":"12322222222296",
        "openid":"",
        "wechatpayUseTime":"2022-11-08T14:56:53+08:00"
    }
}

17.查询商家券详情

17.1 功能描述

商户可通过该接口查询已创建的商家券批次详情信息。

17.2 接口地址

请求地址：/V1/stocks/findInfo
请求方式：POST

17.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
批次号	stockId	string[1,20]	M	微信为每个商家券批次分配的唯一ID 示例值：1212
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表

17.3.1 示例

{
    "settleCurrency":"HKD",
    "stockId":"1232222222222006"
}

17.4 返回参数列表（data，响应信息）

参数名

变量

类型[长度限制]

必填

描述

商家券批次名称

stockName

string[1,21]

M

批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：8月1日活动券

批次归属商户号

belongMerchant

string[8,15]

M

批次归属于哪个商户。
示例值：10000022

批次备注

comment

string[1,20]

O

仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：活动使用

适用商品范围

goodsName

string[1,15]

M

用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx商品使用

批次类型

stockType

string[1,16]

M

批次类型
NORMAL：固定面额满减券批次
DISCOUNT：折扣券批次
EXCHANGE：换购券批次
示例值：NORMAL

-核销规则

couponUseRule

object

M

券核销相关规则

参数名

变量

类型[长度限制]

必填

描述

-券可核销时间

couponAvailableTime

object

M

日期区间内可以使用优惠。

参数名

变量

类型[长度限制]

必填

描述

开始时间

availableBeginTime

string[1,32]

M

批次开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：开始时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

结束时间

availableEndTime

string[1,32]

M

批次结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：结束时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

生效后N天内有效

availableDayAfterReceive

int

O

日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推。注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。
示例值：3

- 固定周期有效时间段

availableWeek

object

O

可以设置多个星期下的多个可用时间段，比如每周二10点到18点，用户自定义字段。

参数名

变量

类型[长度限制]

必填

描述

可用星期数

weekDay

array[int]

O

0代表周日，1代表周一，以此类推。
示例值：1, 2

- 当天可用时间段

availableDayTime

array

O

可以填写多个时间段，最多不超过2个。

参数名	变量	类型[长度限制]	必填	描述
当天可用开始时间	beginTime	int	O	当天可用开始时间，单位：秒，1代表当天0点0分1秒。示例值：3600
当天可用结束时间	endTime	int	O	当天可用结束时间，单位：秒，86399代表当天23点59分59秒。示例值：86399

- 无规律的有效时间段

irregularyAvaliableTime

array

O

无规律的有效时间，多个无规律时间段，用户自定义字段。

参数名	变量	类型[长度限制]	必填	描述
开始时间	beginTime	string[1,32]	O	开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00
结束时间	endTime	string[1,32]	O	结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

领取后N天开始生效

waitDaysAfterReceive

int

O

日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推。用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。
示例值：7

-固定面额满减券使用规则

fixedNormalCoupon

object

三选一

stock_type为NORMAL时必填。

参数名	变量	类型[长度限制]	必填	描述
优惠金额	discountAmount	int64	M	优惠金额，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：5
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-折扣券使用规则

discountCoupon

object

stock_type为DISCOUNT时必填。

参数名	变量	类型[长度限制]	必填	描述
折扣比例	discountPercent	int	M	折扣百分比，例如：86为八六折。示例值：86
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-换购券使用规则

exchangeCoupon

object

stock_type为EXCHANGE时必填。

参数名	变量	类型[长度限制]	必填	描述
单品换购价	exchangePrice	int64	M	单品换购价，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100

核销方式

useMethod

string[1,128]

M

枚举值：
OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。
PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
示例值：OFF_LINE

小程序appid

miniProgramsAppid

string[1,32]

C

核销方式为线上小程序核销才有效。
示例值：wx23232232323

小程序path

miniProgramsPath

string[1,128]

C

核销方式为线上小程序核销才有效。
示例值：/path/index/index

-发放规则

stockSendRule

object

是

券发放相关规则

参数名	变量	类型[长度限制]	必填	描述
批次最大发放个数	maxCoupons	int	C	当stock_type为DISCOUNT或EXCHANGE类型时，必须填写。特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100
用户最大可领个数	maxCouponsPerUser	int	M	用户可领个数。示例值：5
单天发放上限个数	maxCouponsByDay	int	O	单天发放上限个数（stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限），每个用户最多100张券。特殊规则：取值范围 1 ≤ value ≤ 1000000000 示例值：100
是否开启自然人限制	naturalPersonLimit	bool	O	不填默认否，枚举值： true：是 false：否注：自然人防刷即同证件号下的所有账户合并计算的限领次数（限领次数指的是参数字段“用户最大领取个数”填写的值）示例值：false
可疑账号拦截	preventApiAbuse	bool	O	不填默认否，枚举值： true：是 false：否示例值：false
是否允许转赠	transferable	bool	O	不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false
是否允许分享链接	shareable	bool	O	不填默认否，枚举值： true：是 false：否该字段暂未开放示例值：false

-自定义入口

customEntrance

object

否

卡详情页面，可选择多种入口引导用户。

参数名

变量

类型[长度限制]

必填

描述

-小程序入口

miniProgramsInfo

object

O

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名	变量	类型[长度限制]	必填	描述
商家小程序appid	miniProgramsAppid	string[1,32]	M	商家小程序appid要与归属商户号有M-A or M-m-suba关系。示例值：wx234545656765876
商家小程序path	miniProgramsPath	string[1,128]	M	商家小程序path 示例值：/path/index/index
入口文案	entranceWords	string[1,5]	M	入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购
引导文案	guidingWords	string[1,6]	O	小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠

商户公众号appid

appId

string[1,32]

O

可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
注：若创建商家券接口未填写该参数，该参数默认返回微信支付的appid，用户点击进入微信支付公众号
示例值：wx324345hgfhfghfg

营销馆id

hallId

string[1,64]

O

填写微信支付营销馆的馆id，用户自定义字段。
示例值：233455656

可用门店id

storeId

string[1,64]

O

填写代金券可用门店id，用户自定义字段。
示例值：233554655

code展示模式

codeDisplayMode

string[1,8]

O

枚举值：
NOT_SHOW：不展示code
BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

-样式信息

displayPatternInfo

object

O

创建批次时的样式信息。

参数名	变量	类型[长度限制]	必填	描述
使用须知	description	string[1,1000]	O	用于说明详细的活动规则，会展示在代金券详情页。示例值：深圳南山区门店可用
商户logo	merchantLogoUrl	string[1,128]	O	若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。 1、商户logo大小需为120像素*120像素。 2、支持JPG/JPEG/PNG格式，且图片小于1M。示例值：https://qpic.cn/xxx
商户名称	merchantName	string[1,16]	O	不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。示例值：微信支付
背景颜色	backgroundColor	string[1,15]	O	代金券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。示例值：Color020
券详情图片	couponImageUrl	string[1,128]	O	券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://qpic.cn/xxx

券code模式

couponCodeMode

string[1,128]

M

枚举值：
WECHATPAY_MODE：系统分配券code。
MERCHANT_API：商户发放时接口指定券code。
MERCHANT_UPLOAD：商户上传自定义code，发券时系统随机选取上传的券code。
示例值：WECHATPAY_MODE

-事件通知配置

notifyConfig

object

O

事件回调通知商户的配置。

参数名	变量	类型[长度限制]	必填	描述
事件通知appid	notifyAppId	string[1,64]	O	用于回调通知时，计算返回操作用户的openid（诸如领券用户），支持小程序or公众号的APPID；如该字段不填写，则回调通知中涉及到用户身份信息的openid与unionid都将为空。示例值：wx23232232323

-批次发放情况

sendCountInformation

object

O

批次发放情况

参数名	变量	类型[长度限制]	必填	描述
已发放券张数	totalSendNum	uint64	否	批次已发放的券数量，满减、折扣、换购类型会返回该字段示例值：1
已发放券金额	totalSendAmount	uint64	O	批次已发放的预算金额，满减券类型会返回该字段示例值：34
单天已发放券张数	todaySendNum	uint64	O	批次当天已发放的券数量，设置了单天发放上限的满减、折扣、换购类型返回该字段示例值：1
单天已发放券金额	todaySendAmount	uint64	O	批次当天已发放的预算金额，设置了单天发放上限的满减券类型返回该字段示例值：34

卡券背景颜色图

商家券详情信息样式图

17.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "stockName":"双十一活动",
        "belongMerchant":"432553075",
        "comment":"无购买上线",
        "goodsName":"所有商品",
        "stockType":"NORMAL",
        "couponUseRule":{
            "couponAvailableTime":{
                "availableBeginTime":"2022-10-20T13:29:35+08:00",
                "availableEndTime":"2022-11-20T13:29:35+08:00",
                "availableDayAfterReceive":null,
                "availableWeek":null,
                "irregularyAvaliableTime":[
                ],
                "waitDaysAfterReceive":0
            },
            "fixedNormalCoupon":{
                "discountAmount":10,
                "transactionMinimum":100
            },
            "discountCoupon":null,
            "exchangeCoupon":null,
            "useMethod":"PAYMENT_CODE",
            "miniProgramsAppid":null,
            "miniProgramsPath":null
        },
        "stockSendRule":{
            "maxCoupons":15,
            "maxCouponsPerUser":2,
            "maxCouponsByDay":5,
            "naturalPersonLimit":null,
            "preventApiAbuse":null,
            "transferable":null,
            "shareable":null
        },
        "outRequestNo":null,
        "customEntrance":{
            "miniProgramsInfo":null,
            "appId":"wx6666666666",
            "hallId":null,
            "storeId":null,
            "codeDisplayMode":null
        },
        "displayPatternInfo":{
            "description":"",
            "merchantLogoUrl":"https://wx.gtimg.com/resource/feuploader/202106/holder_logo_240x240.png",
            "merchantName":"BM",
            "backgroundColor":"Color020",
            "couponImageUrl":""
        },
        "couponCodeMode":"MERCHANT_UPLOAD",
        "notifyConfig":null,
        "sendCountInformation":{
            "totalSendNum":2,
            "totalSendAmount":20,
            "todaySendNum":"2",
            "todaySendAmount":"20"
        }
    }
}

18.根据过滤条件查询用户券

18.1 功能描述

商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。

18.2 接口地址

请求地址：/V1/stocks/findConditions
请求方式：POST

18.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表
用户标识	openid	string[1,128]	M	Openid信息，用户在appid下的唯一标识。校验规则：传入的openid得是调用方商户号（即请求头里面的商户号）有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。示例值：2323dfsdf342342
公众账号ID	appid	string[1,32]	M	支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID 或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx233544546545989
批次号	stockId	string[1,20]	O	微信为每个商家券批次分配的唯一ID，是否指定批次号查询。示例值：9865000
券状态	couponState	string[1,16]	O	券状态枚举值： SENDED：可用 USED：已核销 EXPIRED：已过期示例值：SENDED
创建批次的商户号	creatorMerchant	string[1,32]	O	批次创建方商户号校验规则：当调用方商户号（即请求头中的商户号）为创建批次方商户号时，该参数必传示例值：1000000001
批次归属商户号	belongMerchant	string[8,15]	O	批次归属商户号校验规则：当调用方商户号（即请求头中的商户号）为批次归属商户号时，该参数必传示例值：1000000002
批次发放商户号	senderMerchant	string[1,32]	O	批次发放商户号校验规则：当调用方商户号（即请求头中的商户号）为批次发放商户号时，该参数必传；委托营销关系下，请填写委托发券的商户号示例值：1000000003
分页页码	offset	int	O	分页页码示例值：0
分页大小	limit	int	O	分页大小示例值：20

18.3.1 示例

{
    "appid":"wxfxxxxx5",
    "belongMerchant":"",
    "couponState":"",
    "creatorMerchant":"",
    "limit":10,
    "offset":0,
    "openid":"o28392xxxxxM",
    "senderMerchant":"",
    "settleCurrency":"HKD",
    "stockId":""
}

18.4 返回参数列表（data，响应信息）

参数名

变量

类型[长度限制]

必填

描述

-结果集

data

array

是

结果集

参数名

变量

类型[长度限制]

必填

描述

批次归属商户号

belongMerchant

string[8,15]

M

批次归属于哪个商户。
示例值：10000022

商家券批次名称

stockName

string[1,21]

M

批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：商家券

批次备注

comment

string[1,20]

O

仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx可用

适用商品范围

goodsName

string[1,15]

M

适用商品范围，字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx商品可用

批次类型

stockType

string[1,128]

M

批次类型
NORMAL：固定面额满减券批次
DISCOUNT：折扣券批次
EXCHANGE：换购券批次
示例值：NORMAL

是否允许转赠

transferable

bool

O

不填默认否，枚举值：
true：是
false：否
该字段暂未开放
示例值：false

是否允许分享领券链接

shareable

bool

O

不填默认否，枚举值：
true：是
false：否
该字段暂未开放
示例值：false

券状态

couponState

string[1,16]

O

商家券状态
枚举值：
SENDED：可用
USED：已核销
EXPIRED：已过期
示例值：SENDED

-样式信息

displayPatternInfo

object

O

商家券详细信息

示例值：https://qpic.cn/xxx

参数名	变量	类型[长度限制]	必填	描述
商户logo	merchantLogoUrl	string[1,128]	O
商户名称	merchantName	string[1,16]	O	商户名称，字数上限为16个，一个中文汉字/英文字母/数字均占用一个字数。示例值：微信支付
背景颜色	backgroundColor	string[1,16]	O	代金券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。示例值：Color020
券详情图片	couponImageUrl	string[1,128]	O	券详情图片，850像素*350像素，且图片大小不超过2M，支持JPG/PNG格式示例值：https://qpic.cn/xxx

-券核销规则

couponUseRule

券核销规则

M

券核销相关规则

参数名

变量

类型[长度限制]

必填

描述

-券可核销时间

couponAvailableTime

object

M

日期区间内可以使用优惠。

参数名

变量

类型[长度限制]

必填

描述

开始时间

availableBeginTime

string[1,32]

M

批次开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：开始时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

结束时间

availableEndTime

string[1,32]

M

批次结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：结束时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

生效后N天内有效

availableDayAfterReceive

int

O

日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推。注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。
示例值：3

- 固定周期有效时间段

availableWeek

object

O

可以设置多个星期下的多个可用时间段，比如每周二10点到18点，用户自定义字段。

参数名

变量

类型[长度限制]

必填

描述

可用星期数

weekDay

array[int]

O

0代表周日，1代表周一，以此类推。
示例值：1, 2

- 当天可用时间段

availableDayTime

array

O

可以填写多个时间段，最多不超过2个。

参数名	变量	类型[长度限制]	必填	描述
当天可用开始时间	beginTime	int	O	当天可用开始时间，单位：秒，1代表当天0点0分1秒。示例值：3600
当天可用结束时间	endTime	int	O	当天可用结束时间，单位：秒，86399代表当天23点59分59秒。示例值：86399

- 无规律的有效时间段

irregularyAvaliableTime

array

O

无规律的有效时间，多个无规律时间段，用户自定义字段。

参数名	变量	类型[长度限制]	必填	描述
开始时间	beginTime	string[1,32]	O	开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00
结束时间	endTime	string[1,32]	O	结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

领取后N天开始生效

waitDaysAfterReceive

int

O

日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推。用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。
示例值：7

-固定面额满减券使用规则

fixedNormalCoupon

object

三选一

stockType为NORMAL时必填。

参数名	变量	类型[长度限制]	必填	描述
优惠金额	discountAmount	int64	M	优惠金额，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：5
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-折扣券使用规则

discountCoupon

object

stockType为DISCOUNT时必填

参数名	变量	类型[长度限制]	必填	描述
折扣比例	discountPercent	int	M	折扣百分比，例如：86为八六折示例值：86
消费门槛	transactionMinimum	int64	M	消费门槛，单位分特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-换购券使用规则

exchangeCoupon

object

stockType为EXCHANGE时必填。

参数名	变量	类型[长度限制]	必填	描述
单品换购价	exchangePrice	int64	M	单品换购价，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100

核销方式

useMethod

string[1,128]

M

枚举值：
OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。
PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
示例值：OFF_LINE

小程序appid

miniProgramsAppid

string[1,32]

C

核销方式为线上小程序核销才有效。
示例值：wx23232232323

小程序path

miniProgramsPath

string[1,128]

C

核销方式为线上小程序核销才有效。
示例值：/path/index/index

-自定义入口

customEntrance

object

O

卡详情页面，可选择多种入口引导用户。

参数名

变量

类型[长度限制]

必填

描述

-小程序入口

miniProgramsInfo

object

O

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名	变量	类型[长度限制]	必填	描述
商家小程序appid	miniProgramsAppid	string[1,32]	商家小程序appid要与归属商户号有M-A or M-m-suba关系。示例值：wx234545656765876
商家小程序path	miniProgramsPath	string[1,128]	M	商家小程序path 示例值：/path/index/index
入口文案	entranceWords	string[1,5]	M	入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购
引导文案	guidingWords	string[1,6]	O	小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠

商户公众号appid

appId

string[1,32]

O

可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
示例值：wx324345hgfhfghfg

营销馆id

hallId

string[1,64]

O

填写微信支付营销馆的馆id，用户自定义字段。示例值：233455656

可用门店id

storeId

string[1,64]

O

填写代金券可用门店id，用户自定义字段。
示例值：233554655

code展示模式

codeDisplayMode

string[1,8]

O

枚举值：
NOT_SHOW：不展示code
BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

券code

couponCode

string[1,32]

O

券的唯一标识。
示例值：123446565767

批次号

stockId

string[1,20]

O

微信为每个商家券批次分配的唯一ID，是否指定批次号查询。
示例值：1002323

券可使用开始时间

availableStartTime

string[1,32]

M

1、用户领取到该张券实际可使用的开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

券过期时间

expireTime

string[1,32]

M

用户领取到该张券的过期时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

券领券时间

receiveTime

string[1,32]

M

用户领取到该张券的时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

发券请求单号

sendRequestNo

string[1,32]

M

发券时传入的唯一凭证
示例值: MCHSEND202003101234

核销请求单号

useRequestNo

string[1,32]

O

核销时传入的唯一凭证（如券已被核销，将返回此字段）
示例值: MCHUSE202003101234

券核销时间

useTime

string[1,32]

O

券被核销的时间（如券已被核销，将返回此字段）；遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

总数量

totalCount

int

M

总数量
示例值： 100

分页页码

offset

int

M

分页页码
示例值：1

分页大小

limit

int

M

分页大小
示例值：10

卡券背景颜色图

18.5 示例

{
  "status": "SUCCESS",
  "code": 1000,
  "msg": "Sucess",
  "data": {
    "data": [
      {
        "belongMerchant": "432574673243",
        "stockName": "双十一活动",
        "comment": "仅限活动使用",
        "goodsName": null,
        "stockType": "NORMAL",
        "transferable": null,
        "shareable": null,
        "couponState": "SENDED",
        "displayPatternInfo": {
          "description": null,
          "merchantLogoUrl": null,
          "merchantName": "BM",
          "backgroundColor": "Color020",
          "couponImageUrl": null
        },
        "couponUseRule": {
          "couponAvailableTime": {
            "availableBeginTime": "2022-10-20T13:29:35+08:00",
            "availableEndTime": "2022-11-20T13:29:35+08:00",
            "availableDayAfterReceive": null,
            "availableWeek": null,
            "irregularyAvaliableTime": [],
            "waitDaysAfterReceive": 0
          },
          "fixedNormalCoupon": {
            "discountAmount": 10,
            "transactionMinimum": 10
          },
          "discountCoupon": null,
          "exchangeCoupon": null,
          "useMethod": "PAYMENT_CODE",
          "miniProgramsAppid": null,
          "miniProgramsPath": null
        },
        "customEntrance": {
          "miniProgramsInfo": null,
          "appId": "wx5784235254212",
          "hallId": null,
          "storeId": null,
          "codeDisplayMode": null
        },
        "couponCode": "a111",
        "stockId": "123222222222000001",
        "availableStartTime": "2022-10-20T13:29:35+08:00",
        "expireTime": "2022-11-20T13:29:35+08:00",
        "receiveTime": "2022-11-08T18:11:23+08:00",
        "sendRequestNo": "232312432334232",
        "useRequestNo": null,
        "useTime": null
      }
    ],
    "totalCount": 1,
    "offset": 0,
    "limit": 20
  }
}

19.商家券修改批次预算

19.1 功能描述

商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量

19.2 接口地址

请求地址：/V1/stocks/editBatchBudget
请求方式：POST

19.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
批次号	stockId	string[1,20]	M	批次号示例值：98065001
结算币种	currency	string[3]	M	支持币种，详见货币列表。示例值：HKD
目标批次最大发放个数	targetMaxCoupons	int	二选一	批次最大发放个数注：目标批次即修改后的批次示例值：3000
目标单天发放上限个数	targetMaxCouponsByDay	int	二选一	单天发放上限个数注：目标批次即修改后的批次示例值：500

19.3.1 示例

{
    "targetMaxCoupons":15,
    "stockId":"123222222222387777",
    "currency":"HKD"
}

19.4 返回参数列表（data，响应信息）

参数名	变量	描述
状态码	code	请求状态码
状态描述	message	状态描述
批次当前最大发放个数	maxCoupons	批次最大发放个数示例值：300
当前单天发放上限个数	maxCouponsByDay	当前单天发放上限个数示例值：100

19.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":"SUCCESS",
        "maxCoupons":15,
        "maxCouponsByDay":null
    }
}

20.商家券使券失效

20.1 功能描述

商户可通过该接口将单张领取后未核销的券进行失效处理，券失效后无法再被核销

20.2 接口地址

请求地址：/V1/stocks/couponsDeactivate
请求方式：POST

20.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
券code	couponCode	string[1,32]	M	券的唯一标识示例值：sxxe34343434
结算币种	currency	string[3]	M	支持币种，详见货币列表
批次号	stockId	string[1,20]	M	券的所属批次号示例值：1234567891
失效流水号	failureSerialNo	string[1, 128]	M	每次失效请求的唯一标识，商户需保证唯一：1002600620019090123143254436
失效原因	deactivateReason	string[1, 64]	O	商户失效券的原因示例值：此券使用时间设置错误

20.3.1 示例

{
    "couponCode":"a123",
    "currency":"HKD",
    "deactivateReason":"",
    "failureSerialNo":"123",
    "stockId":"1232222222000383336"
}

20.4返回参数列表（data，响应信息）

参数名	变量	描述
状态码	code	示例值：SUCCESS
状态描述	message	状态描述
券成功失效的时间	wechatpayDeactivateTime	券成功失效的时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2020-05-20T13:29:35.08:00

20.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":null,
        "wechatpayDeactivateTime":"2022-11-08T14:28:21+08:00"
    }
}

21.修改商家券基本信息

21.1 功能描述

商户可以通过该接口修改商家券基本信息

21.2 接口地址

请求地址：/V1/stocks/editSecuritiesInfo
请求方式：POST

21.3 请求参数列表

参数名

变量

类型[长度限制]

必填

描述

批次号

stockId

string[1,20]

M

批次号
示例值：101156451224

结算币种

currency

string[3]

M

支持币种，详见货币列表。
示例值：HKD

-自定义入口

stocksCustomEntrance

object

O

卡详情页面，可选择多种入口引导用户

参数名

变量

类型[长度限制]

必填

描述

-小程序入口

miniProgramsInfo

object

O

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。appid要与归属商户号有绑定关系

参数名	变量	类型[长度限制]	必填	描述
商家小程序appid	miniProgramsAppid	string[1,32]	C	需要小程序appid与归属商户号有绑定关系示例值：wx234545656765876
商家小程序path	miniProgramsPath	string[1,128]	C	商家小程序path 示例值：/path/index/index
入口文案	entranceWords	string[1,5]	C	入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购
引导文案	guidingWords	string[1,6]	O	小程序入口引导文案，字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠

商户公众号appid

appid

string[1,32]

O

可配置商户公众号，从券详情可跳转至公众号
示例值：wx324345hgfhfghfg

营销馆id

hallId

string[1,64]

O

填写微信支付营销馆的馆id，用户自定义字段。示例值：233455656

code展示模式

codeDisplayMode

string[1,8]

O

枚举值：
NOT_SHOW：不展示
code BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

批次备注

comment

string[1,20]

O

仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：活动使用

适用商品范围

goodsName

string[1,15]

O

用来描述批次在哪些商品可用，会显示在微信卡包中。字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx商品使用

商户请求单号

outRequestNo

string[1,128]

M

商户修改批次凭据号（格式：商户id+日期+流水号），商户侧需保持唯一性。
示例值：6122352020010133287985742

-样式信息

stocksDisplayPatternInfo

object

O

创建批次时的样式信息。

参数名

变量

类型[长度限制]

必填

描述

使用须知

description

string[1, 1000]

O

用于说明详细的活动规则，会展示在代金券详情页。
示例值：xxx门店可用

背景颜色

backgroundColor

string[1,15]

O

代金券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值：Color020

券详情图片

couponImageUrl

string[1,128]

O

券详情图片，1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。
仅支持通过《图片上传API》接口获取的图片URL地址。
示例值：https://qpic.cn/xxx

- 视频号相关信息

stocksFinderInfo

object

O

视频号相关信息

参数名	变量	类型[长度限制]	必填	描述
视频号ID	finderId	string[1,32]	C	关联视频号将展示在优惠券详情的顶部右侧，作为跳转去视频号的入口，请求参数请配置视频号ID，请前往视频号助手管理查看视频号ID 示例值：sph6Rngt2T4RlUf
视频号视频ID	finderVideoId	string[1,256]	C	券详情视频内容，支持配置关联视频号下的具体视频内容，请求参数请配置视频ID，请前往视频号助手管理后台复制具体视频ID 示例值：export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
视频号封面图	finderVideoCoverImageUrl	string[1,256]	C	截取的视频号图片将在券到期提醒消息、券详情中展示。 1.图片尺寸：1074像素（宽）*603像素（高），图片大小不超过2M，支持JPG/PNG格式。 2.仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://wxpaylogo.qpic.cn/xxx

-核销规则

stocksCouponUseRule

object

O

body券核销相关规则

参数名	变量	类型[长度限制]	必填	描述
核销方式	useMethod	string[1,128]	O	核销方式,枚举值： OFF_LINE：线下滴码核销 MINI_PROGRAMS：小程序核销 SELF_CONSUME：用户自主核销 PAYMENT_CODE：微信支付付款码核销示例值：OFF_LINE
小程序appid	miniProgramsAppid	string[1,32]	O	核销方式为线上小程序核销才有效示例值：wx23232232323
小程序path	miniProgramsPath	string[1,128]	O	核销方式为线上小程序核销才有效示例值：/path/index/index

-发放规则

stockSendRule

object

O

券发放相关规则

参数名	变量	类型[长度限制]	必填	描述
可疑账号拦截	preventApiAbuse	boolean	O	不填默认否，枚举值： true：是 false：否示例值：false

-事件通知配置

stocksNotifyConfig

object

O

事件回调通知商户的配置

参数名	变量	类型[长度限制]	必填	描述
事件通知appid	notifyAppid	string[1, 64]	O	用于回调通知时，计算返回操作用户的openid（诸如领券用户），支持小程序or公众号的APPID；如该字段不填写，则回调通知中涉及到用户身份信息的openid与unionid都将为空。示例值：wx23232232323

卡券背景颜色图

21.3.1 示例

{
    "stockSendRule":{
        "preventApiAbuse":"false"
    },
    "stocksNotifyConfig":{
        "notifyAppid":""
    },
    "productCode":"",
    "stocksCouponUseRule":{
        "useMethod":"",
        "miniProgramsAppid":"",
        "miniProgramsPath":""
    },
    "stockId":"122223220000003386",
    "currency":"HKD",
    "comment":"不限期",
    "stocksCustomEntrance":{
        "codeDisplayMode":"",
        "miniProgramsInfo":{
            "guidingWords":"",
            "miniProgramsAppid":"",
            "miniProgramsPath":"",
            "entranceWords":""
        },
        "hallId":"",
        "appid":""
    },
    "stocksDisplayPatternInfo":{
        "backgroundColor":"",
        "description":"",
        "couponImageUrl":"",
        "stocksFinderInfo":{
            "finderVideoCoverImageUrl":"",
            "finderId":"",
            "finderVideoId":""
        }
    },
    "goodsName":"不限",
    "merchantNo":""
}

21.4 返回参数列表

参数名	变量	必填	描述
请求状态	status	M	成功SUCCESS,请求已接收失败FAIL 示例值：SUCCESS
状态码	code	M	请求状态码
状态描述	msg	M	状态描述

21.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":null
    }
}

22.查询用户单张券详情

22.1 功能描述

商户可通过该接口查询微信用户卡包中某一张商家券的详情信息。

22.2 接口地址

请求地址：/V1/stocks/queryOneUserCouponsInfo
请求方式：POST

22.3请求参数列表

参数名	变量	类型[长度限制]	必填	描述
券code	couponCode	string[1,32]	M	券的唯一标识。示例值：123446565767
结算币种	currency	string[3]	M	支持币种，详见货币列表
公众账号ID	appid	string[1,32]	M	支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。校验规则：传入的APPID得是与调用方商户号（即请求头里面的商户号）有绑定关系的APPID或传入的APPID得是归属商户号有绑定关系的APPID 示例值：wx233544546545989
用户标识	openid	string[1,128]	M	Openid信息，用户在appid下的唯一标识。校验规则：传入的openid得是调用方商户号（即请求头里面的商户号）有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。示例值：2323dfsdf342342

22.3.1 示例

{
    "appid":"wxdnfdkmfo5",
    "couponCode":"a123",
    "currency":"HKD",
    "openid":"okjsidfisdmASMOISMDO"
}

22.4 返回参数列表（data，响应信息）

参数名

变量

类型[长度限制]

必填

描述

状态码

code

string

M

请求状态码。
示例值：USUCCESS

状态描述

message

string

M

状态描述。
示例值：SUCCESS

批次归属商户号

belongMerchant

string[8,15]

M

批次归属于哪个商户。
示例值：10000022

商家券批次名称

stockName

string[1,21]

M

批次名称，字数上限为21个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：商家券

批次备注

comment

string[1,20]

O

仅配置商户可见，用于自定义信息。字数上限为20个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx可用

适用商品范围

goodsName

string[1,15]

M

适用商品范围，字数上限为15个，一个中文汉字/英文字母/数字均占用一个字数。
示例值：xxx商品可用

批次类型

stockType

string[1,128]

M

批次类型
NORMAL：固定面额满减券批次
DISCOUNT：折扣券批次
EXCHANGE：换购券批次
示例值：NORMAL

是否允许转赠

transferable

bool

O

不填默认否，枚举值：
true：是
false：否
该字段暂未开放
示例值：false

是否允许分享领券链接

shareable

bool

O

不填默认否，枚举值：
true：是
false：否
该字段暂未开放
示例值：false

券状态

couponState

string[1,16]

O

商家券状态

枚举值：
SENDED：可用
USED：已核销
EXPIRED：已过期
DEACTIVATED：已失效
示例值：SENDED

-样式信息

displayPatternInfo

object

O

商家券详细信息

参数名

变量

类型[长度限制]

必填

描述

使用须知

description

string[1,1000]

O

用于说明详细的活动规则，会展示在代金券详情页。
示例值：深圳南山门店可用

商户logo

merchantLogoUrl

string[1,128]

O

若券归属商户号有认证品牌，则系统将自动拉取对应品牌logo；若券归属商户号不在认证品牌下，需自定义上传logo，未上传时将展示兜底灰色logo样式，影响券详情页用户体验，请及时上传。
示例值：https://qpic.cn/xxx

商户名称

merchantName

string[1,16]

O

不支持商户自定义。若券归属商户号有认证品牌，系统将自动拉取认证品牌号下的品牌名称；若券归属商户号不在认证品牌下，则拉取本商户号的商户简称。展示上限12个字符。
示例值：微信支付

背景颜色

backgroundColor

string[1,15]

O

代金券的背景颜色，可设置10种颜色，色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值：Color020

券详情图片

couponImageUrl

string[1,128]

O

券详情图片， 850像素*350像素，且图片大小不超过2M，支持JPG/PNG格式示例值：https://qpic.cn/xxx

- 视频号相关信息

stocksFinderInfo

object

O

视频号相关信息

参数名	变量	类型[长度限制]	必填	描述
视频号ID	finderId	string[1,32]	M	关联视频号将展示在优惠券详情的顶部右侧，作为跳转去视频号的入口，请求参数请配置视频号ID，请前往视频号助手管理查看视频号ID 示例值：sph6Rngt2T4RlUf
视频号视频ID	finderVideoId	string[1,256]	M	券详情视频内容，支持配置关联视频号下的具体视频内容，请求参数请配置视频ID，请前往视频号助手管理后台复制具体视频ID 示例值：export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
视频号封面图	finderVideoCoverImageUrl	string[1,256]	M	截取的视频号图片将在券到期提醒消息、券详情中展示。 1.图片尺寸：716像素（宽）*402像素（高）；图片大小不超过2M，支持JPG/PNG格式。 2.仅支持通过《图片上传API》接口获取的图片URL地址。示例值：https://wxpaylogo.qpic.cn/xxx

-券核销规则

couponUseRule

券核销规则

M

券核销相关规则

参数名

变量

类型[长度限制]

必填

描述

-券可核销时间

couponAvailableTime

object

M

日期区间内可以使用优惠。

参数名

变量

类型[长度限制]

必填

描述

开始时间

availableBeginTime

string[1,32]

M

批次开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：开始时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

结束时间

availableEndTime

string[1,32]

M

批次结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。
注意：结束时间设置有效期最长为1年。
示例值：2015-05-20T13:29:35+08:00

生效后N天内有效

availableDayAfterReceive

int

O

日期区间内，券生效后x天内有效。例如生效当天内有效填1，生效后2天内有效填2，以此类推。注意，用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数，无论用户何时领取商家券，商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写，也可单独填写。单独填写时，有效期内领券后立即生效，生效后x天内有效。
示例值：3

- 固定周期有效时间段

stocksAvailableWeek

object

O

可以设置多个星期下的多个可用时间段，比如每周二10点到18点，用户自定义字段。

参数名

变量

类型[长度限制]

必填

描述

可用星期数

weekDay

array[int]

O

0代表周日，1代表周一，以此类推。
示例值：1, 2

- 当天可用时间段

availableDayTime

array

O

可以填写多个时间段，最多不超过2个。

参数名	变量	类型[长度限制]	必填	描述
当天可用开始时间	beginTime	int	O	当天可用开始时间，单位：秒，1代表当天0点0分1秒。示例值：3600
当天可用结束时间	endTime	int	O	当天可用结束时间，单位：秒，86399代表当天23点59分59秒。示例值：86399

- 无规律的有效时间段

irregularyAvaliableTime

array

O

无规律的有效时间，多个无规律时间段，用户自定义字段。

参数名	变量	类型[长度限制]	必填	描述
开始时间	beginTime	string[1,32]	O	开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00
结束时间	endTime	string[1,32]	O	结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00

领取后N天开始生效

waitDaysAfterReceive

int

O

日期区间内，用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写，领券后第2天开始生效填1，以此类推。用户在有效期开始前领取商家券，则从有效期第1天开始计算天数，用户在有效期内领取商家券，则从领取当天开始计算天数。无论用户何时领取商家券，商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写，不可单独填写。
示例值：7

-固定面额满减券使用规则

fixedNormalCoupon

object

三选一

stockType为NORMAL时必填。

参数名	变量	类型[长度限制]	必填	描述
优惠金额	discountAmount	int64	M	优惠金额，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：5
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-折扣券使用规则

discountCoupon

object

stockType为DISCOUNT时必填。

参数名	变量	类型[长度限制]	必填	描述
折扣比例	discountPercent	int	M	折扣百分比，例如：86为八六折。示例值：86
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 1 ≤ value ≤ 10000000 示例值：100

-换购券使用规则

exchangeCoupon

object

stockType为EXCHANGE时必填。

参数名	变量	类型[长度限制]	必填	描述
单品换购价	exchangePrice	int64	M	单品换购价，单位分特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100
消费门槛	transactionMinimum	int64	M	消费门槛，单位：分。特殊规则：取值范围 0 ≤ value ≤ 10000000 示例值：100

核销方式

useMethod

string[1,128]

M

枚举值：
OFF_LINE：线下滴码核销，点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS：线上小程序核销，点击券“立即使用”跳转至配置的商家小程序（需要添加小程序appid和path）。
PAYMENT_CODE：微信支付付款码核销，点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME：用户自助核销，点击券“立即使用”跳转至用户自助操作核销界面（当前暂不支持用户自助核销）。
示例值：OFF_LINE

小程序appid

miniProgramsAppid

string[1,32]

C

核销方式为线上小程序核销才有效。
示例值：wx23232232323

小程序path

miniProgramsPath

string[1,128]

C

核销方式为线上小程序核销才有效。
示例值：/path/index/index

-自定义入口

customEntrance

object

O

卡详情页面，可选择多种入口引导用户。

参数名

变量

类型[长度限制]

必填

描述

-小程序入口

miniProgramsInfo

object

O

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序，APPID、path、入口文案为必填，引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名	变量	类型[长度限制]	必填	描述
商家小程序appid	miniProgramsAppid	string[1,32]	M	商家小程序appid要与归属商户号有M-A or M-m-suba关系。示例值：wx234545656765876
商家小程序path	miniProgramsPath	string[1,128]	M	商家小程序path 示例值：/path/index/index
入口文案	entranceWords	string[1,5]	M	入口文案，字数上限为5个，一个中文汉字/英文字母/数字均占用一个字数。示例值：欢迎选购
引导文案	guidingWords	string[1,6]	O	小程序入口引导文案，用户自定义字段。字数上限为6个，一个中文汉字/英文字母/数字均占用一个字数。示例值：获取更多优惠

商户公众号appid

appid

string[1,32]

O

可配置商户公众号，从券详情可跳转至公众号，用户自定义字段。
示例值：wx324345hgfhfghfg

营销馆id

hallId

string[1,64]

O

填写微信支付营销馆的馆id，用户自定义字段。示例值：233455656

可用门店id

storeId

string[1,64]

O

填写代金券可用门店id，用户自定义字段。
示例值：233554655

code展示模式

codeDisplayMode

string[1,8]

O

枚举值：
NOT_SHOW：不展示code
BARCODE：一维码
QRCODE：二维码
示例值：BARCODE

券code

couponCode

string[1,32]

O

券的唯一标识。
示例值：123446565767

批次号

stockId

string[1,20]

O

微信为每个商家券批次分配的唯一ID，是否指定批次号查询。
示例值：1002323

券可使用开始时间

availableStartTime

string[1,32]

M

1、用户领取到该张券实际可使用的开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
2、若券批次设置为领取后可用，则开始时间即为券的领取时间；若券批次设置为领取后第X天可用，则开始时间为券领取时间后第X天00:00:00可用。
示例值：2019-12-30T13:29:35+08:00

券过期时间

expireTime

string[1,32]

M

用户领取到该张券的过期时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

券领券时间

receiveTime

string[1,32]

M

用户领取到该张券的时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

发券请求单号

sendRequestNo

string[1,64]

M

发券时传入的唯一凭证
示例值: MCHSEND202003101234

核销请求单号

useRequestNo

string[1,32]

O

核销时传入的唯一凭证（如券已被核销，将返回此字段）
示例值: MCHUSE202003101234

券核销时间

useTime

string[1,32]

O

券被核销的时间（如券已被核销，将返回此字段）；遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35+08:00

卡券背景颜色图

22.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":"SUCCESS",
        "belongMerchant":"432553075",
        "stockName":"双十一活动",
        "comment":"仅限活动使用",
        "goodsName":"xxx商店可用",
        "stockType":"NORMAL",
        "transferable":null,
        "shareable":null,
        "couponState":"SENDED",
        "displayPatternInfo":{
            "description":"",
            "merchantLogoUrl":"https://wx.gtimg.com/resource/feuploader/202106/holder_logo_240x240.png",
            "merchantName":"BM",
            "backgroundColor":"Color020",
            "couponImageUrl":"",
            "stocksFinderInfo":null
        },
        "couponUseRule":{
            "couponAvailableTime":{
                "availableBeginTime":"2022-10-20T13:29:35+08:00",
                "availableEndTime":"2022-11-20T13:29:35+08:00",
                "stocksAvailableWeek":null,
                "irregularyAvaliableTime":[
                ],
                "availableDayAfterReceive":null,
                "waitDaysAfterReceive":0
            },
            "fixedNormalCoupon":{
                "discountAmount":10,
                "transactionMinimum":10
            },
            "discountCoupon":null,
            "exchangeCoupon":null,
            "useMethod":"PAYMENT_CODE",
            "miniProgramsAppid":null,
            "miniProgramsPath":null
        },
        "customEntrance":{
            "miniProgramsInfo":null,
            "appid":null,
            "hallId":null,
            "storeId":null,
            "codeDisplayMode":null
        },
        "couponCode":"a111",
        "stockId":"123222222000000002",
        "availableStartTime":"2022-10-20T13:29:35+08:00",
        "expireTime":"2022-11-20T13:29:35+08:00",
        "receiveTime":"2022-11-08T18:11:23+08:00",
        "sendRequestNo":"14074736748399293123",
        "useRequestNo":null,
        "useTime":null
    }
}

23.设置商家券事件通知地址

23.1 功能描述

用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。

23.2 接口地址

请求地址：/V1/stocks/notifyUrl
请求方式：POST

23.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表
通知URL地址	notifyUrl	string[10,256]	M	商户提供的用于接收商家券事件通知的url地址，必须支持https。示例值：`https://pay.weixin.qq.com`

23.3.1 示例

{
    "settleCurrency":"HKD",
    "notifyUrl":"https://pay.weixinzhifu.qq.com"
}

23.4 返回参数列表（data，响应信息）

参数名	变量	描述
通知URL地址	notifyUrl	商户提供的用于接收商家券事件通知的url地址，必须支持https。示例值：`https://pay.weixinzhifu.qq.com`

23.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "notifyUrl":"https://pay.weixinzhifu.qq.com"
    }
}

24.查询商家券时间通知地址

24.1 功能描述

通过调用此接口可查询设置的通知URL。

24.2 接口地址

请求地址：/V1/stocks/queryNotify
请求方式：POST

24.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表

24.3.1 示例

{
    "settleCurrency":"HKD"
}

24.4 返回参数列表（data，响应信息）

参数名	变量	描述
通知URL地址	notifyUrl	商户提供的用于接收商家券事件通知的url地址，必须支持https。示例值：`https://pay.weixinzhifu.qq.com`

24.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "notifyUrl":"https://pay.weixin.qq.com"
    }
}

25 回调通知接口

25.1 功能描述

请求URL：该链接是通过【设置商家券事件通知地址API】提交notify_url参数设置，必须为https协议。如果链接无法访问，商户将无法接收到微信通知。通知url必须为直接可访问的url，不能携带参数。示例：https://pay.weixin.qq.com/wxpay/pay.action

通知规则
领券完成后，会把相关领券结果和用户信息发送给商户，商户需要接收处理，并按照文档规范返回应答。出于安全的考虑，我们对支付结果数据进行了加密，商户需要先对通知数据进行解密，才能得到支付结果数据。

对后台通知交互时，如果我们收到应答不是成功或超时，我们认为通知失败，我们会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。（通知频率为60s/次 - 总计11次）

通知报文
领券结果通知是以POST 方法访问商户设置的通知url，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。

25.2 通知参数信息

参数名	变量	类型[长度限制]	必填	描述
事件类型	eventType	string[1,32]	M	业务细分事件类型，枚举值： EVENT_TYPE_BUSICOUPON_SEND：商家券用户领券通知示例值：EVENT_TYPE_BUSICOUPON_SEND
券code	couponCode	string[1,32]	M	券的唯一标识。示例值：1227944959000000911017
批次号	stockId	string[1,32]	M	批次号示例值：1286950000000039
发放时间	sendTime	string[1,32]	M	发放时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日 13点29分35秒。示例值：2015-05-20T13:29:35+08:00
用户标识	openid	string[1,128]	M	微信用户在appid下的唯一标识。示例值：odXnH1CJjeQ6666648db-pnxs-Wg
用户统一标识	unionid	string[1,128]	O	微信用户在同一个微信开放平台账号下的唯一用户标识。示例值：oOuyajgxj0oVw888SoQm6mp7PGKw
发放渠道	sendChannel	string	M	发放渠道，枚举值： BUSICOUPON_SEND_CHANNEL_MINIAPP：小程序 BUSICOUPON_SEND_CHANNEL_API：API BUSICOUPON_SEND_CHANNEL_PAYGIFT：支付有礼 BUSICOUPON_SEND_CHANNEL_H5：H5 BUSICOUPON_SEND_CHANNEL_FTOF：面对面 BUSICOUPON_SEND_CHANNEL_MEMBERCARD_ACT：会员卡活动 BUSICOUPON_SEND_CHANNEL_HALL：扫码领券（营销馆） BUSICOUPON_SEND_CHANNEL_JSAPI：JSAPI BUSICOUPON_SEND_CHANNEL_MINI_APP_LIVE：微信小程序直播 BUSICOUPON_SEND_CHANNEL_WECHAT_SEARCH：搜一搜 BUSICOUPON_SEND_CHANNEL_PAY_HAS_DISCOUNT：微信支付有优惠 BUSICOUPON_SEND_CHANNEL_WECHAT_AD：微信广告 BUSICOUPON_SEND_CHANNEL_RIGHTS_PLATFORM：权益平台 BUSICOUPON_SEND_CHANNEL_RECEIVE_MONEY_GIFT：收款有礼 BUSICOUPON_SEND_CHANNEL_MEMBER_PAY_RIGHT：会员付费权益 BUSICOUPON_SEND_CHANNEL_BUSI_SMART_RETAIL：智慧零售活动 BUSICOUPON_SEND_CHANNEL_FINDER_LIVEROOM：视频号直播示例值：BUSICOUPON_SEND_CHANNEL_MINIAPP
发券商户号	sendMerchant	string[1,16]	M	发券商户号示例值：98568888

25.3 通知应答

接收成功：HTTP应答状态码需返回200或204，无需返回应答报文。

接收失败：HTTP应答状态码需返回5XX或4XX，同时需返回应答报文，格式如下：

参数名	变量	类型[长度限制]	必填	描述
返回状态码	code	string[1,32]	是	错误码，SUCCESS为接收成功，其他错误码为失败。示例值：FAIL
返回信息	message	string[1,64]	是	返回信息，如非空，为错误原因。示例值：失败

25.3.1 示例

{
    "code": "FAIL",
    "message": "失败"
}

26 图片上传

26.1功能描述

通过本接口上传图片后可获得图片url地址。图片url可在微信支付营销相关的API使用。

26.2接口地址

请求地址：/V1/stocks/uploadPictures
请求方式：POST
请求主体类型：multipart/form-data

26.3 请求参数列表

参数名	变量	类型[长度限制]	必填	描述
结算币种	settleCurrency	string[3]	M	支持币种，详见货币列表
图片文件	file	file	M	文件文件后缀必须为.bmp/.jpg/.png 文件不能超过2M

26.3.1 示例

{
    "file":"/user/pic/1.jpg",
    "settleCurrency":"HKD"
}

26.4 返回参数列表（data，响应信息）

参数名	变量	描述
状态码	code	状态码，
状态描述	message	状态描述
媒体文件URL地址	mediaUrl	微信返回的媒体文件标识url。有效期为永久示例值：https://qpic.cn/xxx

26.4.1 示例

{
    "status":"SUCCESS",
    "code":1000,
    "msg":"Sucess",
    "data":{
        "code":"SUCCESS",
        "message":"SUCCESS",
        "mediaUrl":"https://pay.weixin.qq.com"
    }
}

27 微信营销建立合作关系

27.1功能描述

该接口主要为商户提供营销资源的授权能力，可授权给其他商户或小程序，方便商户间的互利合作。

27.2接口地址

请求地址：/V1/stocks/partnershipbind
请求方式：POST

27.3 请求参数列表

参数名

变量

类型[长度限制]

必填

描述

-结算币种

settleCurrency

string[3]

是

商户入网指定的账户结算币种

-合作方信息

partner

object

是

body 合作方相关的信息。

参数名	变量	类型[长度限制]	必填	描述
合作方类别	type	string[1,32]	是	合作方类别，枚举值： APPID：合作方为APPID MERCHANT：合作方为商户示例值：APPID
合作方APPID	appid	string[1,32]	否	合作方APPID，合作方类别为APPID时必填。示例值：wx4e1916a585d1f4e9
合作方商户ID	merchantId	string[8,15]	否	合作方商户ID，合作方类别为MERCHANT时必填。示例值：2480029552

-被授权数据

authorizedData

object

是

body 被授权的数据。

参数名	变量	类型[长度限制]	必填	描述
授权业务类别	businessType	string[1,32]	是	授权业务类别，枚举值： FAVOR_STOCK：代金券批次（暂不支持合作方为商户的场景） BUSIFAVOR_STOCK：商家券批次示例值：FAVOR_STOCK
授权批次ID	stockId	string[1,20]	否	授权批次ID，授权业务类别为商家券批次或代金券批次时，此参数必填。示例值：2433405

27.3.1 示例

{
  "settleCurrency":"HKD",
  "partner":{
    "type":"APPID",
    "appid":"wx87b0b416003b0175"
  },
  "authorizedData":{
    "businessType":"BUSIFAVOR_STOCK",
    "stockId":"1232200000000425"
  }
}

27.4 返回参数列表（data，响应信息）

参数名

变量

类型[长度限制]

必填

描述

+合作方信息

partner

object

是

合作方相关的信息。

参数名	变量	类型[长度限制]	必填	描述
合作方类别	type	string[1,32]	是	合作方类别，枚举值： APPID：合作方为APPID MERCHANT：合作方为商户示例值：APPID
合作方APPID	appid	string[1,32]	否	合作方APPID，合作方类别为APPID时必填。示例值：wx4e1916a585d1f4e9
合作方商户ID	merchantId	string[8,15]	否	合作方商户ID，合作方类别为MERCHANT时必填。示例值：2480029552

+被授权数据

authorizedData

object

是

被授权的数据。

参数名	变量	类型[长度限制]	必填	描述
授权业务类别	businessType	string[1,32]	是	授权业务类别，枚举值： FAVOR_STOCK：代金券批次 BUSIFAVOR_STOCK：商家券批次示例值：FAVOR_STOCK
授权批次ID	stockId	string[1,20]	否	授权批次ID，授权业务类别为商家券批次或代金券批次时，此参数必填。示例值：2433405

合作状态

state

string[1,32]

是

合作状态，枚举值：
ESTABLISHED：已建立
TERMINATED：已终止
示例值：ESTABLISHED

建立合作关系时间

buildTime

string[1,32]

是

建立合作关系时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.120+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35.120+08:00

创建时间

createTime

string[1,32]

是

创建时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.120+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35.120+08:00

更新时间

updateTime

string[1,32]

是

更新时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.120+08:00表示，北京时间2015年5月20日 13点29分35秒。
示例值：2015-05-20T13:29:35.120+08:00

27.4.1 示例

{
    "status": "SUCCESS",
    "code": 1000,
    "msg": "Sucess",
    "data": {
        "buildTime": "2023-12-12T18:32:23+08:00",
        "updateTime": "2023-12-13T10:26:52+08:00",
        "partner": {
            "type": "APPID",
            "merchantId": "",
            "appid": "wx87b0b416003b0175"
        },
        "createTime": "2023-12-12T18:32:23+08:00",
        "authorizedData": {
            "stockId": "1232200000000425",
            "businessType": "BUSIFAVOR_STOCK"
        },
        "state": "ESTABLISHED"
    }
}