1. Obtaining Authorization Page Ticket

2 Obtaining Authorization Page URL

3. Mini Program Opens Authorization Page

4. iOS App Opens Authorization Page

5. Andoird App Opens Authorization Page

6. Receiving Authorization Completion Event Push

7. Querying Authorization Completion Status

8. Rejecting Invoicing

9. Setting Authorization Page Field Information

10. Querying Authorization Page Field Information

11. Linking Merchant ID and the Invoicing Platform

12. Querying the Linking Status of Merchant ID and the Invoicing Platform

13. Enabling Post-Payment Invoicing for a Specific Transaction

14. Unified Invoicing API - Issue Blue Invoice

15. Unified Invoicing API - Invoice Offset

16. Unified Invoicing API - Query Issued Invoices

17. Setting Merchant's Contact Information

18. Querying Merchant's Contact Information

19. Unified Invoicing API - Async Notifications of Invoicing Result

99. Error Codes


#1. Obtaining Authorization Page Ticket

API description

Before calling the authorization page, the merchant must obtain an authorization page ticket, which is valid for 7200s. This ticket is used as a parameter when calling the "obtaining authorization page" API to enhance security.

Request method

Request URL: https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card

Request method: GET

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code. For error description, see Error Codes.
errmsg String Yes Error message. For error description, see Error Codes.
ticket String Yes Temporary ticket, which is used as a parameter when obtaining the authorization page URL.
expires_in Int Yes Validity period of the ticket. Generally, it is 7200 sec.

Sample code

Response:
{
    "errcode": 0,
    "errmsg":"ok",
    "ticket":"m7RQzjA_ljjEkt-JCoklRM5zrzYr-6PI09QydZmNXXz-opTqMv53aFj1ykRt_AOtvqidqZZsLhCDgwGC6nBDiA",
    "expires_in": 7200
}

2. Obtaining Authorization Page URL

API description

This API is called by merchants. A merchant obtains the authorization page URL by providing the order number, invoicing platform ID, and other parameters via this API. On the authorization page displayed to users in WeChat, after a user taps the "Get Invoice" or "Apply for Invoice" button, the order number is linked to this user's authorization. The invoicing platform can initiate a request to add the invoice card into the user's Cards & Offers based on this order no. At this time, WeChat will verify the authorization to determine whether or not to add the card.

There are three authorization page styles. Merchants can provide different type values when calling the API to set the style. The different styles are shown below:

授权页样式

The different styles provide the following functions:

type=0 (Apply for invoice): This type is used when the merchant has already obtained the user's title from another channel. It pulls up the authorization page to initiate an invoicing request. After the invoice is issued, it is saved in the user's Cards & Offers.

type=1 (Enter invoice title and apply for invoice): When this type is called, the page will display the user's commonly used titles stored in WeChat. This makes it easy for users to specify their title information when the merchant does not already have it. Please note that only type=1 can be called for post-payment invoicing.

type=2 (Get invoice): After the merchant has issued an invoice, this type is used to pull up the authorization page so that the user can save the invoice in Cards & Offers.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/getauthurl?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
s_pappid String Yes ID of the invoicing platform in WeChat. This is provided to the merchant by the invoicing platform.
order_id String Yes Order ID, which is a unique identifier of an invoice request of the merchant.
money Int Yes Order amount (in cents).
timestamp Int Yes Timestamp
source String Yes Channel from which the invoice is issued. app: app; web: WeChat HTML5 page; wxa: Mini Program; wap: normal webpage.
redirect_url String No The page to be redirected to after successful authorization. This field is only required when the source is an HTML5 page. It guides the user to the next process. For app invoicing, the third-party app pulls up the WeChat authorization page and the user is automatically redirected back to the third-party app after authorization. Therefore, this parameter is not required.
ticket String Yes Obtained from the previous step.
type Int Yes Authorization type, 0: authorization for invoicing, 1: authorization for entering fields and invoicing, 2: authorization for getting invoice.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

If the error code is 0, the following information is returned:

Parameter Type Required Description
auth_url String Yes The authorization URL
appid String No This is only used when source is wxa.

Sample code

Request:
{
    "s_pappid": "wxabcd",
    "order_id": "1234",
    "money": 11,
    "timestamp": 1474875876,
    "source": "web",
    "redirect_url": "https://mp.weixin.qq.com",
    "ticket": "tttt",
    "type": 1
}
Response:
{
    "errcode": 0,
    "errmsg": "ok",
    "auth_url": "http://auth_url"
}
For Mini Programs, the response is:
{
    "errcode": 0,
    "errmsg": "ok",
    "auth_url": "auth_url"
    "appid": "appid"
}

3. Mini Program Opens Authorization Page

API description

To open the authorization page, a Mini Program must first get the authorization page URL by calling the Obtaining Authorization Page URL API using the Mini Program account.

Request method

Call the wx.navigateToMiniProgram method in the Mini Program.

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
appid string Yes The appid returned by the "Obtaining Authorization Page URL" API.
path string Yes The auth_url returned by the "Obtaining Authorization Page URL" API.

