1.1 Obtaining access_token
1.2 Receiving Callbacks
2.1 Obtaining a Ticket
2.2 Obtaining Authorization Page URL
2.3 Receiving Authorization Completion Event
2.4 Querying Authorization Information
2.5 Rejecting Collection of E-Bill
3.1 Obtaining Finance Bureau s_pappid
3.2 Receiving Authorization Completion Event

1. Common APIs

1.1 Obtaining access_token

API description
The access_token is the globally unique credential for an Official Accounts to call APIs. It is required for every API request of an Official Account, so developers need to keep it secure. To store the access_token, you need to reserve space for at least 512 characters. The access_token is valid for 2 hours and needs to be refreshed regularly. If you obtain a new access_token, the previous one will become invalid. We recommend that you obtain and refresh access_tokens using a central control server. All the access_token values used by other business logic servers come from this central control server and should not be refreshed separately. Otherwise, the access_token may be overwritten, which will affect services. For more information about access_tockens, see the Official Account development documentation. Request method
Request URL: https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
Request method: GET

Request parameters

Parameter Type Required Description
grant_type String Yes Enter client_credential to get access_token
appid String Yes Unique credential of a third-party user
secret String Yes AppSecret (the key of the unique credential of a third-party user).

Response Data format: JSON

Parameter Type Required Description
access_token String Yes The obtained token
expires_in Int Yes Validity period of the token (in sec)

Sample code

Response:
{
	"access_token":"ACCESS_TOKEN",
	"expires_in":7200
}

1.2 Receiving Callbacks

Log in to the Official Accounts Platform, go to Developer Center Settings, and set the URL for receiving callbacks. When a user authorizes the collection of an e-bill or the e-bill status is updated, the WeChat server notify the developer via this URL.
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. If developer'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.

2. APIs for a Payee Organization

2.1 Obtaining a Ticket

API description
A ticket is used to improve security. It is valid for 2 hours and must be refreshed regularly. We recommend that Official Account developers obtain and refresh all tickets using a central control server. Request method
Request URL: https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card
Request method: GET
Response
Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
ticket String Yes Temporary ticket used for the signature in the URL.
expires_in Int Yes Validity period of the ticket (generally, it is 7200 sec).

Sample code

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

Notes

  1. A ticket is valid for 7200 seconds. During the validity period, the ticket remains unchanged regardless of repeated requests.
  2. A ticket must be cached at the payee organization's backend to be called normally.

2.2 Obtaining Authorization Page URL

API description
This API is used to obtain the authorization page URL to allow users to go to the authorization page. Request method
Request URL: https://api.weixin.qq.com/nontax/getbillauthurl?access_token={access_token}
Request method: POST Request parameters

Parameter Type Required Description
s_pappid String Yes Finance bureau ID, which must be provided by the finance bureau.
order_id String Yes Order ID.
money Int Yes Order amount (in cents).
timestamp Int Yes Timestamp
source String Yes Channel from which the e-bill is issued. web: Official Account; app: app.
redirect_url String No URL of the page to which the user is redirected after a successful authorization.
ticket String Yes The Api_ticket, which is obtained using the "Obtain api_ticket" API.

Response Data format: JSON

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
expire_time Int Yes Validity period of the authorization URL (in sec).

Sample code

Request:
{
    "s_pappid": "wxabcd",
    "order_id": "1234",
    "money": 11,
    "timestamp": 1474875876,
    "source": "web",
    "redirect_url": "https://mp.weixin.qq.com",
    "ticket": "tttt"
}
Response:
{
    "errcode": 0, 
    "errmsg": "ok", 
    "auth_url": "http://auth_url",
    "expire_time": 7200
}

2.3 Receive Authorization Completion Event

API description
After the user's authorization, the Official Account of the payee organization receives the authorization completion event. For more information about the event push, see Receiving Callbacks.
Response
Data format: XML

Parameter Type Description
ToUserName String The Official Account ID.
FromUserName String User's openID.
CreateTime Int Creation time of the event
MsgType String Always set to "event".
Event String Always set to "user_authorize_invoice".
SuccOrderId String The order no. for which authorization is successful.
FailOrderId String The order no. for which authorization failed.
AuthorizeAppId String AppId of the Official Account receiving the event
Source String Channel from which the authorization is performed. web: H5 page in WeChat.

Sample code

<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>

2.4 Querying Authorization Information

API description
The payee organization can call this API to query whether the user have granted authorization for the order.
Request method
Request URL: https://api.weixin.qq.com/card/invoice/getauthdata?access_token={access_token}
Request method: POST
Request parameters

Parameter Type Required Description
order_id String Yes Order ID
s_pappid String Yes Finance bureau ID

Response Data format: JSON

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

Sample code

Request parameters
{
    "s_pappid": "{s_pappid}",
    "order_id": "{order_id}"
}
Response Data:
{
  "errcode": 0,
  "errmsg": "ok",
  "invoice_status": "auth success",
  "auth_time": 1480342498
}

2.5 Rejecting Collection of E-Bill

