接入易错点

 签名验签须匹配接口版本与密钥模式

 说明：代金券接口存在 APIv2 与 APIv3 两套签名规则；调用方与制券方为不同商户时，不能复用另一商户的密钥或证书配置。
正确应该怎么做：① 为每个代金券接口明确标注 API 版本；② APIv3 请求使用商户 API 证书私钥签名，应答与回调使用微信支付公钥或平台证书验签，回调密文按 APIv3 密钥解密；③ APIv2 按参数排序、拼接 APIv2 密钥后生成 sign；④ 跨商户发券时以实际调用商户的身份和凭据发起请求。
典型反例：把支付的 APIv3 Authorization 签名头直接用于代金券 APIv2 请求，或让不同调用商户共用一套证书配置。
见 4012365342-总述-APIv3如何签名和验签、4011985891-APIv2安全规范、4012534633-创建代金券批次、4012084207-代金券开发指引、4012153196-微信支付公钥产品介绍、4013038816-微信支付公钥常见问题、4015419357-如何从微信支付公钥切换成平台证书、4013053249-如何使用微信支付公钥验签、4013070756-开发必要参数说明 

 返回 SIGN_ERROR、验签失败或商户证书相关错误，接口调用和回调处理失败。 

 设置代金券回调前须开通营销事件推送

 说明：调用「设置代金券消息通知地址」接口时，若商户未开通营销事件推送能力，接口返回 HTTP 403 REQUEST_BLOCKED，提示「请开通回调通知产品权限」。
正确应该怎么做：① 登录微信支付商户平台，进入产品中心开通「营销事件推送」。
② 开通后调用 POST /v3/marketing/favor/callbacks 设置通知地址，notify_url 须为 HTTPS、可访问且不能携带参数。
③ 需要回调回传用户 openid 时，在请求中传入已绑定的 appid。
典型反例：未开通营销事件推送就直接调用设置回调接口，把 403 当作 URL 或签名问题处理。
见 4012084079-产品介绍、4012464198-设置代金券消息通知地址、4012285250-核销事件回调通知、4012072195-配置APIv3密钥、4015880636-常见问题 

 设置通知地址返回 REQUEST_BLOCKED“请开通回调通知产品权限”。 

 创建批次后须先激活并确认运营中状态

 说明：代金券批次激活后才能发放，仅运营中的批次可用于发券；暂停、已停止或未激活的批次不能按正常活动发放或核销。
正确应该怎么做：① 调用《创建代金券批次》创建批次后，调用《激活代金券批次》并设置生效时间；② 发布活动前调用《查询批次详情》，确认批次 status 为 running；若批次处于 paused 且仍需继续发放，按业务安排调用《重启代金券批次》；③ 对个人用户完成发券后，再开放支付侧优惠入口，避免活动尚未运营时用户支付却未享受优惠。
典型反例：制券成功即向用户投放领券入口，未确认批次是否已经激活或恢复运营。
见 4012460137-激活代金券批次、4012534633-创建代金券批次、4012084079-代金券产品介绍、4012084207-代金券开发指引、4012460564-查询批次详情、4012460411-重启代金券批次 

 未激活、已暂停或已结束的批次不能发券，接口返回活动未开始或已结束。

 后台创建批次须预留接口同步时间

 说明：代金券批次可通过商户平台或创建代金券批次接口创建；商户平台创建的批次同步到接口查询存在延迟，接口创建的批次无此延迟。
正确应该怎么做：① 需要创建后立即进入接口激活、发券或自动化管理流程时，优先调用“创建代金券批次”，保存接口返回的 stock_id 与 create_time；② 通过商户平台创建批次时，为接口同步预留等待时间，在激活和发券前通过“条件查询批次列表”或“查询批次详情”确认批次已可查询，不要因首次查询为空就重复建批次；③ 查询时正确传入创建批次的商户号与批次号，区分“尚未同步”和“查询参数错误”。
典型反例：定时任务在商户平台建券后立即按批次号查询，一次查不到就判定创建失败并重新制券，造成重复批次。
见 4012084079-产品介绍、4012460489-条件查询批次列表、4012460564-查询批次详情 

 后台创建后立即查询可能返回空结果，活动状态核对出现时间差。

 新增多笔立减活动须通过API发放

 说明：多笔立减已迁移至智能投放，自2026年9月15日起停止新增后台活动，仅支持通过API发放；不限商户、不限用户的全场立减还受全局活动数量限制，超过上限时不能激活。
正确应该怎么做：① 新增活动时通过API或智能投放配置，不再依赖商户平台旧入口；② 需要指定人群包时使用智能投放的投放范围配置；③ 创建全场立减前盘点现有活动量，优先复用，必要时改为限商户或限用户活动；④ 确有扩容需求时联系对接运营确认可行方案。
典型反例：继续按旧后台流程新增活动，并大量创建不限商户、不限用户的全场立减。
见 4012084207-代金券开发指引 

 原有后台新增路径不可用，存量活动与不限商户活动还受独立规则约束。

 核销商户号须在支付前加入批次可用名单

 说明：代金券批次创建时通过 available_merchants 指定可核销商户号，只有名单内商户的交易才能核销该券；核销商户号须在用户下单前配置完成，支付后才加入名单的交易不能享受本单优惠。
