将电子发票插入微信用户卡包

更新时间：2025.09.26

商户自行开具电子发票后，可调用本接口将电子发票插入微信用户的卡包。

请求本接口前需要调用【上传电子发票文件】接口上传电子发票文件并获取文件ID。

> 注：该文件ID三天内有效。

若是非微信支付场景，需要先通过【获取用户授权链接】接口获取用户授权链接，并等待用户完成授权才能调用本接口；若是微信支付场景，则无需额外获取用户授权。

注意，本接口返回成功仅代表请求被受理。当插卡完成时，微信支付会根据商户配置的回调地址进行回调通知，商户也可以通过【查询电子发票】接口获取插卡结果及卡券信息。

> 注：一个微信支付订单只能插卡一次，最多对应五张电子发票，多次调用会做幂等性检查。

接口说明

支持商户：【普通商户】

请求方式：【POST】/v3/new-tax-control-fapiao/fapiao-applications/{fapiao_apply_id}/insert-cards

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数
折叠全部参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为application/json

Wechatpay-Serial 　必填　string

【微信支付公钥ID】或【微信支付平台证书序列号】请求参数中的敏感字段，需要使用微信支付公钥加密（推荐），请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引，也可以使用微信支付平台证书公钥加密，参考获取平台证书序列号、平台证书加密敏感信息指引

path 路径参数

fapiao_apply_id 　必填 string(32)

【发票申请单号】发票申请单号，唯一标识一次开票行为。请填写本次开票关联的微信支付订单号，且必须是属于相应商户的订单。

body 包体参数

scene 　必填 string

【插卡场景】插卡场景

可选取值：

WITH_WECHATPAY: 微信支付场景

WITHOUT_WECHATPAY: 非微信支付场景

buyer_information 　必填 object

【购买方信息】购买方信息，即发票抬头。商户可以从【获取用户授权信息】接口获取用户填写的抬头；微信支付场景下，若该笔订单在下单时指定在支付凭证上不展示开票入口，则商户需要自行获取用户抬头。

属性

type 　必填 string

【购买方类型】购买方类型

可选取值：

INDIVIDUAL: 个人

ORGANIZATION: 单位

name 　必填 string(256)

【名称】购买方名称

taxpayer_id 　选填 string(32)

【纳税人识别号】购买方纳税人识别号，购买方类型为ORGANIZATION时必须存在

address 　选填 string(128)

【地址】购买方地址

telephone 　选填 string(32)

【电话】购买方电话

bank_name 　选填 string(128)

【开户银行】购买方开户银行

bank_account 　选填 string(32)

【银行账号】购买方银行账号

phone 　选填 string

【手机号】用户手机号。注意：该字段为密文字段，需要使用微信支付公钥加密（推荐），请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引，也可以使用微信支付平台证书公钥加密，参考获取平台证书序列号、平台证书加密敏感信息指引

email 　选填 string

【邮箱地址】用户邮箱地址。注意：该字段为密文字段，需要使用微信支付公钥加密（推荐），请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引，也可以使用微信支付平台证书公钥加密，参考获取平台证书序列号、平台证书加密敏感信息指引

fapiao_card_information 　必填 array[FapiaoCardInfo]

【电子发票卡券信息列表】电子发票卡券信息列表，最多五条

属性

fapiao_media_id 　必填 string(128)

【电子发票文件ID】上传的电子发票文件对应的ID，用于CreateFapiaoCard接口

fapiao_number 　必填 string(8)

【发票号码】发票号码

fapiao_code 　必填 string(12)

【发票代码】发票代码

fapiao_time 　必填 string(32)

【开票时间】开票时间，遵循RFC3339标准格式

check_code 　必填 string(20)

【校验码】校验码

password 　必填 string(1024)

【密码】发票票面密码区内容

total_amount 　必填 integer

【总价税合计】总价税合计，所有发票行单行金额合计的累加，单位：分

tax_amount 　必填 integer

【总税额】总税额，所有发票行单行税额的累加，单位：分

amount 　必填 integer

【总金额】总金额，所有发票行单行金额的累加，单位：分

seller_information 　必填 object

【销售方信息】销售方信息

属性

name 　必填 string(256)

【名称】销售方名称

taxpayer_id 　必填 string(32)

【纳税人识别号】销售方纳税人识别号

address 　选填 string(128)

【地址】销售方地址。数电模式下无地址信息

telephone 　选填 string(32)

【电话】销售方电话

bank_name 　选填 string(128)

【开户银行】销售方开户银行

bank_account 　选填 string(32)

【银行账号】销售方银行账号

extra_information 　必填 object

【附加信息】附加信息

属性

payee 　选填 string(20)

【收款人】收款人

reviewer 　选填 string(20)

【复核人】复核人

drawer 　必填 string(20)

【开票人】开票人

items 　选填 array[object]

【发票行信息】发票行信息

属性

tax_code 　必填 string(32)

【税局侧规定的货物或应税劳务、服务税收分类编码】税局侧规定的货物或应税劳务、服务税收分类编码

goods_name 　必填 string(128)