Response

The user's authorization result is notified to the merchant via the Mini Program callback.

Sample code

wx.navigateToMiniProgram({
    appId: '{appid}',
    path: '{auth_url}',
    success(res) {
        console.log('navigateToMiniProgram success:', res)
    },
    fail(error){
        console.log('navigateToMiniProgram fail:', error)
    },
    complete(res){
        console.log('navigateToMiniProgram complete:', res)
    }
})

4. iOS App Opens Authorization Page

API description

To open the authorization page, an app on iOS devices must first get the authorization page URL by calling the Obtaining Authorization Page URL API using the open account.

Request method

Call the sendReq API.

Request parameters

Parameter Type Required Description
urlString string Yes The auth_url returned by the "Obtaining Authorization Page URL" API.

Response

The merchant's app receives the response of the WeChat invoice authorization API and must implement the onResp method. The fields in the returned result are described below:

Parameter Type Required Description
errCode int Yes Error code
wxOrderId string Yes Authorization order no.

Sample code

Send request
WXInvoiceAuthInsertReq *req = [[WXInvoiceAuthInsertReq alloc] init];
req.urlString = self.authUrl;
[WXApi sendReq:req];

Receive response
- (void) onResp:(BaseResp *)resp
{
    if ([resp isKindOfClass:[WXInvoiceAuthInsertResp class]]) {
        WXInvoiceAuthInsertResp *wxResp = (WXInvoiceAuthInsertResp *) resp;
        NSString *strTitle = @"WeChat redirection";
        NSString *strMsg = [NSString stringWithFormat:@"errcode: %d orderid:%@", wxResp.errCode, wxResp.wxOrderId];
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:strTitle message:strMsg delegate:self cancelButtonTitle:@"Cancel " otherButtonTitles:@"OK", nil];
        [alert show];
    }
}

Note

After the user is redirected from the merchant's app to the WeChat app and authorizes invoicing, the user may not be able to return to the merchant's app (for example, if the user ends the WeChat process). Therefore, the merchant cannot rely on a response from the WeChat app to determine if the user has granted authorization. The WeChat e-invoicing platform provides an Official Account callback mechanism. When the user authorizes invoicing, the WeChat e-invoicing platform notifies merchants using the callback. In addition, the WeChat e-invoicing platform provides an authorization status query API.

How to use:

  1. The merchant obtains the authorization URL by calling the API using the open account.

  2. The user goes to the invoicing page from the merchant app and then is redirected to the WeChat app through the WeChat SDK to grant the authorization for adding the invoice card.

  3. The merchant's Official Account receives a callback indicating the user's authorization status.

  4. When the merchant's app receives the redirection of invoice card adding authorization from the WeChat app, the merchant queries the user's authorization status by calling the API using the open account.

  5. When the user enters the invoicing page on the merchant's app again, the merchant queries the user's authorization status by calling the API using the open account.

  6. If the user has granted authorization, the invoicing platform is notified to issue an invoice.

5. Andoird App Opens Authorization Page

API description

To open the authorization page, an app on android devices must first get the authorization page URL by calling the Obtaining Authorization Page URL API.

Request method

Call the sendReq API.

Request parameters

Parameter Type Required Description
urlString string Yes The auth_url returned by the "Obtaining Authorization Page URL" API.

Response

The merchant's app receives the response of the WeChat invoice authorization API and must implement the onResp method. The fields in the returned result are described below:

Parameter Type Required Description
errCode int Yes Error code
wxOrderId string Yes Authorization order no.

Sample code

Send request
WXInvoiceAuthInsert.Req oReq = new WXInvoiceAuthInsert.Req();
oReq.url = sJumpUrl;
api.sendReq(oReq);

Receive response
public class WXEntryActivity extends Activity implements IWXAPIEventHandler {
    private static final String APP_ID = "wxxxxxxxxxxx";
    private IWXAPI api;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        api = WXAPIFactory.createWXAPI(this, APP_ID, true);
        api.handleIntent(getIntent(), this);
    }

    @Override
    public void onReq(BaseReq baseReq) {
    }

    @Override
    public void onResp(BaseResp baseResp) {
        Toast.makeText(getApplicationContext(), "onResp", Toast.LENGTH_LONG).show();
        if (baseResp.getClass().equals(WXInvoiceAuthInsert.Resp.class)) {
            WXInvoiceAuthInsert.Resp oResp = (WXInvoiceAuthInsert.Resp) baseResp;
            String sLog = "errcode:" + oResp.errCode + " wxorderid:" + oResp.wxOrderId;
            System.out.print(sLog);
        }
    }
}

Note

After the user is redirected from the merchant's app to the WeChat app and authorizes invoicing, the user may not be able to return to the merchant's app (for example, if the user ends the WeChat process). Therefore, the merchant cannot rely on a response from the WeChat app to determine if the user has granted authorization. The WeChat e-invoicing platform provides an Official Account callback mechanism. When the user authorizes invoicing, the WeChat e-invoicing platform notifies merchants using the callback. In addition, the WeChat e-invoicing platform provides an authorization status query API.