正确应该怎么做：① 创建代金券批次时，在 coupon_use_rule.available_merchants 中完整填写本批次需要核销的商户号；② 下单前调用查询代金券可用商户接口，核对订单支付商户号已在名单中；③ 支付商户号新增或变更后，先完成批次可用商户配置，再发起交易。
典型反例：按制券商户号直接推断券可在该商户核销，未把实际收款商户号加入批次可用商户名单即上线。
见 4012534633-创建代金券批次、4012463358-查询代金券可用商户、4012084207-代金券开发指引、4012285250-核销事件回调通知、4012084079-代金券产品介绍、4012460564-查询批次详情、4012534537-创建代金券批次（服务商）、4012463409-查询代金券可用商户（服务商）、4012460606-查询批次详情（服务商）、4020807296-代金券错误码 

 核销商户号不匹配时券无法核销，用户按原价支付；支付界面可能不展示扣减金额。

 已领取券有效期领取时固定，过期不得延期使用

 说明：发放指定批次代金券时，券沿用该批次的可用时间设置；使用“领取后N天有效”等相对有效期规则时，仍在批次可用时间内计算，批次结束时间先到时券会过期。
正确应该怎么做：① 在批次创建阶段同时配置 available_begin_time、available_end_time 和券的使用规则；② 需要相对有效期时，确保“领取后N天”覆盖预期使用日，同时核对不会超过批次结束时间；③ 激活批次后再发券，并以批次详情和发券结果中的券有效期为准；④ 对连续包月等后置使用场景，将最晚核销时间纳入批次结束时间设计。
典型反例：配置“领券后30天可用”后，默认券一定能在第30天使用，未考虑批次先于第30天结束。
见 4012534633-创建代金券批次、4012460137-激活代金券批次、4012463767-发放指定批次的代金券、4012486942-查询代金券详情 

 用户在支付时无可用券，无法抵扣；已过期券不能延期或恢复。

 服务商须将已授权子商户设为可核销商户

 说明：普通服务商自身不能作为普通商户直接发起交易，必须传入特约商户的 sub_mchid。免充值券由普通服务商创建时，available_merchants 只能填写已完成免充值授权的子商户；该子商户自己发起的交易不能使用这批免充值券，须由服务商代子商户发起交易。
正确应该怎么做：① 确认实际收款的 sub_mchid 已完成免充值代金券权限授权；② 创建批次时将已授权子商户号写入 available_merchants；③ 下单时由服务商传入对应的 sub_mchid 并发起交易；④ 发券时传入创建批次商户号、该用户当前的 appid 和与之对应的有效 openid；⑤ 上线前分别核对可核销商户名单与实际交易收款子商户。
典型反例：只填写服务商商户号，未填写实际收款的子商户；或让特约商户自行发起交易后，期望使用服务商创建的免充值券。
见 4012534537-创建代金券批次、4012463807-发放指定批次的代金券、4012087801-开发接入准备、4012534633-创建代金券批次、4012463358-查询代金券可用商户 

 批次无法覆盖目标子商户交易，或子商户自行发起的交易不能使用该免充值券。

 发券前须保证批次库存、预算和单日额度充足

 说明：批次受 max_coupons（发放总上限）、max_amount（总预算）及可选的 max_amount_by_day（单天预算）约束，max_amount 须等于券面额乘以发放总上限；任一额度耗尽时，用户无法继续领券或订单无法享受对应优惠。
正确应该怎么做：① 创建批次时按“券面额 × 计划发券数”计算并填写 max_amount，同时按活动规模设置 max_coupons，需要控制单日成本时设置 max_amount_by_day；② 活动开始前调用查批次详情接口，核对 status、distributed_coupons、max_coupons、max_amount、max_amount_by_day；③ 余额、总预算或单日限额不足时，先在商户平台补充预算或调整活动安排，再继续发券；④ 发券后记录接口返回码与 coupon_id，失败时只重试未成功的发放请求。
典型反例：只核算总预算，不检查单日发放预算；或在库存、预算接近耗尽时仍继续对外展示领券入口。
见 4012534633-创建代金券批次、4012460564-查询批次详情、4012463767-发放指定批次的代金券、4020807296-错误码、4012460137-激活代金券批次、4012460489-条件查询批次列表、4012084079-产品介绍、4012084207-代金券开发指引 

 可能返回 NOT_ENOUGH、270079534 或单日限额相关错误，用户无法领券或订单无法抵扣。

 补足库存后须主动重发未成功券

 说明：发放接口按“指定批次 + 指定 openid”单次发放一张券并返回 coupon_id；未发放成功的券不会在批次补库存、补预算后自动补发，也没有待发数量记录。补足批次资源后，商户须重新发起未成功的发放请求。
正确应该怎么做：① 服务端保存每个用户的计划发券数量、每次调用结果及成功返回的 coupon_id；② 出现库存或预算不足时，先补足对应批次资源；③ 按实际缺口逐次调用发放接口，并为每次新发放使用唯一的 out_request_no；④ 全部重发后调用查券接口核对用户实际持有的券，确认数量与状态。
典型反例：一次计划发五张券后只记录“已提交”，没有按每次返回的 coupon_id 判断实际成功数量，补库存后也未补发失败部分。
见 4012463767-发放指定批次的代金券、4012084207-开发指引、4012534690-根据商户号查用户的券 

 未成功发放的券不会自动补发，用户始终缺少对应优惠。

 发券前须校验用户未超过领券次数上限

 说明：批次通过 max_coupons_per_user 限制活动期间单个用户可领个数，达到上限后不能继续发放。
