开发指引
更新时间：2024.01.19# 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后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
- 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：
- 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。
# 3. 快速接入
# 3.1. 业务流程图
# 业务流程时序图
重点步骤说明：
步骤5 商户创建商家券后，可通过《创建全场满额送活动》接口创建支付有礼活动，微信支付生成支付有礼活动并返回活动ID给到商户。
步骤20 支付有礼活动创建后，商户可通过《获取活动详情接口》查询管理活动。
步骤22 活动创建后，如需结束活动，可通过《终止活动》接口，结束活动。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】创建全场满额送活动
步骤说明：商户可以创建满额送活动，用户支付后送全场券，提升交易额。
background_color取值：
重要入参说明：
- activity_name：活动名称。
- activity_second_title：活动副标题。
- merchant_logo_url：商户logo，送出优惠券时展示， 仅支持通过《图片上传API》接口获取的图片URL地址。
- out_request_no：商户请求单号，商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。
- delivery_purpose：投放目的。枚举值：
OFF_LINE_PAY：拉用户回店消费
JUMP_MINI_APP：引导用户前往小程序消费。 - send_content：发放内容，可选单张券或礼包，选礼包时奖品限定3-5个。枚举值：
SINGLE_COUPON：单张券
GIFT_PACKAGE：礼包
更多参数、响应详情及错误码请参见创建全场满额送活动接口文档。
# 3.2.2. 【服务端】获取活动详情接口
步骤说明：商户创建活动后，可以通过该接口查询支付有礼的活动详情，用于管理活动。
重要入参说明：
activity_id：活动ID。
更多参数、响应详情及错误码请参见获取活动详情接口接口文档。
# 3.2.3. 【服务端】获取活动发券商户号
步骤说明：商户创建活动后，可以通过该接口查询支付有礼的发券商户号，用于管理活动。
重要入参说明：
- activity_id：活动ID。
更多参数、响应详情及错误码请参见获取活动发券商户号接口文档。
# 3.2.4. 【服务端】获取活动指定商品列表
步骤说明：商户创建活动后，可以通过该接口查询支付有礼的活动指定商品，用于管理活动。
重要入参说明：
- activity_id：活动ID。
更多参数、响应详情及错误码请参见获取活动指定商品列表接口文档。
# 3.2.5. 【服务端】终止活动
步骤说明：商户可通过该接口停止支付有礼活动。
重要入参说明：
- activity_id：活动ID。
更多参数、响应详情及错误码请参见终止活动接口文档。
# 3.2.6. 【服务端】新增活动发券商户号
步骤说明：商户创建活动后，可以通过该接口增加支付有礼的发券商户号，用于管理活动。
重要入参说明：
- activity_id：活动ID。
- add_request_no：请求业务单据号，商户添加发券商户号的凭据号，商户侧需保持唯一性。
更多参数、响应详情及错误码请参见新增活动发券商户号接口文档。
# 3.2.7. 【服务端】获取支付有礼活动列表
步骤说明：商户根据一定过滤条件，查询已创建的支付有礼活动。
重要入参说明：
- offset：分页页码，页面从0开始。
- limit：分页大小。特殊规则：最大取值为100，最小为1。
更多参数、响应详情及错误码请参见获取支付有礼活动列表接口文档。
# 3.2.8. 【服务端】删除活动发券商户号
步骤说明：商户创建活动后，可以通过该接口删除支付有礼的发券商户号，用于管理活动。
重要入参说明：
- activity_id：活动ID。
更多参数、响应详情及错误码请参见删除活动发券商户号接口文档。
# 4. 常见问题
# Q：支付有礼创建全场满额送活动API返回“发券商户号校验失败，请核实是否满足同品牌等规则”
A：支付有礼活动的曝光商户号必须是商家券归属商户号的同品牌。同品牌商户号是指同一企业/集团/品牌/公司旗下，如果存在多个微信支付商户号，该企业/集团/品牌/公司可以授权财付通支付科技有限公司将其旗下的多个商户号创建为同品牌商户号组合。主要用于更便利使用免充值营销产品功能，包括开通产品权限、配置组合内商户号为可用商户、配置活动后可用商户免审核等。
# Q：支付有礼创建全场满额送活动API返回“商家券信息不满足活动规则，请核实券有效期或code”
A：支付有礼中投放批次的校验，请按照以下几点排查：
- 单张券/券包中所有的券开始时间需早于支付有礼活动的开始时间，结束时间需晚于支付有礼的结束时间。
- 如果批次为上传code模式，需先上传code再投放到支付有礼。
- 添加券包时，库存、限领和归属商户号需要保持一致。
- 曝光商户号、批次的归属商户号需要全部为同品牌。
# Q：支付有礼创建全场满额送活动API，开始时间和结束时间描述的“最长可以配置1年内的活动”中的“1年”如何计算？
A：间隔需要小于31536000s，即需要小于365天。
# Q：支付有礼创建全场满额送活动API上传了merchant_id_list字段，接着调用了获取支付有礼活动列表API，并没有merchant_id_list返回，该字段在什么情况下才返回？
A：查询活动发券商户号API才会有这个字段返回，接口文档地址。
# Q：支付有礼发放商家券，用户领券没有收到领券事件通知OpenID
A：请检查对应的批次，调用创建商家券接口时是否有设置事件通知AppID参数（notify_appid）。
# Q：配置使用「立即使用」跳转商家小程序的能力时，有什么需要注意的地方？
A：在小程序支付场景下，当用户从支付有礼活动落地页点击「立即使用」跳转至商家小程序时，建议不处理小程序调起支付的回调结果。
