开发指引
更新时间：2023.08.23# 1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
# 2. 开发准备
# 2.1. 搭建和配置开发环境
为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传 等基础功能（更多语言版本的开发库将在近期陆续提供）。
测试步骤：
1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：
- wechatpay-java (opens new window)（推荐）、wechatpay-apache-httpclient (opens new window)，适用于Java开发者。
- 注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推荐）、wechatpay-guzzle-middleware (opens new window)，适用于PHP开发者。
- 注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，适用于Go开发者。
更多资源可前往微信支付开发者社区 (opens new window)搜索查看。
2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。
3、基于接口的示例代码，替换请求参数后可发起测试。
说明：
- 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
- 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：
- 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。
# 2.2. 业务开发配置
# 2.2.1. 开通营销事件推送能力
开通营销事件推送能力说明：
- 用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。
- 营销事件推送：点击开通产品权限。 由商家券批次创建方登录Pay平台，操作开通。
# 3. 快速接入
# 3.1. 业务流程图
# 业务流程时序图
重点步骤说明：
步骤1 商户发起创建商家券请求，可通过《创建商家券》接口创建商家券，微信支付生成商家券批次后并返回商家券批次号给到商户。
请求参数商户logo（merchant_url）的内容要求使用图片上传（营销专用）接口上传后获取
步骤4.2 商户获取到商家券批次号，需要调用《小程序发券插件》来发放商户券，并获取微信支付返回商家券发放结果。
步骤7.2 商户发券成功后，商户可通过《查询商家券批次详情》、《根据过滤条件查询用户的券》、《查询用户券详情》等商家券管理接口进行券管理，商户需核销用户券时，可通过调用《核销用户的券》来核销用户微信卡包中具体某一张商家券。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入商家券产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】创建商家券
步骤说明： 通过此接口可为有需求的商户创建商家券。当前支持创建的商家券类型包含满减券、换购券和折扣券三种。
卡券背景颜色图：
商家券样式图：
券详情信息展示：
重要入参说明：
- belong_merchant： 批次归属商户号，批次归属于哪个商户。普通商户请填写普通商户号
- out_request_no： 商户请求单号，商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性。
- max_coupons： 批次最大发放个数，批次最大可发放个数限制。特殊规则：取值范围 1 ≤ value ≤ 1000000000。
- notify_appid： 事件通知AppID，用于回调通知时，计算返回操作用户的OpenID（诸如领券用户），支持小程序or公众号的AppID；如该字段不填写，则回调通知中涉及到用户身份信息的OpenID与unionid都将为空。
更多参数、响应详情及错误码请参见创建商家券接口文档。
# 3.2.2. 【服务端】查询商家券批次详情
步骤说明： 商户可通过该接口查询已创建的商家券批次详情信息。
卡券背景颜色图：
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
更多参数、响应详情及错误码请参见查询商家券批次详情接口文档。
# 3.2.3. 【服务端】核销用户的券
步骤说明： 在用户满足优惠门槛后，商户可通过该接口核销用户微信卡包中具体某一张商家券。
重要入参说明：
- coupon_code： 券code，券的唯一标识。
- AppID： 公众账号ID，支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。核销接口返回的OpenID会在该传入AppID下进行计算获得。
- use_request_no： 核销请求单据号，每次核销请求的唯一标识，商户需保证唯一。
更多参数、响应详情及错误码请参见核销用户的券接口文档。
# 3.2.4. 【服务端】根据过滤条件查询用户券
步骤说明： 商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。
重要入参说明：
- OpenID： 用户标识，OpenID信息，用户在AppID下的唯一标识。
- AppID： 公众账号ID，支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。
更多参数、响应详情及错误码请参见根据过滤条件查询用户的券接口文档。
# 3.2.5. 【服务端】查询用户券详情
步骤说明： 商户可通过该接口查询微信用户卡包中某一张商家券的详情信息。
重要入参说明：
- coupon_code： 券code，券的唯一标识。
- OpenID： 用户标识，OpenID信息，用户在AppID下的唯一标识。
- AppID： 公众账号ID，支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。
更多参数、响应详情及错误码请参见查询用户券详情接口文档。
# 3.2.6. 【服务端】上传预存code
步骤说明： 商家券的Code码可由微信后台随机分配，同时支持商户自定义。如商家已有自己的优惠券系统，可直接使用自定义模式。即商家预先向微信支付上传券Code，当券在发放时，微信支付自动从已导入的Code中随机取值（不能指定），派发给用户。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
- upload_request_no： 请求业务单据号，商户上传code的凭据号，商户侧需保持唯一性。
更多参数、响应详情及错误码请参见上传预存code接口文档。
# 3.2.7. 【服务端】设置商家券事件通知地址
步骤说明： 用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。
注意
- 仅可以收到由商户自己创建的批次相关的通知
- 需要设置APIv3密钥，否则无法收到回调。
- 如果需要领券回调中的参数OpenID。需要创券时候传入notify_appid参数。
重要入参说明：
- notify_url： 通知URL地址，商户提供的用于接收商家券事件通知的URL地址，必须支持HTTPS。
更多参数、响应详情及错误码请参见设置商家券事件通知地址接口文档。
# 3.2.8. 【服务端】查询商家券事件通知地址
步骤说明： 通过调用此接口可查询设置的通知URL。
注意
- 仅可以查询由请求商户号设置的商家券通知URL。
重要入参说明：
- mchid： 商户号，微信支付商户的商户号，由微信支付生成并下发，不填默认查询调用方商户的通知URL。
更多参数、响应详情及错误码请参见查询商家券事件通知地址接口文档。
# 3.2.9. 【服务端】关联订单信息
步骤说明： 将有效态（未核销）的商家券与订单信息关联，用于后续参与摇奖&返佣激励等操作的统计。
注意
- 仅对有关联订单需求的券进行该操作。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
- coupon_code： 券code，券的唯一标识。
- out_trade_no： 关联的商户订单号，微信支付下单时的商户订单号，预与该商家券关联的微信支付。
- out_request_no： 商户请求单号，商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。
更多参数、响应详情及错误码请参见关联订单信息接口文档。
# 3.2.10. 【服务端】取消关联订单信息
步骤说明： 取消商家券与订单信息的关联关系。
注意
- 建议取消前调用查询接口，查到当前关联的商户单号并确认后，再进行取消操作。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID
- coupon_code： 券code，券的唯一标识。
- out_trade_no： 关联的商户订单号，微信支付下单时的商户订单号，预与该商家券关联的微信支付
- **out_request_no：**商户请求单号，商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。
更多参数、响应详情及错误码请参见取消关联订单信息接口文档
# 3.2.11. 【服务端】修改批次预算
步骤说明： 商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
- modify_budget_request_no： 修改预算请求单据号（格式：商户ID+日期+流水号），商户侧需保持唯一性。
更多参数、响应详情及错误码请参见修改批次预算接口文档。
# 3.2.12. 【服务端】修改商家券基本信息
步骤说明： 商户可以通过该接口修改商家券基本信息。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
- out_request_no： 商户请求单号，商户修改批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性。
更多参数、响应详情及错误码请参见修改商家券基本信息接口文档。
# 3.2.13. 【服务端】申请退券
步骤说明： 商户可以通过该接口为已核销的券申请退券。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID
- coupon_code： 券code，券的唯一标识。
- return_request_no： 退券请求单据号，每次退券请求的唯一标识，商户需保证唯一。
更多参数、响应详情及错误码请参见申请退券接口文档。
# 3.2.14. 【服务端】使券失效
步骤说明： 商户可通过该接口将单张领取后未核销的券进行失效处理。
重要入参说明：
- stock_id： 批次号，微信为每个商家券批次分配的唯一ID。
- coupon_code： 券code，券的唯一标识。
- deactivate_request_no： 失效请求单据号，每次失效请求的唯一标识，商户需保证唯一。
更多参数、响应详情及错误码请参见使券失效接口文档。
# 3.2.15.【服务端】领券事件回调通知
步骤说明： 领券完成后，微信会把相关领券结果和用户信息发送给商户，商户需要接收处理，并按照文档规范返回应答。出于安全的考虑，我们对支付结果数据进行了加密，商户需要先对通知数据进行解密，才能得到支付结果数据。
注意
- 领券事件通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。
- 支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱
- 对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为60s/次 - 总计11次 ）
更多参数、响应详情及错误码请参见 领券事件回调通知接口文档。
# 4. 常见问题
# Q：调用创建商家券接口返回“非法敏感图片”
A：请求参数商户logo（merchant_url）的内容要求使用图片上传（营销专用）接口上传后获取，请检查确认。
# Q：创建商家券接口，goods_name字段展示在哪里？
A：展示在商家券详情里面的优惠说明中。
# Q：调用修改商家券基本信息API返回：无法将输入源“/body/stock_id”映射到目标字段“批次号”中，此字段并非多重字段但被输入源“/uri_template/stock_id”映射过了
A：请注意参数stock_id传到请求URL里面，body里面就不用传该参数。
# Q：商家券领券回调，正常设置地址，为什么接收不到回调信息？
A：请按以下几点检查
- 请检查是否有正确设置APIv3。设置步骤如下： 【微信商户平台 (opens new window)—>账户设置—>API安全—>设置APIv3】
- 请检查回调URL是否能正常公网访问
- 如果是HTTP地址，建议更换支持HTTPS
- 是否开启了防火墙，如果开户了防火墙，请添加微信支付营销回调IP：
- 上海电信出口网段 101.226.103.0/2
- 上海联通出口网段 140.207.54.0/25
- 上海CAP出口网段 121.51.58.128/25
# Q：商家券消费门槛字段transaction_minimum不填写为什么会报错？
A：该字段属于必填字段，可以填写为0。