正确应该怎么做：① 创建批次时设置 max_coupons_per_user，取值不得大于发放总个数，范围为 1 至 60；② 发券前调用根据商户号查用户的券接口，核对该用户已领取数量；③ 已领取数量达到上限时不再重复调用发券接口。
典型反例：发券服务只判断批次是否在有效期内，未按 openid 查询用户已领数量就直接发券。
见 4012534633-创建代金券批次、4012534690-根据商户号查用户的券、4020807296-代金券错误码、4012463767-发放指定批次的代金券 

 返回“用户已达最大领券次数”或“立减发券超过用户领取上限”，券不发放。

 开启自然人限领后须按同一身份证合并计数

 说明：创建批次时将 natural_person_limit 设为 true 后，同一身份证下的多个微信号会合并视为同一用户，并共同受 max_coupons_per_user 限制；按单个 openid 统计的发券明细可能低于配置上限，但该自然人已领取其他微信号份额。
正确应该怎么做：① 按活动规则决定是否开启 natural_person_limit；② 开启后将 max_coupons_per_user 配置为 1 至 60 之间的目标值；③ 用户提示已达上限时，不要只用单个 openid 的发券记录判断是否未达上限；④ 通过后台领用记录核对已领取情况，并按照自然人维度设计活动提示。
典型反例：已开启自然人限领，却只以单个 openid 的累计张数推算用户是否还能领取。
见 4012534633-创建代金券批次、4012463767-发放指定批次的代金券、4020807296-错误码、4012460564-查询批次详情、4015894256-业务示例代码、4012084207-代金券开发指引 

 可能返回 RULE_LIMIT，提示“被自然人规则拦截”或“用户已达最大领券次数”。 

 用户实名或风控异常时不得循环重试发券

 说明：发放接口在用户无实名信息时返回 403 USER_ACCOUNT_ABNORMAL，错误信息为“用户未实名”；用户命中风控时也可能返回同类账号异常结果。该类用户不满足发券条件，不应按可重试的临时系统错误循环调用。
正确应该怎么做：① 对 USER_ACCOUNT_ABNORMAL 单独做业务处理，记录为不发券而非系统失败；② 对历史 openid 重新获取当前用户标识后再尝试一次；③ 仍返回账号异常或未实名时停止发券，并向用户展示当前账号无法参与活动；④ 不将同一失败请求无限重试。
典型反例：把 USER_ACCOUNT_ABNORMAL 归入普通网络失败，并使用同一个 openid 持续重试发券。
见 4012463767-发放指定批次的代金券、4020807296-错误码 

 发放接口返回 403 USER_ACCOUNT_ABNORMAL，提示“用户未实名”或“用户非法”。 

 面向指定用户发券须主动调用发券接口

 说明：创建并激活批次只完成制券和批次上线，代金券须由商户系统调用发放指定批次的代金券接口发放给指定用户。
正确应该怎么做：① 调用创建代金券批次接口取得 stock_id；② 调用激活代金券批次接口使批次可发放；③ 按业务场景调用 /v3/marketing/favor/users/{openid}/coupons，传入 stock_id、唯一 out_request_no、appid 和 stock_creator_mchid；④ 校验应答中的 coupon_id 并记录发券结果。
典型反例：认为创建或激活活动后微信会自动调用商户发券接口并向用户发券，实际未由商户主动发起发券请求。
见 4012084207-开发指引、4012463767-发放指定批次的代金券、4012084079-产品介绍 

 批次创建或激活不会自动向目标用户发券，用户领取不到券。

 常规立减活动激活后无需再调用发券接口

 说明：发放指定批次代金券接口的 stock_id 只支持代金券（全场券或单品券）批次，不支持立减与折扣；立减常规活动无需调用发券接口，特殊场景以运营配置为准。
正确应该怎么做：① 调用前先用 stock_type 确认批次类型。
② 对 DISCOUNT_CUT 批次不要调用发放接口，按平台活动配置完成发放。
③ 需要核对发放或核销结果时，使用批次详情、条件查询或下载批次核销明细。
典型反例：把平台创建的立减批次号传给发放代金券接口，期望通过 API 发券。
见 4012534633-创建代金券批次、4012460489-条件查询批次列表、4012534537-创建代金券批次（服务商）、4012460518-条件查询批次列表（服务商）、4012463767-发放指定批次的代金券、4012463585-下载批次核销明细、4012463807-发放指定批次的代金券（服务商）、4012463698-下载批次核销明细（服务商） 

 误加发券步骤会增加无效调用，不能替代立减活动激活与核销。

 调用发券接口的商户号须先绑定请求appid

 说明：发券时校验的是实际调用接口的请求头商户号与 appid 的绑定关系，不能仅依据报文体中的批次创建商户号或业务配置中的商户号判断。
正确应该怎么做：① 从 APIv3 请求头确认实际调用商户号；② 选择与该校验商户号已完成绑定的公众号、小程序或 App 的 appid；③ 核对 stock_id 确由请求中的 stock_creator_mchid 创建；④ 使用该 appid 下对应的 openid 发券。
典型反例：业务系统展示的是创券商户号，但签名请求头切换为另一商户号后仍沿用旧 appid。
见 4012463807-发放指定批次的代金券、商家商户号与AppID账号关联管理、4012463767-发放指定批次的代金券、4012084079-产品介绍、4020807296-错误码 

 返回 APPID_MCHID_NOT_MATCH、270079507 或“商户号与 AppID 不匹配”，发券失败。

 发券和查券须使用对应appid下的当前openid

 说明：代金券发放接口要求 openid 与请求中的 appid 存在对应关系，且 appid 与调用接口的商户号已绑定。用户变更实名信息后，历史 openid 可能不再对应当前实名状态，继续使用它会触发“用户未实名”。