API description
After the user's authorization, if the payee organization finds that the information provided by the user is incorrect or a refund occurs, they can call this API to reject the e-bill collection and notify the user of the rejection.
Request method
Request URL: https://api.weixin.qq.com/card/invoice/rejectinsert?access_token={access_token}
Request method: POST
Request parameters

Parameter Type Required Description
s_pappid String Yes Finance bureau ID
order_id String Yes Order ID.
reason String Test The reason for cancellation
url String Yes The redirect URL

Response

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": "avb"
}
Response:
{
    "errcode": 0, 
    "errmsg": "ok"
}

3. APIs for a Finance Bureau

3.1 Obtaining Finance Bureau s_pappid

API description
This API is used to obtain the Finance Bureau s_pappid and pass it to the payee organization, which can use the s_pappid parameter to specify the finance bureau that provides billing services. A finance bureau only has one s_pappid so you only need to call the API once and save the s_pappid for later use.
Request method
Request URL: https://api.weixin.qq.com/card/invoice/seturl?access_token={access_token}
Request method: POST

Request parameters
The request parameters are in a JSON format and the input data is null, i.e. {}.
Response

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
invoice_url String Yes The finance bureau must give the s_pappid in the URL to the payee organization. When requesting the authorization URL, the payee organization passes this parameter to WeChat.

Sample code

Request
{}
Response
{
  "errcode": 0,
  "errmsg": "ok",
 "invoice_url": "https://mp.weixin.qq.com/bizmall/authinvoice?action=list&s_pappid=d3xxxxxxxxxxxxxGLSS0wrL14No8c1"
}

3.2 Creating Financial E-Bills

API description
A finance bureau can use this API to help the payee organization create a financial e-bill template. A single finance bureau can work with multiple payee organizations, and each payee organization can only have a unique card_id.
Request method
Request URL: https://api.weixin.qq.com/nontax/createbillcard?access_token={access_token}
Request method: POST
Request parameters
Data format: JSON
"invoice_info" field of a financial e-bill

Parameter Type Required Description
base_info Object Yes Financial e-bill information
payee string Yes The full name of the payee (biller) displayed in details of the financial e-bill

base_info field

Parameter Type Required Description
logo_url String Yes The logo of the finance bureau. For more information, see the "Upload Images" API.

Response

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
card_id String Yes The card_id of the e-bill.

Sample code

Request:
{
    "invoice_info" : {
        "payee" : "Test non-tax revenue e-bill",
        "base_info" : {
            "logo_url": : "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"
        }
    }
}
Response:
{
    "errcode": 0, 
    "errmsg": "ok", 
    "card_id": "pjZ8Yt9WoOePThU0NfUKz5-tBEWU"
}

3.3 Uploading PDF File

API description
The finance bureau can use this API to upload the PDF file of an e-bill to the WeChat Financial E-Bill Platform for billing. The uploaded PDF is valid for three days and the "Adding an E-bill to Cards & Offers" API must be called before it expires.
Request method
Request URL: https://api.weixin.qq.com/card/invoice/platform/setpdf?access_token={access_token}
Request method: POST
Request parameters
Data format: multipart/form-data

Parameter Required Description
pdf Yes The identifier of the media file in form-data, including the information such as filename, filelength, and content-type.

Response Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
s_media_id String Yes Used for obtaining the PDF file and adding the e-bill to Cards & Offers. It is valid for 3 days.

Sample code

Request:
------WebKitFormBoundary2exwM16BY25kVBgf
Content-Disposition: form-data; name="pdf"; filename="1133090578170938.pdf"
Content-Type: application/pdf
Pdf content
------WebKitFormBoundary2exwM16BY25kVBgf--
Response:
{
  "errcode": 0,
  "errmsg": "ok",
  "s_media_id": "3015806758683707"
}

3.4 Obtaining PDF File

API description
This API is used to obtain the PDF file of a financial e-bill. Request method
Request URL: https://api.weixin.qq.com/card/invoice/platform/getpdf?access_token={access_token}
Request method: POST
Request parameters
Data format: JSON

Parameter Type Required Description
s_media_id string Yes The s_media_id of the financial e-bill.
actin String Yes Enter "get_url".

Response
Data format: JSON

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
pdf_url String Yes URL of the PDF
pdf_url_expire_time Int Yes Validity period of the pdf_url (7200 sec)

Sample code

Request:
{
         "action": "get_url",
         "s_media_id": "75195574948725301"
}
Response:
{
    "errcode": 0,
    "errmsg": "ok",
    "pdf_url": "https://mp.weixin.qq.com/intp/invoice/getpdf?action=media_pdf&media_key=dFRnTkV6WCswNjB1V1czZ0tVU3MhaX4yb2pxeEVSY0teSCtuflY6UXAifD5rL09kTjFpOFVWKyJGNCgxTCtkJER6VjFlRCtVU2JKcS5FZw",
    "pdf_url_expire_time": 7200
}

3.5 Adding an E-Bill to User's Cards & Offers

API description
After the user's authorization for collecting the e-bill, the payee organization requests the e-bill for an order from the finance bureau, which then issues the e-bill to the user using this API.
Request method
Request URL: https://api.weixin.qq.com/nontax/insertbill?access_token={access_token}
Request method: POST
Request parameters
Data format: JSON