How to use:

  1. The merchant obtains the authorization URL by calling the API using the open account.

  2. The user goes to the invoicing page from the merchant app and then is redirected to the WeChat app through the WeChat SDK to grant the authorization for adding the invoice card.

  3. The merchant's Official Account receives a callback indicating the user's authorization status.

  4. When the merchant's app receives the redirection of invoice card adding authorization from the WeChat app, the merchant queries the user's authorization status by calling the API using the open account.

  5. When the user enters the invoicing page on the merchant's app again, the merchant queries the user's authorization status by calling the API using the open account.

  6. If the user has granted authorization, the invoicing platform is notified to issue an invoice.

6. Receiving Authorization Completion Event Push

API description

When a user grants the authorization for saving invoices in their WeChat account, the merchant can receive the authorization completed status push. After receiving the push, the merchant can send the order_id and invoice information to the invoicing platform. Then the invoicing platform can add the e-invoice in the user's Cards & Offers after issuing the invoice.

This event is sent to the URL entered by the developer (log in to the Official Accounts Platform and go to Developer Center Settings; an Official Account account shall be used for an open account, as shown in the figure below).

If the WeChat server does not receive the response within five seconds, the connection is broken and the request is initiated again. A maximum of three retries are made. We recommend that you use FromUserName + CreateTime to de-duplicate requests. If the merchant's server cannot ensure the request is processed within five seconds, it can return an empty string. When receiving the string, the WeChat server will not take any action or make a retry.

Response

The returned result is in XML format and contains the following fields:

Parameter Type Required Description
ToUserName String Yes The Official Account ID
FromUserName String Yes User's openid
CreateTime Int Yes Creation time of the event
MsgType String Yes Always set to "event".
Event String Yes Always set to "user_authorize_invoice".
SuccOrderId String No The order no. for which authorization is successful. Either this or FailOrderId must be displayed.
FailOrderId String No The order no. for which authorization failed. Either this or SuccOrderId must be displayed.
AuthorizeAppId String Yes The AppId that obtains the authorization page URL.
Source String Yes Channel from which the invoice is issued. web: Official Account; app: app; wxa: Mini Program; wap: HTML5 page.

Sample code

<?xml version="1.0" encoding="utf-8"?>
<xml>
   <ToUserName><![CDATA[gh_fc0a06a20993]]></ToUserName>
   <FromUserName><![CDATA[oZI8Fj040-be6rlDohc6gkoPOQTQ]]></FromUserName>
   <CreateTime>1475134700</CreateTime>
   <MsgType><![CDATA[event]]></MsgType>
   <Event><![CDATA[user_authorize_invoice]]></Event>
   <SuccOrderId><![CDATA[1202933957956]]></SuccOrderId>
   <FailOrderId><![CDATA[]]></FailOrderId> < AuthorizeAppId ><![CDATA[]]></ AuthorizeAppId > <Source><![CDATA[]]></Source>
</xml>

7. Querying Authorization Completion Status

API description

This API is called in two scenarios:

  1. If the merchant has displayed the authorization page to the user, but does not receive an authorization completion status push after a long period of time, the merchant can use this API to actively check if the user has completed authorization. This API can be used when the merchant fails to receive the authorization completion status event due to problems such as network issue.

  2. If the merchant displays a type=1 authorization page to a user and, after receiving the authorization completion event push, the merchant can call this API to obtain user invoice information.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/getauthdata?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
order_id string Yes Invoice order_id
s_pappid String Yes ID of the invoicing platform in WeChat. This is provided to the merchant by the invoicing platform.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
invoice_status String No Order authorization status, which is displayed when errcode is 0.
auth_time Int No Authorization time expressed as a 10-digit timestamp (UTC+8), which is displayed when errcode is 0.
user_auth_info Object No Structured field for user authorization information, which is displayed only when the authorization page type is 1.

Sample code

Request:
{
    "s_pappid": "{s_pappid}",
    "order_id": "{order_id}"
}
Response:
If the user enters an individual invoice title:
{
    "errcode": 0,
    "errmsg": "ok",
    "invoice_status": "auth success",
    "auth_time": 1480342498,
    "user_auth_info": {
        "user_field": {
            "title": "Dhxhhx ",
            "phone": "5554545",
            "email": "dhxhxhhx@qq.cind",
            "custom_field": [
                {
                    "key": "field1",
                    "value": "ABCD"
                }
            ]
        }
    }
}
If the user enters a company invoice title:
{
    "errcode": 0,
    "errmsg": "ok",
    "invoice_status": "auth success",
    "auth_time": 1480342897,
    "user_auth_info": {
        "biz_field": {
            "title": "xxCompany",
            "tax_no": "6464646766",
            "addr": "xxBuilding",
            "phone": "1557548768",
            "bank_type": "xxBank",
            "bank_no": "545454646",
            "custom_field": [
                {
                    "key": "field2",
                    "value": "EFGH"
                }
            ]
        }
    }
}