正确应该怎么做：① 从当前用户本次访问所用的 AppID 和登录、授权会话中获取 openid；② 调用发放接口时同时传入与之对应的 appid、批次创建商户号和唯一 out_request_no；③ 命中 USER_ACCOUNT_ABNORMAL 或“用户未实名”时，停止使用已保存的历史 openid 循环重试；④ 重新获取当前 openid 后仅重试一次，仍报未实名则按不发券处理。
典型反例：长期复用用户更换实名认证前保存的 openid，并对同一历史标识反复发起发券请求。
见 4012463767-发放指定批次的代金券、4012084207-开发指引、4020807296-错误码、商家商户号与AppID账号关联管理、4012534690-根据商户号查用户的券、4012486942-查询代金券详情、4012068676-参数说明 

 返回 270079501“openid 与 appID 不匹配”、INVALID_REQUEST 或账号异常，券无法发放或查询。

 发券重试须复用原请求号并保证新请求唯一

 说明：发券接口支持幂等重入；out_request_no 由商户生成并须保持唯一，同一发券请求超时后应按原请求商户、原批次、原制券商户和原 out_request_no 重试。
正确应该怎么做：① 每笔发券业务生成唯一 out_request_no，并与业务单据建立持久化映射；② 网络超时或结果未知时，不更换 out_request_no，使用原请求参数和请求头商户号重试；③ 重试后仍需确认券结果，可按原 appid、openid、coupon_id 调用查询代金券详情，并据返回结果更新发券记录。
典型反例：首次请求超时后直接更换 out_request_no 再次发放，最终同一业务单据获得多张券。
见 4012463807-发放指定批次的代金券、4012492796-查询代金券详情、4012463767-发放指定批次的代金券、4012084207-开发指引 

 重复重试可能生成多张券或无法匹配原结果，造成重复发券和成本损失。

 常规发券不得传指定面额字段

 说明：coupon_value 和 coupon_minimum 用于指定面额发券场景，当前字段暂未开放；常规发券不应传入这两个字段，也不应把它们作为空值显式传递。
正确应该怎么做：① 使用批次创建时已固定的券面额和门槛；② 常规发券请求只传 stock_id、out_request_no、appid、stock_creator_mchid 等基础参数；③ 序列化请求体时不要把未使用的可选字段输出为 null。
典型反例：虽然业务不需要指定面额，却在发券请求中保留 "coupon_value": null 或 "coupon_minimum": null。
见 4012463767-发放指定批次的代金券 

 发券请求返回不支持指定面额，券无法发放。

 API发券默认不入卡包，展示须先申请插卡

 说明：API 发放的代金券可通过后台插卡配置展示在用户微信卡包，未申请该配置时券可能只能在支付时使用而不在卡包展示。
正确应该怎么做：① 按人工流程提交“后台插卡申请”，说明申请原因及完整 API 发券用户交互，并提供带明确领取按钮的交互示意图；② 提供 H5 链接或小程序名称、Appid、Path；③ 以表格附件提交制券商户号和批次号；④ 申请通过后继续使用原发券接口发放，无需新增插卡接口。
典型反例：仅在发券接口中调用成功，就默认用户能在卡包看到券，未完成发放场景与批次的插卡报备。
见 4012084079-代金券产品介绍、4012463767-发放指定批次的代金券、4012534690-根据商户号查用户的券 

 用户卡包看不到券；未开通插卡能力时不能自行假设已插入。

 卡包不展示时须以实际领券账号和券状态核验

 说明：代金券可进入用户卡包；卡包未展示时，应核对该券实际绑定的 openid、领券记录和券状态，不能仅根据手机号或另一微信账号的截图判断未发券。卡包不展示不必然影响券的核销。
正确应该怎么做：① 调用《根据商户号查用户的券》，按创建商户号、AppID 和当前用户 openid 查询券 ID 与状态；② 重新获取当前用户最新 openid，与发券记录比对；③ 发券记录与当前账号不一致时，向当前账号重新发券，不根据手机号推定实名归属。
典型反例：仅用手机号联系用户，不核对用户当前微信账号对应的 openid 和券状态，就认定发券失败并重复发券。
见 4012084207-代金券开发指引、4012463767-发放指定批次的代金券、4012084079-代金券产品介绍、4012534690-根据商户号查用户的券 

 可能向错误账号重复发券，同时真实领券账号仍无法被定位。

 查询批次须使用创建商户号和对应批次号

 说明：查询批次详情接口的 stock_creator_mchid 必须是创建该批次的商户号，不是发券商户号；跨商户发券时，也不能用发券方商户号替代。
