---
url: "https://pay.weixin.qq.com/doc/v3/partner/4015792579.md"
title: "将电子发票插入微信用户卡包"
doc_id: 4015792579
---

>更新时间：2025.12.03

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

请求本接口前需要调用[【上传电子发票文件】](https://pay.weixin.qq.com/doc/v3/partner/4015792580.md)接口上传电子发票文件并获取文件ID。

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

若是非微信支付场景，需要先通过[【获取用户抬头填写链接】](https://pay.weixin.qq.com/doc/v3/partner/4015770776.md)接口获取用户授权链接，并等待用户完成授权才能调用本接口；若是微信支付场景，则无需额外获取用户授权。

注意，本接口返回成功仅代表请求被受理。当插卡完成时，微信支付会根据商户配置的回调地址进行回调通知，商户也可以通过[【查询电子发票】](https://pay.weixin.qq.com/doc/v3/partner/4015792567.md)接口获取插卡结果及卡券信息。

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




## 接口说明

支持商户：【普通服务商】

请求方式：【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 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/merchant/4012075113.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考 [签名认证](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `application/json` |
| Wechatpay-Serial | string | true | 【微信支付公钥ID】或【微信支付平台证书序列号】  请求参数中的敏感字段，需要使用微信支付公钥加密（推荐），请参考 [获取微信支付公钥ID说明](https://pay.weixin.qq.com/doc/v3/merchant/4013038816.md#Q:-%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E5%85%AC%E9%92%A5ID?) 以及 [微信支付公钥加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/merchant/4013053257.md)；也可以使用微信支付平台证书公钥加密，参考 [获取平台证书序列号](https://pay.weixin.qq.com/doc/v3/merchant/4013053294.md)、 [平台证书加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/merchant/4013053264.md) |
### Path 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| fapiao_apply_id | string(32) | true | 【发票申请单号】 发票申请单号，唯一标识一次开票行为。当开票场景为WITHOUT\_WECHATPAY时，为调用 [【获取用户抬头填写链接】](https://pay.weixin.qq.com/doc/v3/partner/4015770776.md) 接口时指定的发票申请单号；当开票场景为WITH\_WECHATPAY时，为与本次开票关联的微信支付订单号，且必须是属于相应商户的订单（服务商模式下该订单必须属于子商户；直连模式下该订单必须属于直连商户） |
### Body 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| sub_mchid | string(32) | true | 【子商户号】 微信支付分配的子商户号，具体请参考 [服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md) |
| scene | string | true | 【插卡场景】 插卡场景<br>可选取值<br><ul><li>`WITH_WECHATPAY`:  微信支付场景</li><li>`WITHOUT_WECHATPAY`:  非微信支付场景</li></ul> |
| buyer_information | object | true | 【购买方信息】 购买方信息，即发票抬头。商户可以从 [【获取用户填写抬头信息】](https://pay.weixin.qq.com/doc/v3/partner/4015784260.md) 接口获取用户填写的抬头；微信支付场景下，若该笔订单在下单时指定在支付凭证上不展示开票入口，则商户需要自行获取用户抬头。 |
| buyer_information.type | string | true | 【购买方类型】 购买方类型<br>可选取值<br><ul><li>`INDIVIDUAL`:  个人、其他</li><li>`ORGANIZATION`:  单位</li></ul> |
| buyer_information.name | string(256) | true | 【名称】 购买方名称 |
| buyer_information.taxpayer_id | string(32) | false | 【纳税人识别号】 购买方纳税人识别号，购买方类型为ORGANIZATION时必填 |
| buyer_information.address | string(128) | false | 【地址】 购买方地址 |
| buyer_information.telephone | string(32) | false | 【电话】 购买方电话 |
| buyer_information.bank_name | string(128) | false | 【开户银行名称】 购买方开户银行名称 |
| buyer_information.bank_account | string(32) | false | 【银行账号】 购买方银行账号 |
| buyer_information.phone | string | false | 【手机号】 用户手机号。注意：该字段为密文字段，作为请求字段需加密，使用微信支付公钥加密（推荐），参考[获取微信支付公钥ID说明](https://pay.weixin.qq.com/doc/v3/partner/4013038589.md#Q:-%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E5%85%AC%E9%92%A5ID?)以及[微信支付公钥加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/partner/4013059044.md)；也可以使用微信支付平台证书公钥加密，参考[获取平台证书序列号](https://pay.weixin.qq.com/doc/v3/partner/4013059181.md)、[平台证书加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/partner/4013059053.md)；作为响应字段需解密，参考[如何使用API证书解密敏感字段](https://pay.weixin.qq.com/doc/v3/partner/4013059060.md) |
| buyer_information.email | string | false | 【邮箱地址】 用户邮箱地址。注意：该字段为密文字段，作为请求字段需加密，使用微信支付公钥加密（推荐），参考[获取微信支付公钥ID说明](https://pay.weixin.qq.com/doc/v3/partner/4013038589.md#Q:-%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98%E5%85%AC%E9%92%A5ID?)以及[微信支付公钥加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/partner/4013059044.md)；也可以使用微信支付平台证书公钥加密，参考[获取平台证书序列号](https://pay.weixin.qq.com/doc/v3/partner/4013059181.md)、[平台证书加密敏感信息指引](https://pay.weixin.qq.com/doc/v3/partner/4013059053.md)；作为响应字段需解密，参考[如何使用API证书解密敏感字段](https://pay.weixin.qq.com/doc/v3/partner/4013059060.md) |
| buyer_information.amount | integer | false | 【订单金额】 微信支付订单金额，仅在微信支付场景下有效，单位：分 |
| buyer_information.out_trade_no | string(32) | false | 【商户订单号】 商户订单号，仅在微信支付场景下有效 |
| buyer_information.fapiao_bill_type | string | false | 【开具的发票类型】 用户选择提交开具发票的类型<br>可选取值<br><ul><li>`COMM_FAPIAO`:  增值税普通发票</li><li>`VAT_FAPIAO`:  增值税专用发票</li></ul> |
| buyer_information.user_apply_message | string(100) | false | 【留言信息】 用户申请开票时提交的留言信息 |
| fapiao_card_information | array[object] | true | 【电子发票卡券信息列表】 电子发票卡券信息列表，最多五条 |
| fapiao_card_information.fapiao_media_id | string(128) | true | 【电子发票文件ID】 上传的电子发票文件对应的ID，用于CreateFapiaoCard接口 |
| fapiao_card_information.fapiao_number | string(20) | true | 【发票号码】 发票号码 |
| fapiao_card_information.fapiao_code | string(12) | false | 【发票代码】 发票代码，非数电发票必填 |
| fapiao_card_information.fapiao_time | string(32) | true | 【开票时间】 开票时间，遵循 [RFC3339](https://tools.ietf.org/html/rfc3339) 标准格式：yyyy-MM-DDTHH:mm:ss+TIMEZONE |
| fapiao_card_information.check_code | string(20) | false | 【校验码】 校验码，非数电发票必填 |
| fapiao_card_information.password | string(1024) | false | 【密码】 发票票面密码区内容，非数电发票必填 |
| fapiao_card_information.total_amount | integer | true | 【总价税合计】 总价税合计，所有发票行单行金额合计的累加，单位：分 |
| fapiao_card_information.tax_amount | integer | true | 【总税额】 总税额，所有发票行单行税额的累加，单位：分 |
| fapiao_card_information.amount | integer | true | 【总金额】 总金额，所有发票行单行金额的累加，单位：分 |
| fapiao_card_information.seller_information | object | true | 【销售方信息】 销售方信息 |
| fapiao_card_information.seller_information.name | string(256) | true | 【名称】 销售方名称 |
| fapiao_card_information.seller_information.taxpayer_id | string(32) | true | 【纳税人识别号】 销售方纳税人识别号 |
| fapiao_card_information.seller_information.address | string(128) | false | 【地址】 销售方地址。数电模式下无地址信息 |
| fapiao_card_information.seller_information.telephone | string(32) | false | 【电话】 销售方电话 |
| fapiao_card_information.seller_information.bank_name | string(128) | false | 【开户银行】 销售方开户银行 |
| fapiao_card_information.seller_information.bank_account | string(32) | false | 【银行账号】 销售方银行账号 |
| fapiao_card_information.extra_information | object | true | 【附加信息】 附加信息 |
| fapiao_card_information.extra_information.drawer | string(20) | true | 【开票人】 开票人 |
| fapiao_card_information.items | array[object] | false | 【发票行信息】 发票行信息 |
| fapiao_card_information.items.tax_code | string(32) | true | 【税局侧规定的货物或应税劳务、服务税收分类编码】 税局侧规定的货物或应税劳务、服务税收分类编码 |
| fapiao_card_information.items.goods_name | string(128) | true | 【货物或应税劳务、服务名称】 由商户自定义的货物或应税劳务、服务名称 |
| fapiao_card_information.items.specification | string(20) | false | 【规格型号】 规格型号，展示在发票中间的规格型号列 |
| fapiao_card_information.items.unit | string(32) | false | 【单位】 单位，展示在发票中间的单位列 |
| fapiao_card_information.items.quantity | integer | true | 【数量】 数量，展示在发票中间的数量列，单位为10-8，100000000表示数量为1 |
| fapiao_card_information.items.unit_price | integer | true | 【单价】 单价，单位为10-6分，100000000表示1元 |
| fapiao_card_information.items.amount | integer | true | 【单行金额】 单行金额，单位：分 |
| fapiao_card_information.items.tax_amount | integer | true | 【单行税额】 单行税额，单位：分 |
| fapiao_card_information.items.total_amount | integer | true | 【单行金额合计】 单行金额和税费的和，折扣行的金额为负数，非折扣行的金额为正数，单位:分 |
| fapiao_card_information.items.tax_rate | integer | true | 【税率】 税率，单位为万分之一，如1300代表13% |
| fapiao_card_information.items.tax_prefer_mark | string | false | 【税收优惠政策标识】 税收优惠政策标识<br>可选取值<br><ul><li>`NO_FAVORABLE`:  无优惠</li><li>`OUTSIDE_VAT`:  不征税</li><li>`VAT_EXEMPT`:  免税</li><li>`NORMAL_ZERO_RATED`:  普通零税率</li><li>`EXPORT_ZERO_RATED`:  出口零税率</li></ul> |
| fapiao_card_information.items.discount | boolean | true | 【是否折扣行】 指定该发票行是否折扣行，折扣行必须是被折扣行的下一行 |
| fapiao_card_information.remark | string(200) | false | 【备注信息】 备注信息 |
## 应答参数

无应答包体
## 错误码

以下是本接口返回的错误码列表。详细错误码规则，请参考[微信支付接口规则-错误码和错误提示](https://pay.weixin.qq.com/doc/v3/partner/4012081726.md#%E9%94%99%E8%AF%AF%E7%A0%81%E5%92%8C%E9%94%99%E8%AF%AF%E6%8F%90%E7%A4%BA)

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/merchant/4012072670.md) |
| 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 | 频率超限 | 请降低请求接口频率 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792579-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792579-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792579-go.md)


应答示例

> 202 Accepted

```
'无应答包体'

```