8. Reject Invoicing

API description

After the user completes authorization, if the merchant finds that the information provided by the user is incorrect or a refund occurs, the merchant can call this API to reject invoicing and notify the user. After invoicing is rejected, the user cannot invoice this order again. Orders for which invoicing is rejected cannot be reused. If a new invoice is needed, the merchant must use a new order_id and obtain the authorization URL to get the authorization from the user again. After the merchant calls the API, the user receives the following notification:

拒绝开票模板消息

Request method

Request URL: https://api.weixin.qq.com/card/invoice/rejectinsert?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
s_pappid string Yes ID of the invoicing platform in WeChat. This is provided to the merchant by the invoicing platform.
order_id string Yes Order ID.
reason string Yes Rejection reason provided by the merchant, such as duplicate invoice, invalid title, or that a refund has occurred.
url string No The redirect link that takes users to the next step, such as apply again for an invoice, enter the invoice title again, or display order details.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code
errmsg string Yes Error message

Sample code

Request:
{
    "s_pappid": "d3JCEfhGLW+q0iGP+o9",
    "order_id": "111229",
    "reason": "1234",
    url": "http://xxx.com"
}
Response:
{
    "errcode": 0,
    "errmsg": "ok"
}

9. Setting Authorization Page Field Information

API description

When users use a type=1 authorization page, merchants can use this API to set the information users are required to enter on the authorization page. When using type=0 or type=2 authorization pages, merchants do not need to call this API. This API only needs to be called once to set the required fields and only needs to be called again when changing the required fields.

Please note that the fields of which the status are displayed are required fields. If a user does not enter this field, they cannot proceed to the next step.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=set_auth_field&access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
auth_field Object Yes The authorization page fields.

auth_field is an Object and includes the following fields:

Parameter Type Required Description
user_field Object Yes Authorization page fields for individual invoices.
biz_field Object Yes Authorization page fields for company invoices.

user_field is an Object and includes the following fields:

Parameter Type Required Description
show_title Int No Indicates whether the invoice title can be entered. 0: No; 1: Yes.
show_phone Int No Indicates whether the phone number can be entered. 0: No; 1: Yes.
show_email Int No Indicates whether the email address can be entered. 0: No; 1: Yes.
require_phone Int No Indicates whether the phone number is required. 0: No, 1: Yes.
require_email Int No Indicates whether the email address is required. 0: No, 1: Yes.
custom_field Object No A custom field.

biz_field is an Object and includes the following fields:

Parameter Type Required Description
show_title Int No Indicates whether the invoice title can be entered. 0: No; 1: Yes.
show_tax_no Int No Indicates whether the tax code can be entered. 0: No; 1: Yes.
show_addr Int No Indicates whether the company address can be entered. 0: No; 1: Yes.
show_phone Int No Indicates whether the phone number can be entered. 0: No; 1: Yes.
show_bank_type Int No Indicates whether the bank name can be entered. 0: No; 1: Yes.
show_bank_no Int No Indicates whether the bank account number can be entered. 0: No; 1: Yes.
require_tax_no Int No Indicates whether the tax number is required. 0: No, 1: Yes.
require_addr Int No Indicates whether the company address is required. 0: No, 1: Yes.
require_phone Int No Indicates whether the phone number is required. 0: No, 1: Yes.
require_bank_type Int No Indicates whether the account number is required. 0: No, 1: Yes.
require_bank_no Int No Indicates whether the tax number is required. 0: No, 1: Yes.
custom_field Object No A custom field.

custom_field is a List, with each object containing the following fields:

Parameter Type Required Description
key String Yes Field name.
is_require Int No 0: No, 1: Yes. Default value: 0.
notice String No Message for user

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

Sample code

Request:
{
    "auth_field" : {
        "user_field" : {
            "require_phone" : 1,
            "custom_field" : [
                {
                    "is_require" : 1,
                    "key" : "field1"
                }
            ],
            "show_email" : 1,
            "show_title" : 1,
            "show_phone" : 1,
            "require_email" : 1
        },
        "biz_field" : {
            "require_phone" : 0,
            "custom_field" : [
                {
                    "is_require" : 0,
                    "key" : "field2"
                }
            ],
            "require_bank_type" : 0,
            "require_tax_no" : 0,
            "show_addr" : 1,
            "require_addr" : 0,
            "show_title" : 1,
            "show_tax_no" : 1,
            "show_phone" : 1,
            "show_bank_type" : 1,
            "show_bank_no" : 1,
            "require_bank_no" : 0
        }
    }
}
Response:
{
    "errcode": 0,
    "errmsg": "ok"
}

10. Querying Authorization Page Field Information

API description

The merchant can query authorization field settings via this API.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=get_auth_field&access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and the provided data is empty, i.e. {}.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
auth_field Object No Settings of the authorization page fields. This field is not empty when the error code is 0.