正确应该怎么做：① 在创建批次成功后同时保存 stock_id 与 stock_creator_mchid；② 调用查批次详情、查可用商户、下载核销或退款明细时，使用对应的创建商户号；③ 跨商户发券场景中，将 stock_id 和 stock_creator_mchid 作为创建方提供的数据传递；④ 查询异常时先核对这两个字段是否属于同一批次。
典型反例：沿用默认发券商户号查询由另一制券商户号创建的批次。
见 4012460564-查询批次详情、4012463767-发放指定批次的代金券、4020807296-错误码、4012486942-查询代金券详情、4012460489-条件查询批次列表、4012460518-条件查询批次列表、4012534537-创建代金券批次、4012460606-查询批次详情、4012463409-查询代金券可用商户 

 返回“批次不存在”“查询批次为空”或 270079577，无法核对批次和核销数据。 

 查询批次须用stock_type区分代金券与立减

 说明：条件查询批次列表与查询批次详情均返回 stock_type，NORMAL 为代金券批次，DISCOUNT_CUT 为立减与折扣，OTHER 为其他；不能用批次名称或面额规则推断券种。
正确应该怎么做：① 调用条件查询批次列表或查询批次详情获取批次信息。
② 以 stock_type 分支处理：NORMAL 走代金券逻辑，DISCOUNT_CUT 走立减与折扣逻辑，OTHER 做兜底。
③ coupon_type 只用于区分满减券与减至券，不与批次类型混用。
典型反例：看到 stock_name 为“折扣立减券”就按代金券发放或暂停流程处理，忽略响应中的 stock_type=DISCOUNT_CUT。
见 4012460489-条件查询批次列表、4012460564-查询批次详情、4012460518-条件查询批次列表（服务商）、4012460606-查询批次详情（服务商） 

 无法区分券种，后续发券、核销或账单处理逻辑可能走错分支。

 折扣字段须按选填对象解析

 说明：查询批次详情或条件查询批次列表中的 stock_use_rule.fixed_discount_coupon 为选填对象，只有返回该对象时，其 discount_amount_max、discount_percent 才必填；普通折扣或折扣优惠批次可能不返回该字段。
正确应该怎么做：① 解析响应时先判断 fixed_discount_coupon 是否存在。
② 存在时再读取 discount_amount_max、discount_percent、transaction_minimum。
③ 不存在时按普通折扣或折扣优惠处理，不将其判为配置丢失或接口异常。
典型反例：把 fixed_discount_coupon 当作所有折扣批次必返回字段，字段缺失就判定批次配置不一致。
见 4012460564-查询批次详情、4012460489-条件查询批次列表 

 解析器把选填对象当成必填字段会导致查询失败或配置判断错误。

 查用户券须用创券或可核销商户号及用户openid

 说明：按用户查询可用券时，应按批次维度选择 creator_mchid 或 available_mchid；发券商户号无权限调用该查询接口，需改用创券商户号或可核销商户号。查询代金券详情（/v3/marketing/favor/users/{openid}/coupons/{coupon_id}）同样只支持批次创建商户号或批次发放商户号调用，且 appid 必须与 openid 对应、调用商户号须已绑定该 appid。
正确应该怎么做：① 明确查询维度：需要批次创建方可见的多种券状态时传 creator_mchid，需要核销方可见的可用券时传 available_mchid；② 使用该查询商户号已绑定的 appid；③ 传入该 appid 下用户的 openid，并在需要时用 stock_id 限定批次；④ 在商户数据库中保存发券时 coupon_id、out_request_no 与用户 openid 的对应关系，便于凭券号补齐查询参数。
典型反例：只保存券ID和用户外部账号，未保存该 openid 所属 appid，后续试图仅凭券ID反查完整领券信息。
见 4012492796-查询代金券详情、4012463807-发放指定批次的代金券、4012534690-根据商户号查用户的券、4012486942-查询代金券详情 

 返回 PARAM_ERROR、INVALID_REQUEST 或查不到券，无法确认用户持券状态。

 领券微信须与实际支付微信保持一致

 说明：发券接口向指定的 openid 发券，且该 openid 须与请求中的 appid 对应、该 appid 须与调用发券接口的商户号绑定。
正确应该怎么做：① 在当前业务 appid 下获取实际付款用户的 openid；② 调用发券接口时使用该 openid 和对应 appid；③ 用户发起支付时按同一用户查询其代金券，只允许本账号持有的券参与当前订单。
典型反例：用户使用微信号 A 领券，却切换到微信号 B 或另一套登录态完成支付。
见 4012084079-产品介绍、4012463767-发放指定批次的代金券、4012534690-根据商户号查用户的券 

 支付账户下没有该券，用户无法享受优惠，卡包也可能看不到券。

 订单原价须与本次支付金额保持一致

 说明：订单 detail.cost_price 用于记录一张小票的整单原价；当订单原价与本次支付金额不相等时，该订单不享受优惠。
正确应该怎么做：① 正常整单支付时不随意传入 cost_price；② 需要记录小票原价时，将 cost_price 设置为整张小票金额，并确保本次支付金额相同；③ 收银系统应避免把同一张小票拆成多笔支付后再分别使用代金券。
典型反例：先使用商家会员券改变本次支付金额，同时保留原小票金额作为 cost_price，系统按小票拆分支付处理。
见 4012791897-JSAPI小程序下单 

 订单被判定为小票拆分支付，不享受代金券优惠。

 收款商户无法通过接口阻止他方券抵扣

 说明：银行或微信官方发放的优惠券由发券方提供，收款商户在接口层无法控制其不被使用；代金券由用户在支付环节满足条件后自动核销，商户不能主动核销。