Parameter Type Required Description
order_id string Yes The order_id of the financial e-bill.
card_id String Yes The card_id of the financial e-bill.
appid String Yes The appid used for the authorization for this order. It is generally the appid of the payee organization.
card_ext Object Yes Content of the financial e-bill.

"card_ext" includes the following information:

Parameter Type Required Description
user_card Object Yes A structured field of user information

"user_card" includes an invoice_user_data object, which contains the following fields:

Parameter Type Required Description
fee Int Yes Amount of the financial e-bill (in cents).
title String Yes Payer for the financial e-bill
billing_time Int Yes Issuance time of the financial e-bill, expressed as a 10-digit timestamp (UTC+8).
billing_no String Yes ID of the financial e-bill
billing_code String Yes Code of the financial e-bill
s_pdf_media_id String Yes After the financial e-bill's PDF file is uploaded to the WeChat Financial E-Bill Platform, a financial e-bill s_media_id is generated, which can be directly used to issue the financial e-bill. For more information about uploading, see "5. Uploading PDF file".

Response Data format: JSON

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
code String Yes Code of the financial e-bill
openid String Yes User ID ( the openid receiving the financial e-bill)

Sample code

Request:
{
    "order_id" : "1511169724",
    "card_ext" : {
        "user_card" : {
            "invoice_user_data" : {
                "billing_time" : "1511169724",
                "billing_code" : "aabbccdd",
                "billing_no" : "1511169724",
                "s_pdf_media_id" : "s_pdf_media_id",
                "fee" : 123,
                "title" : "Guan Ge's Bill"
            }
        }
    },
    "card_id" : "pjZ8Yt7xiy3b9UfffRIA4Tm2xTnw",
    "appid" : "wxc0b84a53ed8e8d29"
}
Response:
{
    "errcode": 0, 
    "errmsg": "ok", 
    "code": "682xxxx661927", 
    "openid": "ojZ8Ytz4lESxxxx_R1TvB2Kds"
}

3.6 Status Update Event Push

API description
When the reimbursing organization updates the status of a financial e-bill, the Official Accounts Platform pushes an Official Account message to the URL set by the finance bureau for receiving callback events. For more information about event push, see the section 6.1.2.
Response
Data format: XML

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 "update_invoice_status".
Status String Yes Reimbursement status of the financial e-bill
CardId String Yes ID of the financial e-bill
Code String Yes Code of the financial e-bill

Sample code

<xml>
<ToUserName><![CDATA[gh_9e1765b5568e]]></ToUserName>
<FromUserName><![CDATA[ojZ8Ytz4lESgdWZ34L_R1TvB2Kds]]></FromUserName>
<CreateTime>1478068440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[update_invoice_status]]></Event>
<Status><![CDATA[INVOICE_REIMBURSE_INIT]]></Status>
<CardId><![CDATA[pjZ8Yt7Um2jYxzneP8GomnxoVFWo]]></CardId>
<Code><![CDATA[186921658591]]></Code>
</xml>

3.7 Updating E-Bill Status

API description
If the status of a financial e-bill of the finance bureau changes, this API should be called to sync the status to the Official Accounts Platform to ensure the financial e-bill status is consistent between the two sides.
Request method
Request URL: https://api.weixin.qq.com/card/invoice/platform/updatestatus?access_token={access_token}
Request method: POST
Request parameters
Data format: JSON

Parameter Type Required Description
card_id String Yes ID of the financial e-bill
code String Yes Code of the financial e-bill
reimburse_status String Yes Reimbursement status of the financial e-bill

Response

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

Sample code

Request:
{
    "card_id": "pjZ8Yt7Um2jYxzneP8GomnxoVFWo",
    "code": "186921658591",
    "reimburse_status": "INVOICE_REIMBURSE_INIT"
}
Response:
{
    "errcode": 0, 
    "errmsg": "ok"
}

4. Remarks

4.1 Authorization Status for the Order

Status Description
never auth Not authorized by the user.
auth success Authorized by the user.
auth time out E-bill collection times out after the user grants authorization.
invoice send The e-bill is collected successfully after the user grants authorization.
reject insert Bill collection is canceled.
invoice sending Bill collection is in progress after the user grants authorization.

4.2 Error Codes

Status Description Remarks
0 OK Successful
72015 unauthorized create invoice No permission for this operation. Check whether you have activated the permission.
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 Collection has been rejected for the financial e-bill. If the order_id has been used as a parameter when the "Reject Collection" API is called, an error occurs when the order_id is used again to add the e-bill to Cards & Offers.
72036 invoice is busy The financial e-bill is being modified. Try again later.
72038 invoice order never auth No authorization granted for the order. There may be a mismatch between the finance bureau s_pappid, payee organization appid, and order_id.
72040 invoice pdf error Invalid PDF. Provide an authentic and valid PDF.
72042 billing_code and billing_no repeated Duplicate e-bill ID and code.
72043 billing_code or billing_no size error Incorrect e-bill ID and code
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 Cares & Offers permission; or the gap between the creation time of card_id and the time of adding the e-bill to Cards & Offers is too small.