auth_field is an Object and includes the following fields:

Parameter Type Required Description
user_field Object No Authorization page fields for individual invoices.
biz_field Object No Authorization page fields for company invoices.

user_field is an Object and includes the following fields:

Parameter Type Required Description
show_title Int No Indicates whether the invoice title can be entered. 0: No; 1: Yes.
show_phone Int No Indicates whether the phone number can be entered. 0: No; 1: Yes.
show_email Int No Indicates whether the email address can be entered. 0: No; 1: Yes.
require_phone Int No Indicates whether the phone number is required. 0: No, 1: Yes.
require_email Int No Indicates whether the email address is required. 0: No, 1: Yes.
custom_field Object No A custom field.

biz_field is an Object and includes the following fields:

Parameter Type Required Description
show_title Int No Indicates whether the invoice title can be entered. 0: No; 1: Yes.
show_tax_no Int No Indicates whether the tax code can be entered. 0: No; 1: Yes.
show_addr Int No Indicates whether the company address can be entered. 0: No; 1: Yes.
show_phone Int No Indicates whether the phone number can be entered. 0: No; 1: Yes.
show_bank_type Int No Indicates whether the bank name can be entered. 0: No; 1: Yes.
show_bank_no Int No Indicates whether the bank account number can be entered. 0: No; 1: Yes.
require_tax_no Int No Indicates whether the tax number is required. 0: No, 1: Yes.
require_addr Int No Indicates whether the company address is required. 0: No, 1: Yes.
require_phone Int No Indicates whether the phone number is required. 0: No, 1: Yes.
require_bank_type Int No Indicates whether the account number is required. 0: No, 1: Yes.
require_bank_no Int No Indicates whether the tax number is required. 0: No, 1: Yes.
require_tax_no Int No Indicates whether the tax number is required. 0: No, 1: Yes.
custom_field Object No A custom field.

custom_field is a list, with each object containing the following fields:

Parameter Type Required Description
key String Yes Custom field name with a maximum length of 5 characters.
Is_require Int No Indicates whether the custom field is required. 0: No, 1: Yes.

Sample code

Request:  {}
Response:
{
    "errcode": 0,
    "errmsg": "ok",
    "auth_field": {
        "user_field": {
            "show_title": 1,
            "show_phone": 1,
            "show_email": 1,
            "custom_field": [{"key": "field1"}]
        },
        "biz_field": {
            "show_title": 1,
            "show_tax_no": 1,
            "show_addr": 1,
            "show_phone": 1,
            "show_bank_type": 1,
            "show_bank_no": 1,
            "custom_field": [{"key": "field2"}]
        }
    }
}

11. Linking Merchant ID and the Invoicing Platform

API description

When using post-paid invoicing, the merchant must first link its merchant ID with the invoicing platform ID. The invoicing platform ID is generated by the invoicing platform according to the WeChat rules and then sent to the merchant. This API only needs to be used once. Afterward, it only needs to be used when relinking the invoicing platform if the invoicing platform's ID changes or if the merchant changes invoicing platforms.

If the merchant has already implemented the WeChat Cards & Offers solution for delivering e-invoices, we suggest the merchant confirm the Official Account linked to the merchant ID is the same account that is used to pull up the authorization page in the WeChat Pay Merchants Platform before calling this API. If the accounts are inconsistent, the merchant shall use the Official Account linked to the merchant ID to call the API to pull up the authorization page again.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=set_pay_mch&access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
paymch_info Object Yes WeChat merchant ID and invoicing platform linking information.

paymch_info is an Object and includes the following fields:

Parameter Type Required Description
mchid string Yes WeChat Pay merchant ID.
s_pappid string Yes ID of the invoicing platform that provides invoicing services to this merchant. This ID is provided to the merchant by the invoicing platform.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code
errmsg string Yes Error message

Sample code

Request:
{
	"paymch_info":
    {
		"mchid": "1234",
		"s_pappid": "wxabcd"
	}
}
Response:
{
 	"errcode": 0,
    "errmsg": "ok"
}

12. Querying the Linking Information of Merchant ID and the Invoicing Platform

API description

The merchant can query its linking information with the invoicing platform via this API.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=get_pay_mch&access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and the provided data is empty, i.e. {}.

Response

The response parameters use JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code
errmsg string Yes Error message
paymch_info object No Linking information of the Merchant ID and the invoicing platform, returned when errcode is 0.

When errcode is 0, the returned data also contains a paymch_info object, which includes the following fields:

Parameter Type Required Description
mchid string Yes WeChat Pay merchant ID.
s_pappid string Yes ID of the linked invoicing platform.

Sample code

Request:  {}
Response:
{
	"errcode": 0,
	"errmsg": "ok",
	"paymch_info":
    {
		"mchid": "1234",
		"s_pappid": "wxabcd"
	}
}

13. Enabling Post-Payment Invoicing for a Specific Transaction

API description