正确应该怎么做：① 在支付结果、订单查询和对账链路中按实际优惠金额与实付金额处理，不假设只会出现本商户创建的券；② 若业务要求限制本商户自行发放的券，应在创建批次和活动发券环节配置核销条件及发放范围；③ 收银台展示金额时区分订单原金额、券优惠金额和用户实付金额。
见 4012084079-产品介绍 

 其他商户或银行发放的券仍可能在支付时抵扣，收款核对金额低于预期。

 支付前须确认用户已领券且券处于可用期

 说明：查用户券接口返回券状态、领取时间、可用开始时间和可用结束时间；只有券已领取、状态为可用且当前时间处于可用期限内，才可能在支付环节自动核销。微信卡包是否展示不能替代券状态判断。
正确应该怎么做：① 用户进入提交订单页时，按批次创建商户号或可用商户号调用查用户券接口；② 仅保留 status=SENDED 且当前时间位于 available_begin_time 与 available_end_time 之间的券；③ 核对 create_time 早于本笔支付，确保不是支付完成后才领取的券；④ 若业务要求卡包展示，先确认运营侧券插入卡包能力已开通，再批量发券；⑤ 卡包未展示时继续以查券接口结果判断实际可用性。
典型反例：只依据卡包是否展示来向用户展示可用券，或在用户支付成功后才补发并尝试用于本单。
见 4012534690-根据商户号查用户的券、4012084079-产品介绍、4012486942-查询代金券详情、4012534633-创建代金券批次 

 用户按原价支付；订单支付后领券或支付前券不可用均不会核销。

 订单金额须达到券面配置的核销门槛

 说明：满减券的 transaction_minimum 是使用券的订单金额门槛，单位为分；订单金额未达到该值时不能核销。
正确应该怎么做：① 创建批次时通过 coupon_use_rule.fixed_normal_coupon.transaction_minimum 配置门槛；② 在商品详情页和收银台按同一门槛展示可用条件；③ 创建订单前读取批次或券详情中的门槛，与本次订单金额比较，仅在满足门槛时展示可抵扣预期。
典型反例：前端把券展示为“我的可用券”，下单时却没有按订单金额重新判断门槛。
见 4012534633-创建代金券批次、4012486942-查询代金券详情、4012084079-产品介绍 

 返回“订单不满足优惠活动规则”或“不满足门槛”，券无法核销。

 单品券须在下单时回传匹配的SKU明细

 说明：单品代金券按批次可用单品核销，下单时须在 detail.goods_detail 回传商品明细，商品编码须与批次可用单品匹配。
正确应该怎么做：① 创建或查询批次时确认可用单品清单；② 下单时在 goods_detail 传入 merchant_goods_id、quantity、unit_price 等必填字段；③ 核销后可在核销事件回调 consume_information.goods_detail 中核对实际回传的单品信息。
典型反例：只传订单总金额，不传 goods_detail，或回传的商品编码与批次可用单品不一致。
见 4012534633-创建代金券批次、4012791856-JSAPI下单、4012463767-发放指定批次的代金券、4012463442-查询代金券可用单品、4012084207-开发指引、4012285250-核销事件回调通知、4012791897-JSAPI小程序下单、4011935214-统一下单 

 报“订单中单品信息未匹配单品代金券批次单品信息”，券无法核销。

 指定卡BIN的券须匹配用户实际付款卡

 说明：批次可配置 coupon_use_rule.limit_card，只有使用指定银行卡 BIN 付款的交易才可核销该批次代金券；bin 单项长度为 6~9 位，条目数为 1~10 个，name 最多 4 个中文字符。
正确应该怎么做：① 创建批次时按目标发卡行核对并配置 limit_card.name 与 limit_card.bin；② 确保实际支付方式为银行卡且付款卡 BIN 属于批次配置范围；③ 修改批次或上线前核对 BIN 值与目标卡种一致。
典型反例：在同一活动中混用借记卡与信用卡客群，却没有分别核对两类卡的 BIN。
见 4012534633-创建代金券批次、4012460564-查询批次详情 

 付款卡未命中批次卡BIN时券不抵扣，可能提示卡BIN条件不匹配。

 单笔订单须遵守单品20张、全场8张券上限

 说明：单笔订单最多可使用20张单品券和8张全场券；订单优惠信息 promotion_detail 为数组，应按券逐项解析，而非只处理单个对象。
正确应该怎么做：① 优惠试算和前端展示按这两个上限筛选可叠加券；② 下单及支付结果处理中，将 promotion_detail 作为券数组遍历，按券 ID、活动批次和优惠金额逐项记账；③ 批次未配置可叠加时，按平台规则只使用符合条件的一张券，不自行实现跨规则叠加。
典型反例：代码把 promotion_detail 固定反序列化为单个对象，多张券同时使用时只保存第一张券或丢失后续券信息。
见 4015880636-代金券常见问题、4012534633-创建代金券批次、4012791859-商户订单号查询订单 

 超过张数的券无法在本单同时核销，用户实付与预期不符。

 裂券明细不得仅按券ID判重

 说明：银行代金券可能分裂为多张立减金并在同一笔订单中同时使用；分裂后的记录在核销明细中可能统一展示原始券ID，导致同一时间、同一支付单号、同一银行流水号下出现多条券ID相同的记录。
