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

更新时间:2025.09.03

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

请求本接口前需要调用【上传电子发票文件】接口上传电子发票文件并获取文件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)

【发票申请单号】 发票申请单号,唯一标识一次开票行为。当开票场景为WITHOUT_WECHATPAY时,为调用【获取用户抬头填写链接】接口时指定的发票申请单号;当开票场景为WITH_WECHATPAY时,为与本次开票关联的微信支付订单号,且必须是属于相应商户的订单(服务商模式下该订单必须属于子商户;直连模式下该订单必须属于直连商户)


body  包体参数

 sub_mchid  必填   string(32)

【子商户号】 微信支付分配的子商户号,具体请参考服务商模式开发必要参数说明


 scene  必填   string

【插卡场景】 插卡场景

可选取值

  • WITH_WECHATPAY:  微信支付场景

  • WITHOUT_WECHATPAY:  非微信支付场景


 buyer_information  必填   object

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

属性

 fapiao_card_information  必填   array[object]

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

属性

请求示例

curl
Java
Go

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    "sub_mchid" : "1900000109",
9    "scene" : "WITH_WECHATPAY",
10    "buyer_information" : {
11      "type" : "INDIVIDUAL",
12      "name" : "深圳市南山区测试企业",
13      "taxpayer_id" : "202003261233701778",
14      "address" : "深圳市南山区深南大道10000号",
15      "telephone" : "075512345678",
16      "bank_name" : "测试银行",
17      "bank_account" : "62001234567890",
18      "phone" : "mI7HGEJ4Q2B91IGjHrl7FNN9QuFPDfzeXoaJM4B8ZghZPzXK+vNotEZu/Gthm87Szv0MK2AoC0/3ZMDgltMtdoY6O0qZ4F1iXiwCuqkkBe+9M4ggvdzpPGM+fyed2QU1seUGbii5RVVVB9s+zLEQ8nv74vsgl77MZx14nd5obtCcfAvPfDJob3oG7FqlThmYKJqjiOwBvvQse7p9R8onj/POzSrbM8re8ZYGp4LcehXopTLdk2ZVWRv8bnJgKZWArAcqMdahq4jY2UVYeY4vpMmq4xuRTYk6xNXvowBBKK2SX8SqM+jm1USyoBIazLu4oaNFNdBO3fip1a1rFW0vRw==",
19      "email" : "NzJy3r0Z2u2Vs5l+WSH0A3CZ1oGlCZ66aa2wUlMXNmACbd4wU8LqqYCuTG4cYWxrVUSmviV59/Uy9vLdIwuHZVrMalYAZGtb8inWGhDj3wUqQnPkmBKBVGIWG5Y6XJmMvpXW6rIKsdzxs8NwWj30cRNfjanLxiWc0aIgl8Knwo0JcxlcYLo38T9ntsrRkQZMQEWHaMYnzjp7ysLbp6yW83OZb/NwEufERBdPnIbDbVE7DUd5MGhvO+tlr2YC1b4VCsrDmjryuTD5nvYYCGHyfXW2CM23hZdBm9tPc+mU18Z9d4XkasnfsecGWd2ISkpPmnk3DtapnD64Nw8JyLtkgw==",
20      "amount" : 1000,
21      "out_trade_no" : "order_20200701_123456",
22      "fapiao_bill_type" : "COMM_FAPIAO",
23      "user_apply_message" : "用户留言"
24    },
25    "fapiao_card_information" : [
26      {
27        "fapiao_media_id" : "ASNFZ4mrze/+3LqYdlQyEA==",
28        "fapiao_number" : "12897794",
29        "fapiao_code" : "044001911211",
30        "fapiao_time" : "2020-07-01T12:00:00+08:00",
31        "check_code" : "69001808340631374774",
32        "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",
33        "total_amount" : 382895,
34        "tax_amount" : 44050,
35        "amount" : 338845,
36        "seller_information" : {
37          "name" : "深圳市南山区测试公司",
38          "taxpayer_id" : "202003261233701778",
39          "address" : "深圳市南山区深南大道10000号",
40          "telephone" : "075512345678",
41          "bank_name" : "测试银行",
42          "bank_account" : "62001234567890"
43        },
44        "extra_information" : {
45          "payee" : "张三",
46          "reviewer" : "李四",
47          "drawer" : "王五"
48        },
49        "items" : [
50          {
51            "tax_code" : "3010101020203000000",
52            "goods_name" : "出租汽车客运服务",
53            "specification" : "A4",
54            "unit" : "次",
55            "quantity" : 100000000,
56            "unit_price" : 380442000000,
57            "amount" : 380442,
58            "tax_amount" : 49458,
59            "total_amount" : 429900,
60            "tax_rate" : 1300,
61            "tax_prefer_mark" : "NO_FAVORABLE",
62            "discount" : false
63          }
64        ],
65        "remark" : "备注"
66      }
67    ]
68  }'
69

应答参数

无应答包体

应答示例

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

发票申请单已存在

请稍后调用【查询电子发票】接口获取开票结果

403

NO_AUTH

商户无权限

请检查是否已经开通电子发票产品相关功能权限,并检查子商户是否接受了服务商的邀请

403

RULE_LIMIT

商户尚未配置电子发票卡券模板信息

请先调用【创建电子发票卡券模板】接口成功后再重新调用

403

RULE_LIMIT

商户提交的购买方信息与用户填写的发票抬头不一致

请检查参数中的购买方信息与【获取用户填写抬头信息】接口返回的发票抬头信息是否一致

403

RULE_LIMIT

微信支付订单所属商户与当前商户不一致(仅微信支付场景)

请检查微信支付订单号是否属于商户

404

RESOURCE_NOT_EXISTS

用户尚未完成发票抬头填写

请在调用【获取用户填写抬头信息】接口成功后再以相同发票申请单号重新调用

429

FREQUENCY_LIMITED

频率超限

请降低请求接口频率

 

 

反馈
咨询
目录
置顶