After linking the WeChat merchant ID and the invoicing platform, Merchant with the ability to issue e-invoices can set whether payment success messages provide an invoicing entry for specific transactions. Users can use this entry to request an invoice.

Request method

The protocol and call method for this API are the same as described in the online Payment Documentation. This feature adds new field to the original payment API.

Request parameters

After the user confirms an order, the merchant can add the receipt field in the payment API (unified order placement/submit Quick Pay/payments-on-behalf) to indicate that an e-invoice needs to be issued. The parameters for this field are as follows:

Parameter Type Required Description
receipt string No Y. When Y is passed, an invoice entry is shown in the payment successful message and payment details page.

Response

It is the same as the result returned by the original payment API.

Sample code

<xml>
    <appid>wx2421b1c4370ec43b </appid>
    <attach>Payment test</attach>
    <body>JSAPIPayment test</body>
    <mch_id>10000100</mch_id>
    <receipt>Y</receipt>
    <nonce_str>1add1a30ac87aa2db72f57a2375d8fec</nonce_str>
    <notify_url>http://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url>
    <openid>oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</openid>
    <out_trade_no>1415659990</out_trade_no>
    <spbill_create_ip>14.23.150.211</spbill_create_ip>
	<total_fee>1</total_fee>
	<trade_type>JSAPI</trade_type>
	<sign>0CB01533B8C1EF103065174F50BCA001</sign>
</xml>

14. Unified Invoicing API - Issue Blue Invoice

API description Merchants who use the WeChat E-invoice feature can issue invoices via this API, no matter which invoicing platform they have selected for invoicing packages on the Official Accounts backend.

Request method Request URL: https://api.weixin.qq.com/card/invoice/makeoutinvoice?access_token={access_token}

Request method: POST

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
wxopenid String Yes User's openid, indicating who is issuing the invoice.
ddh String Yes Order no. set by enterprises. See 'Note 1'.
fpqqlsh String Yes Invoice request serial no., which is a serial number that uniquely identifies an invoice request. See 'Note 2'.
nsrsbh String Yes Taxpayer ID
nsrmc String Yes Taxpayer name
nsrdz String Yes Taxpayer's address
nsrdh String Yes Taxpayer's phone number
nsrbank String Yes Bank of the taxpayer's account
nsrbankid String Yes Taxpayer's bank account
ghfmc Sring Yes Buyer's name
ghfnsrsbh String No Buyer's ID
ghfdz String No Buyer's address
ghfdh String No Buyer's phone number
ghfbank String No Bank of the buyer's account
ghfbankid String No Buyer's bank account
kpr String Yes Invoice issuer
skr String No Recipient
fhr String No Reviewer
jshj String Yes The price including tax
hjse String Yes Total amount
bz String No Remarks.
hylx String No Industry type, 0: commercial, 1: other.
invoicedetail_list List Yes Invoice line item information

'Note 1': "ddh" (order no.) must be consistent with the order_id on the authorization page. Otherwise, the system will report an unauthorized order no. error. 'Note 2': "fpqqlsh" (invoice request serial no.) is the unique identifier of the invoice. The first six digits must be consistent with the merchant ID on the backend.

invoicedetail_list is a JSON list, with each object taking the following structure:

Parameter Type Required Description
fphxz String Yes Nature of the invoice line, 0: normal, 1: discount, 2: discounted.
spbm String Yes 19-digit tax classification code. For details, see 'Note'.
xmmc String Yes Item name
dw String No Unit of measurement
ggxh String No Model/specifications
xmsl String Yes Item quantity
xmdj String Yes Item unit
xmje String Yes The item amount excluding tax, in RMB and precise to two decimal places.
sl String Yes Tax rate, precise to two decimal spaces, e.g. 0.01.
se String Yes Tax amount, in RMB and precise to two decimal places.

'Note': The tax classification code is a 19-digit code in the Tax Classification and Coding for Commodities and Services. The merchant shall enter this field based on the actual invoice item and the situation of the enterprise and verify it with the enterprise's financial department.

Response The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code. For more information, see the error code list.
errmsg string Yes Error message

Sample code

Request
{
	"invoiceinfo" :
	{
	    "wxopenid": "os92LxEDbiOw7kWZanRN_Bb3Q45I",
	    "ddh" : "30000",
	    "fpqqlsh": "test20160511000461",
	    "nsrsbh": "110109500321654",
	    "nsrmc": "Baiwang electronic test1",
	    "nsrdz": "Shenzhen",
	    "nsrdh": "0755228899988",
	    "nsrbank": "Bank of China, Guangzhou branch",
		"nsrbankid": "12345678",
	    "ghfnsrsbh": "110109500321654",
	    "ghfmc": "Monday",
	    "ghfdz": "Guangzhou",
	    "ghfdh": "13717771888",
		"ghfbank": "ICBC",
		"ghfbankid": "12345678",
	    "kpr": "John",
	    "skr": "Mark",
	    "fhr": "Jane",
	    "jshj": "159",
	    "hjje": "135.9",
	    "hjse": "23.1",
	    "bz": "Remarks",
	    "hylx": "0",
	    "invoicedetail_list": [
	        {
	            "fphxz": "0",
	            "spbm": "1090418010000000000",
	            "xmmc": "Washing machine",
	            "dw": "Unit",
	            "ggxh": "60L",
	            "xmsl": "1",
	            "xmdj": "135.9",
	            "xmje": "135.9",
	            "sl": "0.17",
	            "se": "23.1"
	        }
	    ],
	}
}
Response
{
  "errcode": 0,
  "errmsg": "sucesss"
}