正确应该怎么做：① 读取核销明细时不把券ID单独作为记录唯一键；② 保留账单每一行，将券ID、支付单号、银行流水号作为分组维度，而不是去重键；③ 对同一订单的多条记录分别累计金额和张数；④ 为账单生成行号或使用文件行序号参与唯一性校验，确保多条合法记录可同时入库。
典型反例：系统以券ID或“支付单号 + 券ID”作为唯一约束，将同一订单的多张裂券记录判为重复数据。<，该展示规则。
见 4012463585-下载批次核销明细、4012463523-下载批次退款明细 

 多条合法核销记录被判为重复，账单无法通过唯一性校验，影响结算。

 核销回调须验签幂等并返回正确状态码

 说明：微信支付会发送以 WECHATPAY/SIGNTEST/ 开头的签名探测流量，商户应将其视为正常回调并执行验签；验签失败须返回 4XX/5XX 及失败应答报文，验签成功返回 200/204，微信不再重复发送该通知。
正确应该怎么做：① 收到 COUPON.USE 通知后，在 5 秒内完成验签。
② 验签失败返回 4XX/5XX 和 {"code":"FAIL","message":"失败"}；验签通过返回 200/204，无应答报文。
③ 应答后再异步处理更新核销状态等业务逻辑，避免处理耗时导致超时。
④ 不能仅依赖回调通知，还需结合查询接口或下载批次核销明细核对结果；下载核销明细的时间需晚于批次结束时间次日 10:00。
典型反例：验签异常时仍统一返回 HTTP 200，微信认为已成功接收，不再重发该通知，商户丢失核销结果。
见 4012084079-代金券产品介绍、4012464198-设置代金券消息通知地址、4012285250-核销事件回调通知、4012285807-核销事件回调通知（服务商）、4013053249-如何使用微信支付公钥验签、4013059017-如何使用微信支付公钥验签（服务商）、4012463585-下载批次核销明细、4012463698-下载批次核销明细（服务商）、4015880636-常见问题 

 验签失败或返回 200 后微信不再补发，核销结果可能丢失或重复处理。

 核销回调商户号须区分收款商户与入账方

 说明：核销事件回调的 consume_information.consume_mchid 是收款商户号；间联模式下当前返回银联、网联或入账方等清算侧商户号，不能直接当作实际核销的二级子商户号。
正确应该怎么做：① 回调处理中把 consume_mchid 按文档定义为收款或清算侧商户号，不直接映射零售商；② 需要实际核销二级商户号时，由创建活动方在活动结束次日 10:00 后调用“下载批次核销明细”；③ 使用批次号、订单号和回调 transaction_id 将核销明细与业务订单关联；④ 回调先验签并在 5 秒内应答，再异步处理账务。
典型反例：把回调中的单一商户号直接作为全国各分公司或零售商的核销主体写入账单。
见 4012285807-核销事件回调通知、4012463698-下载批次核销明细、4012285250-核销事件回调通知、4012463585-下载批次核销明细、4012463358-查询代金券可用商户 

 将回调商户号误当实际子商户号会关联错订单或核销记录。

 判断券是否结算须区分CASH与NOCASH

 说明：订单查询响应中的 promotion_detail.type 用于区分代金券结算资金类型：CASH 为预充值券，会随订单结算给收款商户；NOCASH 为免充值券，无对应资金结算给收款商户。promotion_detail.scope 表示全场券或单品券，出资方字段表示由谁出资，均不等同于结算类型。
正确应该怎么做：① 支付成功后调用订单查询接口；② 遍历 promotion_detail，按每张券的 type 判断 CASH 或 NOCASH；③ 分别汇总两类券面额，计算用户支付金额与商户应结金额；④ 存在额外分账规则时，在券结算结果基础上再按该规则处理。
典型反例：用 scope、wechatpay_contribute 或其他出资方字段代替 type 判断该笔券资金是否结算给商户。
见 4012791858-微信支付订单号查询订单、4012084079-产品介绍、4012534633-创建代金券批次、4012085146-支付成功回调通知、4011987538-查询订单、4012463585-下载批次核销明细、4012791866-申请交易账单、4012791859-商户订单号查询订单 

 预充值券与免充值券的商户实收和对账口径不同，误判会造成账务差额。

 APIv3 免充值券对账须遍历 promotion_detail 按 type=NOCASH 汇总免充值金额

 说明：APIv3 订单查询接口（如 /v3/pay/transactions/id/{transaction_id}）返回逐张券的 promotion_detail 数组，可通过筛选 type=NOCASH 的券面额汇总免充值优惠，以此计算商户应结订单金额。
正确应该怎么做：① 支付完成后调用 APIv3 订单查询接口；② 遍历 promotion_detail，筛选 type=NOCASH 并汇总 amount 得到本次免充值券金额，按“订单总金额减免充值券金额”核算商户应结金额；③ 将用户支付金额、订单金额、券金额和应结金额分别入账；④ 对可能包含同品牌或其他已授权商户券的场景，按 promotion_detail 券明细记录发放方和批次。
典型反例：只读取订单总金额，未遍历 promotion_detail 汇总 type=NOCASH 的免充值券明细，直接把订单总金额作为应结金额。
见 4012791858-微信支付订单号查询订单、4012084079-产品介绍、4012534633-创建代金券批次 

 免充值券面额被错误计入商户应结资金，形成订单应收与实际结算差额。

 核销与退款明细须使用对应账单接口和有效期

 说明：核销明细绑定具体 stock_id，查询日期应在该批次 available_begin_time 至 available_end_time 的活动期间内；接口需在活动结束后次日10点后才有数据。批次活动有效期由商户创建批次时设置，不包含券或立减金的使用有效期。