【货物或应税劳务、服务名称】由商户自定义的货物或应税劳务、服务名称

specification 　选填 string(20)

【规格型号】规格型号

unit 　选填 string(20)

【单位】单位

quantity 　必填 integer

【数量】数量，单位为10^-8，100000000表示数量为1

unit_price 　必填 integer

【单价】单价，单位为10^-6分，100000000表示1元

amount 　必填 integer

【单行金额】单行金额，单位：分

tax_amount 　必填 integer

【单行税额】单行税额，单位：分

total_amount 　必填 integer

【单行金额合计】单行金额和税费的和，单位:分

tax_rate 　必填 integer

【税率】税率，单位为万分之一，如1300代表13%

tax_prefer_mark 　选填 string

【税收优惠政策标识】税收优惠政策标识

可选取值：

NO_FAVORABLE: 无优惠

OUTSIDE_VAT: 不征税

VAT_EXEMPT: 免税

NORMAL_ZERO_RATED: 普通零税率

EXPORT_ZERO_RATED: 出口零税率

discount 　必填 boolean

【是否折扣行】指定该发票行是否折扣行，折扣行一定是被折扣行的下一行

remark 　选填 string(200)

【备注信息】备注信息

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/new-tax-control-fapiao/fapiao-applications/4200000444201910177461284488/insert-cards \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1"  \
6  -H "Content-Type: application/json" \
7  -d '{
8    "scene" : "WITH_WECHATPAY",
9    "buyer_information" : {
10      "type" : "INDIVIDUAL",
11      "name" : "深圳市南山区测试企业",
12      "taxpayer_id" : "202003261233701778",
13      "address" : "深圳市南山区深南大道10000号",
14      "telephone" : "075512345678",
15      "bank_name" : "测试银行",
16      "bank_account" : "62001234567890",
17      "phone" : "18507550000",
18      "email" : "123110@qq.com"
19    },
20    "fapiao_card_information" : [
21      {
22        "fapiao_media_id" : "ASNFZ4mrze/+3LqYdlQyEA==",
23        "fapiao_number" : "12897794",
24        "fapiao_code" : "044001911211",
25        "fapiao_time" : "2020-07-01T12:00:00+08:00",
26        "check_code" : "69001808340631374774",
27        "password" : "006>299-375/326>2+7/*0-+<351059<80<4*/5>+<11631+*3030/5*37+/-243159658+013>3409*044>4-/1+/9->*>69501*6++1997--21",
28        "total_amount" : 382895,
29        "tax_amount" : 44050,
30        "amount" : 338845,
31        "seller_information" : {
32          "name" : "深圳市南山区测试公司",
33          "taxpayer_id" : "202003261233701778",
34          "address" : "深圳市南山区深南大道10000号",
35          "telephone" : "075512345678",
36          "bank_name" : "测试银行",
37          "bank_account" : "62001234567890"
38        },
39        "extra_information" : {
40          "payee" : "张三",
41          "reviewer" : "李四",
42          "drawer" : "王五"
43        },
44        "items" : [
45          {
46            "tax_code" : "3010101020203000000",
47            "goods_name" : "出租汽车客运服务",
48            "specification" : "A4",
49            "unit" : "次",
50            "quantity" : 100000000,
51            "unit_price" : 380442000000,
52            "amount" : 380442,
53            "tax_amount" : 49458,
54            "total_amount" : 429900,
55            "tax_rate" : 1300,
56            "tax_prefer_mark" : "NO_FAVORABLE",
57            "discount" : false
58          }
59        ],
60        "remark" : "备注"
61      }
62    ]
63  }'
64

应答参数

无应答包体

应答示例

202 Accepted

1'无应答包体'
2

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	请求参数符合参数格式，但不符合业务规则	请使用正确的参数重新调用
400	RESOURCE_ALREADY_EXISTS	发票申请单已存在	请稍后调用【查询电子发票】接口获取开票结果
401	SIGN_ERROR	签名错误或签名信息不完整	请检查签名参数和方法是否都符合签名算法要求
403	NO_AUTH	商户无权限	请检查是否已经开通电子发票产品相关功能权限，若是服务商模式，还需确认子商户是否接受了服务商的邀请
403	RULE_LIMIT	商户尚未配置电子发票卡券模版信息	请先调用【创建电子发票卡券模板】接口成功后再重新调用
403	RULE_LIMIT	商户提交的购买方信息与用户填写的发票抬头不一致	请检查参数中的购买方信息与【获取用户填写的抬头】接口返回的发票抬头信息是否一致
403	RULE_LIMIT	微信支付订单所属商户与当前商户不一致（仅微信支付场景）	请检查微信支付订单号是否属于商户，若是服务商模式则检查是否属于子商户
404	RESOURCE_NOT_EXISTS	用户尚未完成发票抬头填写	请在调用【获取用户填写的抬头】接口成功后再以相同发票申请单号重新调用
429	FREQUENCY_LIMITED	频率超限	请降低请求接口频率

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服

将电子发票插入微信用户卡包

接口说明

请求参数 折叠全部参数

应答参数

错误码

公共错误码

业务错误码

请求参数
折叠全部参数