15. Unified Invoicing API - Invoice Offset

API description Merchants who use the WeChat E-invoice feature can offset invoices via this API, no matter which invoicing platform they have selected for invoicing packages on the Official Accounts backend.

Request method Request URL: https://api.weixin.qq.com/card/invoice/clearoutinvoice?access_token={access_token}

Request method: POST

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
wxopenid String Yes User's openid, indicating who is issuing the invoice.
fpqqlsh String Yes Invoice request serial no., which is the unique serial number used to query the invoice.
nsrsbh String Yes Taxpayer ID
nsrmc String Yes Taxpayer name
yfpdm String Yes Code of the original invoice, i.e. the invoice code of the blue invoice to be offset.
yfphm String Yes Number of the original invoice, i.e. the invoice number of the blue invoice to be offset.

Response The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code. For more information, see the Error Code List.
errmsg string Yes Error message. For more information, see the Error Code List.

Sample code

Request
{
	"invoiceinfo" :
	{
	    "wxopenid": "os92LxEDbiOw7kWZanRN_Bb3Q45I",
	    "fpqqlsh": "test20160511000400",
	    "nsrsbh": "110109500321654",
	    "nsrmc": "Baiwang electronic test1", 
	    "yfpdm" : "050003521100",
	    "yfphm" : "30329969",
  
	}
}

Response
{
  "errcode": 0,
  "errmsg": "sucesss"
}

16. Unified Invoicing API - Query Issued Invoices

API description Merchants who use the WeChat E-invoice feature can query issued invoices via this API, no matter which invoicing platform they have selected for invoicing packages on the Official Accounts backend.

Request method Request URL: https://api.weixin.qq.com/card/invoice/queryinvoceinfo?access_token={access_token}

Request method: POST

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
fpqqlsh String Yes Invoice request serial no., which is the unique serial number used to query the invoice.
nsrsbh String Yes Taxpayer ID

Response The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code. For more information, see the Error Code List.
errmsg string Yes Error message. For more information, see the Error Code List.
fpqqlsh String Yes Invoice request serial no., which is the unique serial number used to query the invoice.
jym String Yes Verification code, located in the upper-right corner of the e-invoice under the invoice issuance date.
kprq String Yes Verification code.
fpdm String Yes Invoice code.
fphm String Yes Invoice number.
pdfurl String Yes URL of the invoice.

Sample code

Request
{
	 "fpqqlsh": "test20160511000440",
	 "nsrsbh": "110109500321654"
}

Response:

{
    "errcode": 0,
    "errmsg": "Invoice data obtained successfully",
    "invoicedetail": {
        "fpqqlsh": "14574d75004451097845",
        "fpdm": "088978450417",
        "fphm": "21590001",
        "jym": "59004166725791147047",
        "kprq": "20171204172159",
        "pdfurl": "http://weixin.com"
    }
}

17. Setting Merchant's Contact Information

API description The merchant must set contact information before obtaining the authorization link.

Request method Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=set_contact&access_token={access_token}

Request method: POST

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
contact Object Yes Contact information.

contact is an Object and includes the following fields:

Parameter Type Required Description
time_out int Yes Invoicing time-out time
phone string Yes Contact number

Response The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code
errmsg string Yes Error message

Sample code

Request: 
{
	"contact" :
    {
        "phone" : "88888888",
        "time_out" : 12345
    }
}
Response:
{
 	"errcode": 0,
    "errmsg": "ok"
}

18. Querying Merchant's Contact Information

API description The merchant must set contact information before obtaining the authorization link.

Request method Request URL: https://api.weixin.qq.com/card/invoice/setbizattr?action=get_contact&access_token={access_token}

Request method: POST

The request parameters use JSON format and the provided data is empty, i.e. {}.

Response The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode int Yes Error code
errmsg string Yes Error message
contact Object Yes Contact information.

contact is an Object and includes the following fields:

Parameter Type Required Description
time_out int Yes Invoicing time-out time
phone string Yes Contact number

Sample code

Request:
{}
Response:
{
    "contact" : {
        "phone" : "88888888",
        "time_out" : 12345
    },
    "errcode" : 0,
    "errmsg" : "ok"
}

19. Unified Invoicing API - Async Notifications of Invoicing Result

API description

When a user grants the authorization for saving invoices in their WeChat account, the merchant can receive the authorization completed status push. After receiving the push, the merchant can send the order_id and invoice information to the invoicing platform. Then the invoicing platform can add the e-invoice in the user's Cards & Offers after issuing the invoice.