正确应该怎么做：① 先调用【查询批次详情】确认批次状态、开始时间和结束时间；② 用同一个批次的 stock_id 和活动期间内的账单日期请求【下载批次核销明细】；③ 活动结束后次日10点再发起下载，并按30秒有效期的下载地址及时取文件；④ 对齐日志中的 request-id 与实际请求参数，确认进入微信侧的就是目标批次和日期。
典型反例：页面展示 A 批次，却把 B 批次的日期区间提交给 A 批次；或把券本身的使用有效期当作批次活动有效期。
见 4012463585-下载批次核销明细、4012460564-查询批次详情、4015880636-常见问题、4020807296-错误码、4012463523-下载批次退款明细、4012084207-代金券开发指引 

 返回“账单文件不存在”“当天没有核销记录”或日期超限，无法完成对账。

 核销明细下载须控制调用频率

 说明：下载批次核销明细接口的频率限制为不区分来源 1000/min、单 IP 5/min；多批次或大促场景需要更高频率时可提前申请。
正确应该怎么做：① 按 stock_id 建立后台下载任务，同一 IP 串行或受限并发调用 GET /v3/marketing/favor/stocks/{stock_id}/use-flow；② 使用令牌桶控制单 IP 速率，遇到 429 FREQUENCY_LIMIT_EXCEED 或 FREQUENCY_LIMITED 时退避重试并加入随机抖动；③ 大促或批量项目上线前联系业务接口人申请频率上限，避免同一时刻集中拉取。
典型反例：几十个项目使用同一出口 IP 同时全量下载核销明细，只按项目数量拆分任务而未按接口频控排队。
见 4012463585-下载批次核销明细、4020807296-错误码 

 超过频率限制时下载失败，批量对账任务无法完成。

 退款退券规则须按优惠类型区分

 说明：全场通用券（银行立减金、政府消费券、微信立减金）发生部分退款时应退回优惠券；随机立减对应的优惠在订单全额退款时也不退回；除这两类外的其他优惠只有在订单全额退款时才全额退回。
正确应该怎么做：① 退款前先识别订单使用的优惠类型（全场通用券 / 随机立减 / 其他优惠）；② 全场通用券按实际使用金额核算并退回，部分退款也要核对退回结果；③ 随机立减不生成退券记录，对账时单独核对优惠承担金额；④ 其他优惠仅在全额退款时触发退回，部分退款不退回。
典型反例：把三类优惠统一按「全额退款才退券」或「退款即退券」处理。
 

 优惠券未按类型正确退回或错误退回，用户权益与商户退款流水、券库存及营销预算不一致，易再次引发客诉。

 部分退款后须按互斥规则处理分裂券

 说明：代金券发生部分退款后有分裂为新券的银行券场景；by 制券商户号 互斥的券在分裂后可与其他券叠加，by banktype 互斥的券在分裂后不可叠加。
正确应该怎么做：① 创建活动时明确当前批次使用的是制券商户号互斥还是 by banktype 互斥；② 支付试算按所选互斥类型判断可叠加券集合，不把两种互斥方式统一处理；③ 对涉及部分退款的银行券活动，依据创券方接口文档维护分裂后的券状态和叠加资格。
典型反例：系统只看“设置了互斥”一个布尔值，未记录互斥维度，导致部分退款分裂后的券被错误允许或错误拦截。
见 4015880636-代金券常见问题、4012534633-创建代金券批次 

 分裂券可能在后续订单叠加或无法叠加，营销成本与用户实付偏离配置。

 退款对账须按券ID和订单号关联原交易

 说明：只有指定了银行卡类型的批次会返回银行流水号；在此基础上，核销记录包含银行流水号，退款记录不包含。退款记录若需关联原交易，应使用券ID和订单号进行匹配。
正确应该怎么做：① 先按批次类型确认该批次是否会返回银行流水号；② 分别下载批次核销明细和退款明细；③ 以券ID和订单号作为核销与退款记录的关联字段；④ 将银行流水号仅作为核销记录的辅助字段，不要求退款记录必须提供。
典型反例：把银行流水号作为所有券交易的统一关联键，并假设退款明细也会返回该字段。
见 4012463585-下载批次核销明细、4012463523-下载批次退款明细 

 退款记录银行流水号为空时无法关联，退款金额与原核销记录对不上。

 含券订单退款须按券类型和退款比例处理

 说明：含代金券订单的全额退款按用户实际支付金额退还；部分退款按「申请退款金额 ×（用户实际支付金额 ÷ 订单总金额）」计算现金退款。券在有效期内发生订单退款时按退款规则回退，活动过期后券状态标记为过期。
正确应该怎么做：① 退款接口的 amount.refund 传订单维度的申请退款金额；② 计算用户现金退款时使用实付金额占比，不能直接按申请退款金额全额退还；③ 从 amount.payer_refund、amount.discount_refund 和 promotion_detail 获取实际现金退款与代金券退款信息；④ 展示券状态时同时判断退款时点与批次有效期。
典型反例：忽略代金券分摊，直接按部分退款申请金额向用户现金退款。
见 4013071001-订单退款产品介绍、4013071200-订单退款常见问题、4013071036-申请退款、4012463523-下载批次退款明细、4012084079-产品介绍、4012791862-退款申请、4012534690-根据商户号查用户的券、4012791903-退款申请、4012486942-查询代金券详情、4012534633-创建代金券批次、4012791863-查询单笔退款（通过商户退款单号）、4013061979-开通免充值代金券产品权限 

 券未按规则退回、退款金额计算错误或商户错误承诺退券，引发客诉和对账差额。