This event is sent to the URL entered by the developer (log in to the Official Accounts Platform and go to Developer Center Settings; an Official Account account shall be used for an open account, as shown in the figure below).

If the WeChat server does not receive the response within five seconds, the connection is broken and the request is initiated again. A maximum of three retries are made. We recommend that you use FromUserName + CreateTime to de-duplicate requests. If the merchant's server cannot ensure the request is processed within five seconds, it can return an empty string. When receiving the string, the WeChat server will not take any action or make a retry.

Response

The returned result is in XML format and contains the following fields:

Parameter Type Required Description
ToUserName String Yes The Official Account ID
FromUserName String Yes User's openid
CreateTime Int Yes Creation time of the event
MsgType String Yes Always set to "event".
Event String Yes Always set to "cloud_invoice_invoiceresult_event".
fpqqlsh String Yes Invoice request serial no., which is a serial number that uniquely identifies an invoice request.
nsrsbh String Yes Taxpayer ID
status Int Yes Invoicing result. 2: failed; 100: successful.

Sample code

<?xml version="1.0" encoding="utf-8"?>
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[]></MsgType>
  <Event><![CDATA[cloud_invoice_invoiceresult_event]]></Event>
  <fpqqlsh><![CDATA[14574d75004451097886]]></fpqqlsh>
  <status>100</status>
  <nsrsbh><![CDATA[150001197205134629]]></nsrsbh>
</xml>

99. Error Codes

Error Code Error Message Description
0 OK Successful
72015 unauthorized create invoice You do not have invoicing platform permissions. Check if the necessary permissions have been activated.
72023 invoice has been lock The invoice has been locked by another Official Account. Generally, this means the invoice has entered a subsequent reimbursement process and the Official Account/OA Company Account/App of the reimbursing company has locked the invoice.
72024 invoice status error Incorrect invoice status
72025 invoice token error Invalid wx_invoice_token
72028 invoice never set pay mch info WeChat Pay merchant information is not set.
72030 invalid mchid Invalid mchid
72031 invalid params Parameter error. The request may contain an invalid parameter name or a parameter value that fails the verification of backend.
72035 biz reject insert Invoicing has been rejected for the invoice. If an order_id has been used as a parameter when calling the "Reject Invoicing" API, an error occurs when the order_id is used again to add the e-invoice to Cards & Offers.
72036 invoice is busy The invoice is being modified. Try again later.
72038 invoice order never auth No authorization granted for the order. There may be a mismatch among the invoicing platform appid, merchant appid, and order_id.
72039 invoice must be lock first The order has not been locked. You must lock it before writing it off.
72040 invoice pdf error Invalid PDF. Provide an authentic and valid PDF.
72042 billing_code and billing_no repeated The billing code and billing number are not unique. This invoice has already been collected by another user.
72043 billing_code or billing_no size error Incorrect invoice ID and code
72044 scan text out of time The invoice title QR code timed out.
72063 biz contact is empty Merchant's contact information is empty. Please call the API to set merchant's contact information.
73000 sys error make out invoice failed Invoicing platform logic error
73001 wxopenid error Incorrect OpenId
73002 ddh orderid empty Order no. is empty.
73003 fpqqlsh empty Invoice serial no. is empty.
73004 kplx empty Invoice serial no. is empty.
73007 nsrmc empty Taxpayer's name is empty.
73008 nsrdz empty Taxpayer's address is empty.
73009 nsrdh empty Taxpayer's phone number is empty.
73010 ghfmc empty Buyer's name is empty.
73011 kpr empty Invoice issuer is empty.
73012 jshj empty The price including tax is empty.
73013 hjje empty Total amount is empty.
73014 hjse empty Total tax amount is empty.
73015 hylx empty Industry type is empty.
73016 nsrsbh empty Taxpayer ID is empty.
73100 ka plat error Invoicing platform error
73101 nsrsbh not cmp The taxpayer ID does not match. The taxpayer ID in the request is inconsistent with the number entered when creating a ticket.
73102 sys error WeChat Invoicing platform system error
73105 Kp plat make invoice timeout, please try again with the same fpqqlsh Invoicing in progress. Please invoice again using the same invoice request serial no.
73106 Fpqqlsh exist with different ddh This invoice request serial no. already exists and has been used by another order no.
73107 Fpqqlsh is processing, please wait and query later This invoice request serial no. is being processed. Please use the query API to obtain the result.
73108 This ddh with other fpqqlsh already exist This order was processed by another invoice request serial no.
73110 fpqqlsh first 6 byte not cmp The first 6 digits of the invoice request serial no. are incorrect.
40078 invalid card status No authorization granted for the card_id. If this error is reported in a sandbox environment, the reason is that the WeChat account calling the API is not added to the test list. If this error is reported in an official environment, the possible reasons include: the Official Account calling the API has not activated the Cards & Offers permission; or the gap between the creation time of card_id and the time of adding the e-invoice to Cards & Offers is too small.