WeChat Payment API

1.
ABOUT THIS DOCUMENT
This document is the official manual for WeChats payment APIs. As such, it is the tutorial for technical
architects, R&D engineers, testing engineers and service engineers for the integrated WeChat payment system, which
includes vendors' systems such as online shopping platforms, cashier systems, or automatic smart POS systems. The
following topics are designed to be read in order and there are references to topics "previously seen" and topics "yet to
come". These references are linked accordingly and it should generally not be a problem to read ahead on other topics.
2. TERMS USED IN THIS DOCUMENT
1. Payment Method
1) Quick Pay
The Payer shows their bar code or QR Code on WeChat's Quick Pay page to the Vendor to scan in order to pay
directly. This mode applies to offline payment scenarios.
2) QR Code Payment
The Vendor generates a transaction QR Code according to the WeChat Payment Protocol and the Payer goes to
"Scan QR Code" in their WeChat in order to complete payment. This mode is applicable to payments made on websites,
physical stores, media advertising, or other scenarios.
3) In-App Web-based Payment
The Payer opens the Vendor's HTML5 pages on their WeChat and calls the WeChat payment module via the
JSAPI interface to pay their transaction. This mode is applicable in the following scenarios:
The Payer enters the Vendors official account and completes their payment on the transaction page;
The Payers friend shares the Vendor's payment URL in a chat or in Moments and the payer clicks the link to
complete their payment;
The Payer scans the payment QR Code displayed within the Vendors page and opens it in a browser to
complete their payment.
4) In-App Payment
In-App payment also refers to a mobile-based payment in which the Vendor calls the WeChat payment module by
using the open SDK integrated in their mobile-based app to pay for transactions.
2. Definitions
1) WeChat Official Account Admin Platform

The WeChat Official Account Admin Platform serves as the application entry and management platform for
official accounts. Using this platform, vendors can submit their basic information, business data and financial
information for enabling WeChat payment.
URL: http://mp.weixin.qq.com
2) WeChat Open Platform
The WeChat Open Platform serves as the entry point for a vendors' app to access to the WeChat payment open
API. Using this platform, vendors can apply for WeChat in-app payment.
URL: http://open.weixin.qq.com
3) WeChat Vendor Platform
The WeChat Vendor Platform serves as the functional hub for vendor features related to WeChat payment,
including parameter settings, payment data query and statistics, online refunds, mobile coupon management, and other
features.
URL: http://pay.weixin.qq.com
4) WeChat Payment System
The WeChat Payment System is the generic term for the backend services processing system for APIs, account
system, and the callback notification system for the WeChat payment process.
5) Vendor Point of Sale Terminal
The Vendor Point of Sale Terminal refers to the POS system commonly used by a cashier that helps record
product data, create orders, assist the Payer's payment and print the transaction bill. When integrating with WeChat
payment, this system requires the development and testing of a POS system.
6) Vendor Backend System
The Vendor Backend System is the generic term for the Vendor's backend services processing system, and
includes the Vendor's website, checkout system, purchase-sale-stock system, delivery system, and customer service
system.
7) Scanner
The Scanner is used to help the Vendor's system to quickly read coding data within an image. Based on the type of
image coding, the vendor can use a QR Code scanner or a bar code scanner. In terms of scanner types, there are
infrared scanners and laser scanners.
8) Vendor Certificate
The Vendor Certificate is a binary file provided by WeChat, which is used as a certificate to identify the Vendor's
identity when the Vendor's system initiates a request session with WeChats backend payment server.
9) Signature
The Vendors backend and the WeChat payment system create the same signature based on the same secret key
and algorithm and use it to verify each other's identity. The signature algorithm is created and provided by WeChat.
Commonly used signature modes are MD5, SHA1, SHA256, and HMAC.
10) JSAPI-based Web Payment
JSAPI-based Web Payment also refers to the above-mentioned In-App web-based payment. Using this method,
the Payer can click a URL in an official account, Moments or a chat, and scan a QR Code using WeChat to open the
Vendor's HTML5 page to complete their payment.
11) Native Payment
Native Payment refers to Quick Pay on WeChat. Using this method, the Vendor creates a QR Code using the
WeChat payment protocol. The Payer then scans the QR code to confirm the transaction, and enters their payment
password to complete the payment.
12) Payment Password
A Payment Password is set independently by the Payer when enabling WeChat payment, and is used to confirm
their payment and authorize transactions. This password is different from their WeChat password used to log in to
WeChat.
13) OpenID
OpenID is used to share a user's identity to an official account, and is different between official accounts. The
Vendor's backend obtains the Payer's OpenID during login authorization, payment notifications, and when calling the
Query Order API. With OpenID, the system can check whether the payment-related operations are done by the same
payer and send service feeds and templated messages to the Payer.
3. PAYMENT ACCOUNT
Vendors can apply for a payment method on the WeChat Official Account Admin Platform (for Native Quick Pay
and In-App Web-based Payment) or the WeChat Open Platform (for In-App Payment) as instructed. After the WeChat
payment staff receives and reviews the application, the corresponding payment permission will be opened for the
Vendor. The Vendor will then receive an email containing required payment instructions from the WeChat Payment
Assistant, as shown in Figure 3.1.
Figure 3.1 Email Template for Application Approval
Table 3.1 shows the relation between email parameters and API parameters.
Table 3.1 Account parameters
Parameters in API Description

Email Parameter
Name
APPID appid appid is a unique identity key for each app within the WeChat Official Account Admin
Platform or WeChat Open Platform, and is assigned by WeChat after developers apply
for it on these platforms. The application approval email also contains this field.
Vendor ID for mch_id Specifies vendor's receipt ID assigned by WeChat Payment after they have applied for
WeChat Payment WeChat Payment
API Key key This key is created for transaction signatures and is retained in the Vendors backend
and WeChat payment system, and should not be made available publicly or on the
Internet. The Vendor should keep this key secured and avoid disclosing it to others.
Vendors may configure the key according to the email instructions.
Appsecret secret AppSecret is the API password corresponding to APPID, and is used to obtain a
certificate (access_token) for calling API access_token. Using WeChat payment, you
should obtain an OpenID via the OAuth2.0 interface and use it within the single
interface for In-App Web-based payment. Developers shall be qualified to get
AppSecret in development mode.
4. API RULES
1. Protocol Rules
The following specifies the rules for calling the API when a vendor accesses WeChat payment:
Table 4.1 API Rules
Transfer Use HTTPS for secure transactions

Mode
Submit Mode Use POST method
Data Format Data submitted and returned is in XML format
Char Use UTF-8 character encoding

Encoding
Signature MD5 or HMAC-SHA256

Algorithm
Signature Signature-checking is required for requesting and receiving data. For more information, see Section 4.3.1
Requirement Signature Algorithm.
Certificate A vendor certificate is required for calling the Submit Refund API or Revoke Order API.
Requirement
Logic Determine protocol field, service field and transaction status.

Judgment
2. Parameter Specifications
1) Payment Amount
The currency type for transaction is CNY (Chinese yuan) by default. The unit used in payment amount is cent
and must be an integer. However, the unit yuan is used in the transaction amount when downloading transaction
history.
For foreign transactions, the transaction amount will use the smallest unit of currency, but the reference value
must be an integer without decimals. For example, using a currency type of "United States dollars" a reference value of
"1750" in the payment amount would be equivalent to US$17.50.
2) Currency Type
The list of currency types is as below:
GBP: Great Britain pound
HKD: Hong Kong dollar
USD: United States dollar
JPY: Japanese yen
CAD: Canadian dollar
AUD: Australian dollar
EUR: Euro
NZDNew Zealand Dollar
KRWSouth Korean won
THB: Thailand baht
Notes: The currency type for payment and refund must be identical.
3) Time Protocol
China Standard Time (UTC+08) is used in this document. If the Vendor is not in this time zone, they should
convert their current time into China Standard Time. For instance, if a vendor is in London at the local time of
November 11, 2014 0:00, it will be November 11, 2014 8:00 AM in Beijing.
4) Timestamp
Taking China Standard Time (UTC+08) as the standard time zone, a timestamp is calculated as seconds since
1970/01/01 00:00:00 UTC and is the required method to store timestamps in this document. Note: Milliseconds should
be rounded to seconds (10-digits).
5) Vendors Order Number
The order number for a payment is defined by the vendor and must be unique. We suggest adding a random
sequence to the end of the current time in order to create a unique and sequenced number. The original order number is
used when initiating a payment again in order to avoid duplicate transactions. However, orders that are paid, closed or
revoked (for more information, see Section 9 Public API) cannot be paid again.
3. Security Specifications
1 Signature Algorithm
General steps to create a signature:
Step 1: Presume all data sent and received is the set M. Sort non-empty values in M in ascending alphabetical
order (i.e. lexicographical sequence), and join them into string A via the corresponding URL key-value format (e.g.
key1=value1&key2=value2).
Notes:
Sort parameter names in ascending alphabetical order based on their ASCII encoded names (e.g.
lexicographical sequence);
Empty parameter values are excluded in the signature;
Parameter names are case-sensitive;
When checking returned data or a WeChat push notification signature, the transferred sign parameter is
excluded in this signature as it is compared with the created signature.
Step 2: Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on
stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue).
Example:
For the following transferred parameters:
appid wxd930ea5d5a258f4f
mch_id 10000100
device_info 1000
body test
nonce_str ibuaiVcKdpRxkhJA
(1) Sort ASCII code of parameter names by lexicographical sequence based on the format of "key=value"
stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVc
KdpRxkhJA";
(2) Join API keys
stringSignTemp="stringA&key=192006250b4c09247ec02edce69f6a2d"
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
Obtain data to be transferred below:
<xml>
<appid>wxd930ea5d5a258f4f</appid>
<mch_id>10000100</mch_id>
<device_info>1000<device_info>
<body>test</body>
<nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
<xml>
WeChat provides online signature tools for this API: URL1.
2 Random String Algorithm
nonce_str is included in WeChat payment API protocols to ensure unpredictability for signatures. We suggest
calling the random() function to create a signature and convert its value into a string.
3 Vendor Certificate
1) Obtain Vendor Certificate
APIs related to payment rollbacks (such as refunds or revoked orders) require a vendor's certificate. The certificate
is issued to vendors via an email notification after the vendor applies for WeChat payment successfully. There are four
certificates that might be required as indicated below:
Table 4.2: Certificate Description
Certificate Description Use Case Remarks

Attachment
pkcs12 format Includes certificate for private Calling the Revoke Order API Double-click to import into a Windows
(apiclient_cert.p12) key information, in p12(pfx) and Submit Refund API system and enter certificate password as
format and issued by WeChat prompted. By default, the certificate
payment for identity password is the vendor's ID (e.g.
verification 10010000)
pem format for apiclient_cert.p12 certificate pem format should be used You can also use the "openssl"
certificate files may be imported to for PHP applications as PHP command to import the p12-format
(apiclient_cert.pem) create a certificate in pem can't use the p12 format certificate as below: openssl pkcs12
format. Do not disclose to -clcerts -nokeys -in apiclient_cert.p12
others. -out apiclient_cert.pem
pem format for apiclient_cert.p12 certificate pem format should be used You can also use the "openssl"
certificate secret key files may be imported to for PHP applications as PHP command to import the p12-format
(apiclient_key.pem) create a certificate in pem can't use the p12 format certificate as below: openssl pkcs12
format. -nocerts -in apiclient_cert.p12 -out
apiclient_key.pem
CA certificate WeChat payment API server This file is the root certificate Root certificates are built-n to some
(rootca.pem) also deploys server issued by authorities that sign tools. For tools without root certificates,
certificates to verify identity WeChat payment certificates, the ones provided here may be used.
for WeChat payment. When which can be used to verify
vendors call APIs, the the authenticity of WeChat
authenticity of the server payment server certificates.
called and domain name shall
be verified.
2) Use Vendor Certificate
apiclient_cert.p12 is vendor's certificate files for all R&D operations except PHP-based development.
Vendors using a .NET environment should ensure that their framework version is greater than 2.0. They can
double-click to install the certificate "apiclient_cert.p12" before using.
The default password for the calling vendor's certificate and installation is vendor's ID (mch_id).
"apiclient_cert.pem" and "apiclient_key.pem" are required for PHP-based development, and rootca.pem is
CA certificate.
For more invocation examples, see Demo outbound links provided by WeChat payment.
3) Vendor Certificate Security
Certificate files should not be stored in a virtual directory on the web server. Instead, they should be placed in a
directory with strict access control in order avoid the certificate being downloaded by others. The Vendor's server
should also be free from viruses and trojan horses to avoid potential certificate theft.
4 Vendor's Callback API Security
In many network environments, HTTP requests bear the risk of DNS spoofing, unwanted pop-ups, and data theft
and modifications. The Vendor's callback API should use HTTPS to ensure data transfer security. For this reason, we
suggest all vendors use HTTPS for all WeChat payment callbacks. For more information, see the HTTPS Building
Guide.
4. Getting OpenID
WeChat Official Account Admin Platform:

After messaging between a follower and Official Accounts, the Official Accounts can get the follower's OpenID.
Each user has a unique OpenID after its WeChat ID is encrypted. User's OpenID varies from different Official
Accounts.
Official Accounts can get user's OpenID by the API below. For information about user's alias, photo picture,
gender, location, language, and following time, user's authorization is required.
URL: http://mp.weixin.qq.com/wiki/17/c0f37d5704f0b64713d5d2c37b468d75.html
To use OpenIDs from different platforms as one ID for the same user, developers can use the API below:
URL: http://mp.weixin.qq.com/wiki/14/bb5031008f1494a59c6f71fa0f319c66.html
WeChat Open Platform:

Mobile apps can use the API below to get user's OpenID:
https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open141931785
1&token=&lang=zh_CN
Website apps can use the API below to get user OpenID:
https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open141931650
5&token=&lang=zh_CN
5. QUICK PAY PROGRAMMING GUIDE
1. Use Case
Step 1After logging in to WeChat, the Payer enters Quick Pay in "Me"->"Wallet", as shown in Figure 5.1;
Step 2Cashier creates a transaction order and the Payer confirms the payment amount displayed on the point of
sale terminal;
Step 3Cashier scans barcode or QR code shown by the Payer into the point of sale terminal and the transaction
order is submitted to the transaction system on a WeChat payment server;
Step 4After the payment request is received by the transaction system, the transaction system determines whether
the Payers' payment password must be verified. If the payment password is not required, the payment is made directly.
Otherwise, the Payer is prompted to enter their password, as shown in Figure 5.2. If the payment is successful, the
Payers will see a successful payment message in WeChat, as shown in Figure 5.3; and if the payment fails, a payment
error page will be displayed instead.
Figure 5.1 Quick Pay Figure 5.2 Confirm Payment Figure 5.3 Successful Payment
2. Payment Verification Code Rules
The Payer's payment password must be verified for any transactions totaling more than 1000 CNY;
For transactions less than 1000 CNY, allow up to 5 password-exempt transactions per day for each WeChat
account and require password verification after reaching this limit;
Require password verification for any untrusted or suspicious transactions;
3. Participating Vendors
Users can experience this payment method for themselves at stores and shops that support WeChat Payment.
Convenience stores: 7-Eleven, Guoda36524, Hi-24, etc.
Chain drugstores: LBX Pharmacy, GuoDa Drugstore, Nepstar Drugstore, etc.
Department stores: Rainbow, etc.
4. Process for Vendors
Based on the Vendors environment, a vendor may process a payment via backend access or via physical store
access. Payment scenarios include payments requiring password-verification and payments that are exempt from
password-verification.
1 Access Mode - Vendors' Backend Access
This mode is applied to vendors who are equipped with a unified backend. In this mode, the Cashier
communicates with the vendors backend first and the backend will subsequently send transaction requests to and
receive results from the WeChat payment system.
Figure 5.4 Vendors' Backend Access Process
2 Access Mode -- Physical Store Access
This mode is applied to vendors who communicate with the WeChat payment system via a public network. In this
mode, the Cashier initiates a transaction request and handles returned results directly with the WeChat payment system.
However, the Vendor can process other transactions between their physical stores and backend based on their
requirements.
Figure 5.5 Physical Store Access Process
3 Password-Exempt Payment Process
This section uses the Vendors backend access mode to illustrate the payment process, as shown in the sequence
chart below.
Figure 5.6 Sequence Chart of Password-Exempt Payment
Password-exempt payment steps:
1) The Cashier creates a payment order on their point of sale terminal and shows the payment amount to the
Payer;
2) Payer opens WeChat and enters Quick Pay in "Me"->"Wallet";
3) Cashier scans the bar code on the Quick Pay screen via their scanner;
4) Scanner reads and transfers the code data to the Cashiers point of sale terminal;
5) The Cashier initiates payment request to Vendor's backend after receiving payment information.
6) The Vendors backend handles the payment request sent by the physical store point of sale terminal and
creates a signature for it, and then calls the Submit Quick Pay API to start a payment request to the
WeChat payment system;
7) The WeChat payment system receives the Vendor's payment request, processes the data after validation, and
returns a payment result to the Vendor's backend. If the transaction is successfully paid, the WeChat payment
system sends the payment result to the Vendor and payer at the same time via SMS or via a WeChat
message;
8) The Vendor's backend validates the signature to process relevant data, and sends the payment result to the
Cashiers point of sale terminal.
9) The Cashier delivers goods to the Payer after receiving a successful payment result.
4 Password-Verification Payment Process
The password-verification payment process is quite similar to that of password-exempt payments. The first 5 steps
are identical. During the password-verification payment process, the WeChat backend prompts the Payer for their
payment password after the Vendors backend calls the Submit Quick Pay API to initiate a payment request. After
the Payer has successfully verified their payment password, the API returns a USERPAYING status immediately to the
Vendors backend, and the Vendor's backend communicates to the WeChat payment system Query Order API in order
to confirm whether the order was successfully paid for.
The password-verification payment process is shown in the following sequence chart:

Figure 5.7 Process Diagram for Password-Verified Payment
Here we show only the steps that are different from those previously described.
1) The Cashiers point of sale terminal initiates a payment request to the Vendors backend after creating the
order;
2) The Vendors backend calls the Submit Quick Pay API to create a payment transaction;
3) The WeChat payment system verifies the Vendors' request and determines whether password verification is
required;
4) The WeChat payment system returns a USERPAYING status and the Vendor's backend sends a response
containing a result to the Cashiers point of sale terminal;
5) WeChat payment system prompts the Payer to enter their payment password on their WeChat;
6) The Payer confirms the payment and enters their payment password;
7) The Payer submits verification after entering their password;
8) The WeChat payment backend returns a payment result after the Payer completes the transaction on WeChat
and notifies the Payer of the result via SMS and a WeChat message;
9) The Vendor's backend receives USERPAYING status from the WeChat payment system and queries the
actual payment result via the Query Order API (For more information, see Public API);
10) If the WeChat payment system replies with a payment status of USERPAYING, the Vendors backend calls
the Query Order API every 5 seconds to determine the final actual payment status. If the Payer cancels
their payment or delays their payment for more than 30 seconds, the Vendors' backend halts the polling
process and calls the Revoke Order API to revoke the transaction.
5 Exception Handling
Follow the instructions below to troubleshoot any payment exceptions:
1) If the Payer cannot find their order in their transaction history when they're prompted of a payment error on
WeChat, they will require the Vendor to initiate the order again; if the order is successfully paid for, the
Vendors backend calls the Query Order API to query the actual payment status again;
2) The Payer will need to repeat the payment process if they're prompted of a payment error caused by
insufficient balance, an invalid card or for other reasons;
3) The Vendors backend should call the Revoke Order APIFor more information, see Public API) to
cancel a transaction whenever the transaction times out or the payment fails;
4) The Vendors backend should send a payment error message to the Cashiers point of sale terminal when it is
caused by an abnormal bank system error, insufficient balance, unsupported bank, or for any other reason;
5) Depending on the type of error code returned, the transaction may be canceled. For details, see API Return
Error Code List.
5. Submit Quick Pay API
1 Use Case
After the Cashier scans a bar or QR code on the Quick Pay page shown by the Payer, the payment parameters are
transferred to the Vendors backend. The Vendors backend calls the Submit Quick Pay API to initiate a payment.
2 URL
https://api.mch.weixin.qq.com/pay/micropay
3 Certificate Requirements
No certificate is required.
4 Parameter Settings
Name ID Type Required Example Description
Official appid String(32) Yes wx8888888888888 Specifies an Official Account ID

Account ID 888 assigned by WeChat
Vendor ID mch_id String(32) Yes 1900000109 Specifies vendor ID assigned by

WeChat Payment
Device ID device_inf String(32) No 013467007045764 Specifies a Terminal device ID (such

o as store number as defined by the
vendor)
Random nonce_str String(32) Yes 5K8264ILTKCH1 32 characters or fewer. For more

string 6CQ2502SI8ZNM information, see Section 4.3.2
TM67VS Random String Algorithm .
Signature sign String(32) Yes C380BEC2BFD72 Signature. For more information, see
7A4B6845133519 Section 4.3.1 Signature Algorithm.
F3AD6
Sign type sign_type String(32) NO HMAC-SHA256/ Currently support HMAC-SHA256

MD5 and MD5, default is MD5. If you
choose HMAC-SHA256, sign_type
must be pass
Item body String(32) Yes Pay for QQ Coins Short description of item(s) to be
Description purchased for the Payer
Item Details detail String(8192 No iPad Mini in white Displays detailed item list
) with 16G memory
Additional attach String(127) No User-Defined Data Allow vendors an additional field to
Data be returned in the payment
notification after submitting a
payment or in the Query Order API
Vendor Order out_trade_ String(32) Yes 121775250120140 32 alphanumeric characters or less.

Number no 7033233368018 For more information, see Section 4.2
Vendor's Order Number.
Bid price total_fee Int Yes 888 Specifies the total order amount. The
units are expressed in cents as
integers. For more details, see Section
4.2 Payment Amount.
Currency fee_type String(8) Yes GBP ISO-4217 standard compliant and be

Type described by three characters based
code. For more information, see
Section 4.2 Currency Type.
Terminal IP spbill_crea String(16) Yes 8.8.8.8 Specifies the machine IP that calls the
te_ip WeChat Payment API
Item Label goods_tag String(32) No Specifies the label of goods, which is

a parameter in the coupon feature for
businesses. For more information, see
Section 10 Mobile coupons.
Authorization auth_code String(128) Yes 120061098828009 Specifies the authorization code by

Code 406 scanning a barcode/QR Code on
Quick Pay
Example
<xml>
<appid>wx2421b1c4370ec43b</appid>
<attach>Additional Order Descriptionr</attach>
<auth_code>120269300684844649</auth_code>
<body>Quick Pay Testing</body>
<device_info>1000</device_info>
<goods_tag></goods_tag>
<nonce_str>8aaee146b1dee7cec9100add9b96cbe2</nonce_str>
<out_trade_no>1415757673</out_trade_no>
<spbill_create_ip>14.17.22.52</spbill_create_ip>
<total_fee>1</total_fee>
<sign>C29DB7DB1FD4136B84AE35604756362C</sign>
</xml>
Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.
5 Return Data
Field Name ID Required Type Example Description
Return return_code Yes String( SUCCESS Set to SUCCESS or FAIL

Status Code 16)
Specifies communicating label but not transaction
label. The status of the transaction is determined by
the value of the result_code field.
Return Data return_msg No String( Signature If not empty, this is the error description. If not
128) Failure empty, this is the error description
Signature Failure
Parameter format checking error
When return_code is SUCCESS, return data will also include the following fields:
Official appid Yes String(3 wx8888888888 The Official Account ID submitted when
Account ID 2) 888888 calling the interface
Vendor ID mch_id Yes String(3 1900000109 The vendor ID submitted when calling the
2) interface
Device ID device_info No String(3 0134670070457 The device ID submitted when calling the
2) 64 interface
Random nonce_str Yes String(3 Fsdfds1235df23 32 characters or fewer, returned from

String 2) 1asdfg32145gfd Wechat payment
se
Signature sign Yes String(3 C380BEC2BFD Signature returned from Wechat payment.
2) 727A4B684513 For more information, see Section 4.3.1
3519F3AD6 Signature Algorithm
Service Result result_code Yes String(1 SUCCESS Set to SUCCESS or FAIL

6)
Error Code err_code No String(3 SYSTEMERRO For more information, please refer to
2) R Section 5.5.6 Error Codes
Error Code err_code_des No String(1 System error The detailed description of error returned
Description 28)
When both return_code and result_code are SUCCESS, return data will also include the following fields:

User Tag openid Yes String The only identification under the current appid
(128)
Follows is_subscribe Yes String Y For users who pay for transactions related to an
Official (1) official account, the value in this field states
Account or whether the user is current following the official
not account
Y: Follows
N: Doesnt follow
Transaction trade_type Yes String MICROPAY The transaction type is MICROPAY(quick pay)
Type (16)
Payment bank_type Yes String CMC Strings states bank type

Bank (16)
Currency fee_type Yes String GBP Complies with ISO 4217 standards and uses 3
Type (8) characters based code. For more information, see
Total Amount total_fee Yes Int 100 Specifies the total amount for a transaction. The
unit is cent and the value must be integer. For more
information, see Section 4.2. Payment Amount.
Cash Type cash_fee_type Yes String CNY Payers currency type. Complies with ISO 4217
(8) standards and uses CNY (Chinese yuan) by default.
For more information, see Section 4.2 Currency
Type.
Cash cash_fee Yes Int 100 Specifies the total cash payment amount of a
Payment transaction. For more information, see Section 4.2
Amount Payment Amount.
WeChat transaction_id Yes String 12177525012 The WeChat payment order id

Payment (32) 01407033233
Order 368018
Number
Vendor Order out_trade_no Yes String 12177525012 Specifies the order number created within the
Number (32) 01407033233 Vendors' system, which is consistent with request.
368018
Vendor's attach No String 123456 Specifies vendor's data package, which is returned
Data Package (128) as it is.
Payment End time_end Yes String 20141030133 Specifies transaction creation time in the format of
Time (14) 525 yyyyMMddHHmmss, such as 20091225091010 for
Dec 25, 2009 09:10:10. For more information, see
Section 4.2 Time Protocol.
Exchange Rate Yes String 650000000 The value is 10 to the 8th power times of the
Rate (16) exchange rate from foreign currency to RMB. For
example, the exchange rate from foreign currency
to RMB is 6.5, the value will be 650000000
Example
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[GOp3TRyMXzbMlkun]]></nonce_str>
<sign><![CDATA[D6C76CB785F07992CDE05494BB7DF7FD]]></sign>
<result_code><![CDATA[SUCCESS]]></result_code>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<trade_type><![CDATA[MICROPAY]]></trade_type>
<bank_type><![CDATA[CCB_DEBIT]]></bank_type>
<coupon_fee>0</coupon_fee>
<fee_type><![CDATA[CNY]]></fee_type>
<transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
<out_trade_no><![CDATA[1415757673]]></out_trade_no>
<attach><![CDATA[Additional Order Description]]></attach>
<time_end><![CDATA[20141111170043]]></time_end>
</xml>
6 Error Codes
Notice: If the returned result is a clear payment failure, please create a new order. If the returned result is an
unknown payment status, please call the query order API and processed the next step based on the query result status.
Please revoke the order if the order status is still unknown after a long time (30s advised).
Name Description Payment Status Reason Solution
SYSTEMERROR API return error Unknown System timed Call the Query Order API
out immediately to check the current
status, and use the returned status to
decide the next steps for processing
the order.
PARAM_ERROR Parameter error Failure Requested Debug your program based on data
parameters are returned by the API
not correct
ORDERPAID Order is paid Failure Duplicate order Confirm whether this order has
number already been processed. If not,
submit it as a new order.
NOAUTH No permissions for Failure Vendors hasnt Apply and receive permission to use
vendors enabled Quick Quick Pay first. For applying for this
Pay payment method, contact customer
service.
AUTHCODEEXPIRE QR Code expired. Failure Payer's bar Cashier should ask payer to refresh
Refresh and try code has the bar code/QR code on WeChat
again. expired and scan the code again. This error is
displayed directly to the cashier.
NOTENOUGH Insufficient balance Failure Payer has Cashiers should inform the payer to
insufficient change their payment bank card and
balance in their scan it again.
payment
Note: In this scenario, the Cashiers
account
point of sale terminal should receive
a message saying "Insufficient
balance in this card. Try another
one" from the Vendors backend.
NOTSUPORTCARD Unsupported card Failure The type of Payer will receive a message in
type card used by WeChat telling them to select
the payer for another card type
their payment is
Note: In this scenario, the cashiers
not supported at
point of sale terminal should receive
the moment
a message saying "Unsupported card
type. Try another one or link a new
card for payment" from the vendors
backend.
ORDERCLOSED Order is closed Failure The order is An exception has occurred with this
closed transaction. Create a new order and
redo the payment process.
ORDERREVERSED Order is cancelled Failure The order is The current order is cancelled.
cancelled Create a new order and redo the
payment process.
BANKERROR Bank system Unknown Bank system Call the Query Order API
exceptions timed out immediately and check the current
transaction status. Process the next
steps based on this status.
USERPAYING Password is Unknown This transaction Wait for 5 seconds and then call the
required as payers requires Query Order API again to check
are performing their payment current transaction status. Process
payment password the next steps based on this status.
AUTH_CODE_ERROR Authorization Failure Requested Each QR code can only be used

parameter error parameters are once. Payer should refresh the QR
not correct code and try again.
AUTH_CODE_INVALID Authorization code Failure The bar or QR Scan bar or QR code on the Quick
checking error code scanned Pay page
by cashiers is
not the one on
the Quick Pay
page
XML_FORMAT_ERROR Invalid XML Failure Invalid XML Check whether XML parameters are
format format in the correct format
REQUIRE_POST_METHOD Use post method Failure Data not Check whether data is submitted via
transferred via POST method
POST method
SIGNERROR Signature error Failure Incorrect Check whether the signature

signature result parameter and method comply with
signature algorithm requirements
LACK_PARAMS Missing parameter Failure Required Check whether all required

parameter is parameters are complete
missing
NOT_UTF8 Invalid coding Failure Specified Use NOT_UTF8 encoding format

format coding format
is not used
BUYER_MISMATCH Incorrect payment Failure Only one payer Check whether the payer is the same
account is allowed to person
pay for one
transaction.
APPID_NOT_EXIST APPID does not Failure No APPID in Check whether provided APPID is
exist this parameter correct
MCHID_NOT_EXIST MCHID does not Failure No MCHID in Check whether provided MCHID is
exist this parameter correct
OUT_TRADE_NO_USED Duplicate vendor Failure The same Check whether the Vendor's order
order number transaction number has already been submitted
can't be or used previously
submitted
repeatedly
APPID_MCHID_NOT_MATCH appid does not Failure appid does not Check whether appid belongs to the
match mch_id match mch_id associated mch_id
6. Query Order API
For more information, see Section 9.2 Query Order.
7. Submit Refund API
For more information, see Section 9.4 Submit Refund.
8. Query Refund API
For more information, see Section 9.5 Query Refund.
9. Cancel Payment API
1 Use Case
When a payment transaction isn't successfully returned or the payment system times out, this API is called to
cancel the transaction. If the Payer fails to pay for the order, the WeChat payment system closes the transaction; if the
Payer has successfully paid, then the WeChat payment system refunds the order.
Note: This API can be called to cancel a transaction made within 7 days after an order is created, while the Submit
Refund API should be used for transactions paid successfully. After a transaction is submitted, Query Order API is
called. When there is no clear query result, Cancel Order API is called.
2 URL
https://api.mch.weixin.qq.com/secapi/pay/reverse
3 Certificate Requirement
This API requires two-way certificates. For more information, see Section 4.3.3 Vendor Certificate.
4 Request Parameters
Official appid Yes String wx88888888 Specifies Official Account ID assigned by WeChat
Account ID (32) 88888888
Vendor ID mch_id Yes String 1900000109 Specifies vendor ID assigned by WeChat Payment
(32)
WeChat transaction_id No String 1217752501 WeChat order number is preferred

Order (32) 2014070332
Number 33368018
Vendor out_trade_no Yes String 1217752501 out_trade_no is an internal order number within the
Order (32) 2014070332 Vendors system.
Number 33368018
transaction_id will be used over out_trade_no if they are
both provided by the vendor.
Random nonce_str Yes String 5K8264ILT 32 characters or fewer or fewer. For more information, see
String (32) KCH16CQ2 Section 4.3.2 Random String Algorithm
502SI8ZNM
TM67VS
Signature sign Yes String C380BEC2B For more information, see Section 4.3.1 Signature
(32) FD727A4B6 Algorithm.
845133519F
3AD6
Sign type sign_type NO String HMAC-SHA Currently HMAC-SHA256 and MD5 are supported, default
(32) 256/MD5 is MD5. This parameter must be submitted if
HMAC-SHA256 is chosen
Example
<xml>
<nonce_str>b7ffb16a7150cf08639db472c5f5bdae</nonce_str>
<sign>9B2EA16C05A5CEF8E53B14D53932D012</sign>
</xml>
5 Return Data
Return Status return_code Yes String SUCCESS SUCCESS or FAIL. Specifies

Code (16) communicating label but not transaction
label. The status of the transaction is
determined by the value of the result_code
field
Return Data return_msg No String Signature If not empty, the returned info is the error
(128) Failure description
Signature Failure
If return_code is SUCCESS, return data will also include the following fields:
Official Account appid Yes String wx888888888 The Official Account ID submitted when
ID (32) 8888888 calling the interface
Vendor ID mch_id Yes String 1900000109 The vendor ID submitted when calling the
(32) interface
Random String nonce_str Yes String 5K8264ILTK 32 characters or fewer

(32) CH16CQ2502
SI8ZNMTM6
7VS
Signature sign Yes String C380BEC2BF For more information, see Section 4.3.1
(32) D727A4B684 Signature
5133519F3A
D6
Service Result result_code Yes String SUCCESS SUCCESS or FAIL

(16)
SUCCESS indicates the order was paid for
successfully and cannot be paid for again.
If the payment is completed, a refund is
initiated.
FAIL refers to exceptions that occur in the

interface. The recall function should be
used to determine whether the order has
been canceled or not;
Error Code err_code No String SYSTEMER For more information, please refer to
(32) ROR Section 5.9.5 Error Code
Error Code err_code_des No String System error The detailed description of error returned.
Description (128)
Recall recall Yes String Y Specifies whether recalling the Cancel

Requirement (1) Order API is required or not, Y means yes
while N means no.
Exchange Rate rate Yes String 650000000 The value is 10 to the 8th power times of
(16) the exchange rate from foreign currency to
RMB. For example, the exchange rate from
foreign currency to RMB is 6.5, the value
will be 650000000
Example:
<xml>
<nonce_str><![CDATA[o5bAKF3o2ypC8hwa]]></nonce_str>
<sign><![CDATA[6F5080EDDD196FFCDE53F786BBB93899]]></sign>
<recall><![CDATA[N]]></recall>
</xml>
6 Error Code
Name Description Reason Solution
SYSTEMERROR API return error System timed out Call the Query Order API immediately to
check the current status, and use the returned
status to decide the next steps for processing
the order
INVALID_TRANSAC Invalid transaction_id Requested parameters are Parameter error. Check transaction_id again.
TIONID not correct
PARAM_ERROR Parameter error Requested parameters are Parameter error. Check parameters again.
not correct
REQUIRE_POST_ME Use POST method Data is not transferred by Check whether data is submitted via POST
THOD POST method method
SIGNERROR Signature error Incorrect signature result Check whether signature parameter and
method comply with signature algorithm
requirements
10. Download Transaction History API
For more information, see Section 9.6 Download Transaction History
11. Report Speed Testing
To improve our payment service, we recommend vendors report payment interface delays to the WeChat payment
backend via the Report Speed Testing API. For more information, see Section 9.8 Report Speed Testing API.
6. NATIVE QUICK PAY PROGRAMMING GUIDE
1. Use Case
The Payer scans a QR Code shown by vendors in the following process.
Step 1 The Vendor creates a QR Code for their products correspondingly based on WeChat payment rules, as
shown in Figure 6.1.
Step 2The Payer scans the QR Code with their WeChat to access the Vendors product data and proceeds with
the transaction, as shown in Figure 6.2. The Payer then makes their payment as instructed, as shown in Figure 6.3.
Figure 6.1 Payment QR Code Figure 6.2 Scan QR Code on WeChat Figure 6.3 Confirm Payment
Step 3The Payer confirms their transaction and enters their payment password, as shown in Figure 6.4.
Step 4: The Payer is prompted of a successful payment after completing their payment, as shown in Figure 6.5.
The Vendor delivers the paid products to the Payer after receiving a notification about the successful payment.
Figure 6.4: Enter Payment Password Figure 6.5 Prompt after Successful
Payment
Offline: Shopin physical stores
Online: JD.com, Ctrip, etc.
3. Process for Vendors
1 Enable Payment Authorization
On the left navigation bar of the WeChat Official Account Admin Platform, choose WeChat Payment
-> Developer Settings () and click Edit (), as shown in Figure 6.6.
Figure 6.6 Parameter Settings of Native Payment

Check the checkbox for Native Payment (Native ) under Official Account Payment and enter the
Vendor's payment backend URL in the Payment Callback URL ( URL) field.
Figure 6.7 Authorization Settings and Payment Callback URL for Native Payment
2 Select a Mode as Required
There are two modes for Quick Pay for vendors to choose from.
Mode 1: The Vendor's backend creates a QR Code based on WeChat payment rule URL containing a fixed
parameter "productid" (specifies product label or order number). After the Payer scans the QR Code, the WeChat
payment system sends the productid and OpenID (Payer's identity) to the Vendors backend. The Vendor's backend
initiates a transaction based on the productid. The WeChat payment system starts the payment process on the Payers'
WeChat.
Mode 2: The Vendor's backend calls the WeChat payment system Unified Order API in order to generate an
advance transaction and creates a QR Code based on the URL returned by the API. The Payer enters their password to
complete the transaction. Note: The advance transaction is valid for 2 hours and cannot be paid for once it expires.
4. Mode 1
Before proceeding with this mode, the Vendor needs to set their payment callback URL on the WeChat Official
Account Admin Platform. This URL is used to receive productid and the payers OpenID via a callback by the WeChat
payment system after the Payer scans a QR Code. For more information, see Section 6.3.1 Enable Payment
Authorization.
1 Sequence Chart
Figure 6.8 Native Payment API of Mode 1

Service steps:
1) The Vendor's backend creates a QR Code based on the format specified by WeChat payment rules (for more
information, see Section 6.4.2 QR Code Generation Rules) and displays it to the Payer to be scanned.
2) Payer opens Scan QR Code in WeChat to scan the QR Code. The scanned data is sent to the WeChat
payment system from the Payer's WeChat.
3) After receiving this request from the Payers WeChat, the WeChat payment system calls the payment
callback URL on the Vendor's backend, containing productid and the users OpenID. The Vendor's system is
required to return prepay_id Unified
( Order APIreturns the transaction session tag which is valid for up to
2 hours) before the Payer can make a payment.
4) Vendor's backend receives the callback request from the WeChat payment system and creates an order in the
Vendor's backend based on productid.
5) Vendor's backend calls the WeChat payment systemUnified Order APIand requests a transaction session
tag.
6) WeChat payment system creates an advance transaction based on the above request and returns the
transaction session tag prepay_id.
7) Vendor's backend receives the transaction session tag prepay_id.
8) Vendor's backend returns prepay_id to WeChat payment system.
9) WeChat payment system initiates an authorization for payment on the Payers WeChat based on prepay_id.
10) The Payer enters their payment password and confirms payment on WeChat. The payment authorization is
submitted from WeChat to the WeChat payment system.
11) WeChat payment system verifies and makes deductions to complete the transaction.
12) WeChat payment system returns the transaction result to the Payer's WeChat via SMS and prompts after the
payment is done. The Payer can see the payment result in WeChat.
13) WeChat payment system sends an asynchronous message to inform the Vendor's backend of the transaction
result. The Vendor's backend replies to the WeChat payment system that the payment is completed.
14) The Vendor backend polls the Query Order API if no payment message is received.
15) The Vendor confirms the order and delivers products to the Payer.
2 QR Code Generation Rules
The content of a QR Code is a URL in the following format:
weixin://wxpay/bizpayurl?sign=XXXXX&appid=XXXXX&mch_id=XXXXX&product_id=XXXXXX&time_
stamp=XXXXXX&nonce_str=XXXXX
where XXXXX are the required fields for the Vendor. The Vendor should create a QR Code based on these rules.
This format is required if the QR Code is to be displayed properly. A Vendor can call a third plug-in to create the QR
Code. The following are parameter specifications.
Table 6.1 Parameters for generating QR Code
Official appid Yes String(32) wx88888888888888 Specifies Official Account ID assigned by

Account ID 88 WeChat
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID assigned by WeChat

Payment
Timestamp time_stamp Yes String(10) 1414488825 Specifies the current system time. For more
information, see Time Protocol in Section
4.2 Parameter Specifications.
Random nonce_str Yes String(32) 5K8264ILTKCH16 32 characters or fewer. For more

String CQ2502SI8ZNMT information, see Section 4.3.2 Random
M67VS String Algorithm.
Product ID product_id Yes String(32) 88888 Specifies product ID or order ID defined by

the Vendor
Signature sign Yes String(32) C380BEC2BFD727 Specifies a signature. For more

A4B6845133519F3 information, see Section 4.3.1 Signature
AD6 Algorithm.
Example
weixin://wxpay/bizpayurl?appid=wx2421b1c4370ec43b&mch_id=10000100&nonce_str=f6808210402125e30663234f94c87a8c&product_id=1&time
_stamp=1415949957&sign=512F68131DD251DA4A45DA79CC7EFE9D
3 Payment Callback URL
The Vendor should provide a payment callback URL (for more information, see Section 6.3.1 Enable Payment
Authorization). The URL is used to receive data sent by the WeChat payment system after the Payer scans the QR
Code. The Vendors backend then creates a payment order based on the data, and calls the Unified Order API to
submit the payment transaction.
1. Input Parameters
Table 6.2 Input Parameters
Official appid Yes String wx8888888888888888 Specifies Official Account ID assigned by

Account ID (32) WeChat
User Tag openid Yes String o8GeHuLAsgefS_80ex Specifies the user id of the Payer provided by
(128) Er1cTqekUs the WeChat system in OpenID format and is
a unique tag unique to each appid instance
Vendor ID mch_id Yes String 1900000109 Specifies vendor ID assigned by WeChat

(32) Payment
Follows is_subscribe Yes String Y Specifies whether the Payer follows the
Official (1) associated official account or not, with Y
Account or not meaning follows and N meaning not
follows.
Random String nonce_str Yes String 5K8264ILTKCH16CQ2 32 characters or fewer or fewer. For more
(32) 502SI8ZNMTM67VS information, see Section 4.3.2 Random
String Algorithm.
Product ID product_id Yes String 88888 Specifies product ID or order ID defined by

(32) the Vendor
Signature sign Yes String C380BEC2BFD727A4 Specifies a signature. For more information,
(32) B6845133519F3AD6 see Section 4.3.1 Signature Algorithm.
2. Output Parameters
Table 6.3 Output Parameters
Return Status return_code Yes String(1 SUCCESS SUCCESS or FAIL. Specifies

Code 6) communicating label but not
transaction label. The status of the
transaction is determined by the value
of the result_code field
Return Data return_msg No String(1 Signature failure If not empty, this is the error
28) description
Signature failure
Official appid Yes String(3 wx8888888888888888 Specifies Official Account ID assigned

Account ID 2) by WeChat
String(3 1900000109 Specifies vendor ID assigned by

Vendor ID mch_id Yes
2) WeChat Payment
Random String nonce_str Yes String(3 5K8264ILTKCH16CQ25
32 characters or fewer
2) 02SI8ZNMTM67VS
Advance prepay_id Yes String(6 wx201410272009395522 Specifies the advance transaction ID

Transaction ID 4) 657a690389285100 created by calling the Unified Order
API.
Service Result result_code Yes String(1 SUCCESS Set to SUCCESS or FAIL

6)
Error err_code_des No String(1 When result_code is FAIL, the Vendor

Description 28) should display the error information to
the Payer
Signature sign Yes String(3 C380BEC2BFD727A4B6 Specifies a signature. For more

2) 845133519F3AD6 information, see Section 4.3.1
Signature Algorithm.
5. Mode 2
Compared with Mode 1, Mode 2 is a simpler process. It doesnt require use of the callback payment URL. In
Mode 2, the Vendor's backend calls the Unified Order API and the WeChat payment system returns code_url to the
Vendor's backend to create a QR Code. The Payer scans the QR Code in WeChat to initiate payment. Note: code_url is
valid for up to 2 hours. The Payer can't scan the QR Code to pay again once it has expired.
1 Sequence Chart
Figure 6.9 Native Payment API of Mode 2
Service steps:
1) The Vendor's backend creates an order based on the product selected by the Payer.
2) The Payer confirms payment and the Vendor calls the WeChat payment system Unified Order API to
create an advance payment transaction.
3) WeChat payment system creates an advance transaction bill upon receiving this request, and returns
code_url.
4) The Vendors backend creates a QR Code based on code_url.

5) The Payer opens Scan QR Code in WeChat and scans the QR code. The scanned data is sent to the WeChat
payment system from the Payer's WeChat.
6) The WeChat payment system receives the request from WeChat and verifies the URL. If the URL is verified
to be valid, payment is initiated and requires the Payer's authorization.
7) The Payer enters their payment password and confirms payment in WeChat. The payment authorization is
submitted to the WeChat payment system from WeChat.
8) The WeChat payment system completes the transaction based on the Payer's authorization.
9) The WeChat payment system returns the transaction result to the Payer's WeChat via SMS after the payment
is done. The Payer can view the payment result in their WeChat.
10) The WeChat payment system sends an asynchronous message to inform the Vendor's backend of the
payment result. Then Vendor's backend replies to inform the WeChat payment system the payment is
completed.
11) The Vendors backend polls the Query Order API if no payment message is received.
12) The Vendor confirms the order and delivers products to the Payer.
2 QR Code Generation Rules
The URL should follow the format weixin://wxpay/bizpayurl?sr=XXXXX. The Vendor can use a third plug-in to
create a QR Code from code_url. If printed on the checkout bill, this QR Code is more readable as the URL is shorter.
Take the QR Code created from weixin://wxpay/s/An4baqw as an example. We can see a clearer pattern in Figure
6.10.
Figure 6.10 QR Code Example in Native Payment API using Mode 2
6. Unified Order API
NATIVE is required for the field of transaction type (trade_type)

For more information, see Section 9.1 Unified Order.
7. Query Order API
8. Close Order API
For more information, see Section 9.3 Close Order.
10. Query Order API
For more information, see Section 9.6 Download Transaction History
To improve our payment service, we recommend vendors report payment interface delays to the WeChat payment
backend via the Report Speed Testing API. For more information, see Section 9.8, Report Speed Testing API.
13. Learn More about QR Codes
Relevant links:
http://www.thonky.com/qr-code-tutorial/
http://coolshell.cn/articles/10590.html
7. IN-APP WEB-BASED PAYMENT
1. Use Case
The Payer opens the vendor's HTML5 page in WeChat by clicking messages or scanning a related QR Code, and
enters WeChat payment to complete their transaction.
Step 1: The Vendor sends a rich media message or a self-defined menu to the Payer, as shown in Figure 7.1.
Step 2: The Payer clicks the message or selects a menu option to enter the Vendor's page and selects product(s).
Figure 7.1 Vendor's Rich Media Figure 7.2 Vendor's Product Page
Message and Self-Defined Menu
Step 3: The Payer calls WeChat payment and enters their payment password as prompted, as shown in Figure 7.3.
Step 4: The payment is completed after the password has been verified successfully. The Vendor's backend
receives the payment result notification, as shown in Figure 7.4.
Figure 7.3: Enter Payment Password Figure 7.4 Prompt after Successful
Payment
Step 5: The Vendor returns a page displaying that the payment was successful. This page is designed by the
Vendor, as shown in Figure 7.5.
Step 6: The Vendor's official account sends a message to inform the Payer in WeChat of delivery, as shown in
Figure 7.6. This step is optional.
Figure 7.5 Return Vendor's Page Figure 7.6 Inform Payer of Delivery
Notes: Vendors can convert their product URL into a QR Code so that payers can scan them to buy and pay
quickly.
Detailed steps are as follows:
Please carefully read the instructions below before designing product pages:
(1) The Payer opens the Vendor's product page and confirms a transaction. The getBrandWCPayRequest API is
called via JavaScript on the page to initiate a WeChat payment request. This initiates the Payers payment process.
(2) After the Payer clicks to pay successfully and completes the transaction, the Vendors front-end receives a
value returned within the JavaScript. The Vendor can then directly redirect to a static page indicating successful
payment.
(3) The Vendor's backend receives a callback call from the WeChat Open Platform, indicating a result reporting
the transaction was paid successfully.
Note:
The triggering times of steps (2) and (3) are not strictly in order. The returned value of the JSAPI is the event that
should trigger the Vendor's page redirect. However, the Vendors backend should process the payment result data only
after a successful payment call is received from the WeChat payment system.
Offline: New-version Ubox vending machines, etc.
Online: JD.com, Yixun Official Account, etc.

3. Programing Instructions
1 Set Testing Directory
You can configure a testing directory on the WeChat Official Account Admin Platform, as shown in Figure 7.7. In
the Payment Testing section, you can configure a testing directory in the Testing Directory () field and
add a testers WeChat IDs to the white list. Ensure that the testing directory is matches the directory for initiating
payment, otherwise the payment can't be performed later. In addition, this payment URL shall be sent to the
corresponding official account session so as to start the payment testing properly.
Figure 7.7 In-App Web-based Payment Settings
2 Set Official Payment Directory
You can edit the above settings after configurations, as shown in Figure 7.8. You can enable the JSAPI by
checking the checkbox and setting the payment authorization directory. Ensure that the directory matches the directory
for initiating payment, as payment can't be started from a sub-directory.
Figure 7.8 In-App Web-based Payment Authorization Directory Settings
4. Sequence Chart
Figure 7.9 In-App Web-based Payment Sequence Chart
How the Vendor's system interacts with the WeChat payment system:
1. The Vendor's server calls the Unified Order API to create an order. For more information, see Section
9.1 Unified Order.
2. The Vendor's server receives payment notifications. For more information, see Section 9.7 General
Payment Result Notification.
3. The Vendor's server queries payment result. For more information, see Section 9.2 Query Order.
5. WeChat Version Requirement
WeChat supports the payment feature in versions 5.0 and greater, so payers using versions prior to version 5.0
can't access WeChat payment. As a consequence, we suggest the Vendor confirm the Payer's version via the user agent
string before using WeChat payment features. Using an iPhone WeChat client as an example, the Vendor can check the
Payer's WeChat version via user agent below:
"Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X) AppleWebKit/534.46(KHTML,like Geocko)

Mobile/9B206 MicroMessenger/5.0"
where 5.0 indicates the Payer's WeChat version. Vendors can parse the above HTTP header to check whether the
WeChat version is greater than or equal to 5.0.
6. WeChat Security Payment Subtitle in Page Header
For transaction security reasons, the Payer can see WeChat Security Payment subtitle in the page header of their
payment page in WeChat. We suggest vendors use this subtitle for their WeChat payment transaction.
Figure 7.10 WeChat Security Payment Subtitle
To display the subtitle, the Vendors should add "showwxpaytitle=1" to the end of the original URL. After doing
so, their page will show the "WeChat Security Payment" subtitle. For example, for the original URL
(http://weixin.qq.com), the Vendor can change it to the one with the subtitle (http://weixin.qq.com?showwxpaytitle=1).
As a result, when the Payer opens http://weixin.qq.com in WeChat, they wont see the subtitle. However, if they
go with http://weixin.qq.com?showwxpaytitle=1, the subtitle will be displayed in the header of their opened page.
7. Call Payment API from HTML5 Websites
The JSAPI is called when the Payer opens an HTML5 website with a WeChat-supported browser. The input and
output API data is in JSON format.
Notes: WeixinJSBridge built-in objects are invalid in other browsers and parameter names in the list are
case-sensitive.
For "getBrandWCPayRequest" parameters and return value definitions, see Table 7.1. For return value description,
see Table 7.2.
Table 7.1 HTML5-based API Parameters
Official Account appId Yes String(16) wx8888888888 This ID is issued after vendors apply for
ID 888888 official account supporting WeChat
payment.
Timestamp timeStamp Yes String(32) 1414561699 Specifies the current time. For more
information, see Timestamp in Section
4.2 Parameter Specifications.
Random String nonceStr Yes String(32) 5K8264ILTKC 32 characters or fewer. For more
H16CQ2502SI8 information, see Section 4.3.2 Random
ZNMTM67VS String Algorithm.
Order Extension package Yes String(128 prepay_id=1234 Specifies the parameter value (prepay_id)
String ) 56789 returned by the Unified Order API. The
submission format is "prepay_id=***".
Signature paySign Yes String(64) C380BEC2BFD Specifies a signature. For more

727A4B684513 information, see Section 4.3.1 Signature
3519F3AD6 Algorithm.
Sign type signType Yes String(32) MD5 Currently HMAC-SHA256 and MD5 are
supported
Table 7.2 Web-based Payment API Return Data Description
Return Value Description

get_brand_wcpay_request:ok Payment successful
get_brand_wcpay_request:cancel Payment canceled
get_brand_wcpay_request:fail Payment failed
"get_brand_wcpay_request:ok" is returned by the JSAPI only when the Payer completes the payment. For
front-end logic, "get_brand_wcpay_request:cancel" or "get_brand_wcpay_request:fail" can be handled as payment
exceptions.
Example:
function onBridgeReady(){
WeixinJSBridge.invoke(
'getBrandWCPayRequest', {
"appId" : "wx2421b1c4370ec43b", //Official Account name transferred by vendors
"timeStamp":" 1395712654", //Timestamp since 1.1.1970 UTC
"nonceStr" : "e61463f8efa94090b1f366cccfbbb444", //Random string
"package" : "prepay_id=u802345jgfjsdfgsdg888",
"signType" : "MD5", //WeChat signature type:
"paySign" : "70EA570631E4BB79628FBCA90534C63FF7FADD89" //WeChat signature
},
function(res){
if(res.err_msg == "get_brand_wcpay_request:ok" ) {} // Use the above method to determine values returned to the front-end. Please note
that "res.err_msg" returns"ok" after a successful payment. However, WeChat doesn't guarantee its reliability.
}
);
}
if (typeof WeixinJSBridge == "undefined"){
if( document.addEventListener ){
document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
}else if (document.attachEvent){
document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
}
}else{
onBridgeReady();
}
JSAPI is required for the field of transaction type (trade_type)
For more information, see Section 9.1 Unified Order.
9. Query Order API
For more information, see Section 9.2Query Order.
10. Close Order API
12. Query Refund API
13. Download Transaction HistoryTransaction History API
For more information, see Section 9.6 Download Transaction History.
8. IN-APP PAYMENT
1. Use Case
This method is applicable to WeChat payments integrated by vendors into mobile apps.
The Vendor's app calls the SDK provided by WeChat to use the WeChat payment module, and redirects to
WeChat to pay a transaction. After completing the transaction, the WeChat reopens the vendor's app and a page
containing the payment result is displayed.
At present, WeChat supports iOS, Android and Windows Phone.
Detailed steps are as below:

Step 1: Payer enters the Vendor's app, selects products and confirms the transaction to proceed with payment. The
Vendors service backend creates a payment order and signs it, and relevant data is transferred to the Vendor's app, as
shown in Figure 8.1.
Step 2: The Payer clicks to confirm the payment and which opens the payment page within WeChat to pay for the
order, as shown in Figure 8.2.
Step 3: The Payer confirms the payee and the amount, and clicks to pay. A page is then displayed that prompts the
Payer to enter their payment password. The Payer can select to pay with a bank card or via Balance, as shown in Figure
8.3.
Figure 8.1 Example of Vendor's app Figure 8.2 Redirect to the payment Figure 8.3: Payer enters their
screen page within WeChat payment password
Step 4: The Payer enters their payment password to complete the transaction. If paid successfully, a page
containing the payment result is displayed on the payer's WeChat, as shown in Figure 8.4.
Step 5: The page reopens the Vendor's app, which will show the order process result based on payment results.
Figure 8.4 Prompt after successful Figure 8.5 Prompt for reopening the
payment vendor's app
This payment method is now supported on the JD and Yixun apps.
3. Service process
This payment method is explained below. The Unified Order API, Query Order API, and accepting order
notifications require signatures, which are created on the Vendor's service backend, as shown in Figure 8.6.
Figure 8.6 In-app payment sequence chart

Below shows how the vendor's backend interacts with the WeChat payment system:
Step 1: Payer selects products within the Vendor's app, submits the order, and chooses WeChat payment.
Step 2: The Vendor receives payer's payment transaction and calls the Unified Order API. For more information,
see Section 9.1Unified Order.
Step 3: The Unified Order API returns a normal prepay_id, and creates a signature based on the signature rules.
The relevant data is transferred to the Vendor's app. Fields contained in the signature include cappId, partnerId,
prepayId, nonceStr, timeStamp, and package. Note: the value format of package is Sign=WXPay
Step 4: The Vendor's app uses the SDK to open WeChat payment within WeChat. For more information, see
Section 8.5App-based Development Guide.
Step 5: The Vendor's backend receives payment notifications. For more information, see Section 9.7 General
Payment Result Notification.
Step 6: The Vendor's backend queries the payment result. For more information, see Section 9.2Query Order.
4. Learn More about this API
https://open.weixin.qq.com/zh_CN/htmledition/res/dev/document/sdk/ios/index.html
5. App-based Development Guide
1 Instructions for iOS
We will use Xcode10.0 running an iOS 7.0 environment as an example to illustrate the process.
1) APPID for Project Settings
After the Vendor has successfully applied for an App in the WeChat Open Platform, the Platform will provide an
unique APPID to the Vendor. When creating a project in Xcode, the developer should enter the APPID value in the
URL Schemes field, as marked in red in Figure 8.7.
Figure 8.7
2) APPID for Registration
The WeChat SDK lib and head files should be imported into the Xcode project. Before calling the API, you
should register your APPID with WeChat, as shown below:
[WXApi registerApp:@"wxd930ea5d5a258f4f" withDescription:@"demo 2.0"];
3) Call Payment
The Vendor's server calls the Unified Order API (for more information, see Section 9.1 Unified Order) to create
an advance transaction. After obtaining prepay_id and signing relevant parameters, the advance transaction data is
transferred to the App to start a payment. See below for an example on how to do this:
PayReq *request = [[[PayReq alloc] init] autorelease];

request.partnerId = @"10000100";
request.prepayId= @"1101000000140415649af9fc314aa427";
request.package = @"Sign=WXPay";
request.nonceStr= @"a462b76e7436e98e0ed6e13c64b4fd1c";
request.timeStamp= @"1397527777";
request.sign= @"582282d72dd2b03ad892830965f428cb16e7a256";
[WXApi safeSendReq:request];
4) Payment Result Callback
As shown in the sample included in the SDK, onResp() can be added to WXPayEntryActivity. After completing
payment, WeChat will be redirected to the Vendor's app and do a callback using onResp(). The Developer receives
notifications in this function and determines the returned error code if necessary. If the payment is successful, the
payment result shall be queried from the WeChat payment system and shown to Payer. The payment result is subject to
the payment notifications from the WeChat payment system and the result returned to the Payer after querying the API.
See below for an example on how to do this:
- (void)onResp:(BaseResp *)resp {
if ([resp isKindOfClass:[PayResp class]]) {
PayResp *response = (PayResp *)resp;
switch (response.errCode) {
case WXSuccess:
//Prompt of successful payment according to server-based query result or API returned data
NSlog(@"Payment Successful");
break;
default:
NSlog(@"Payment Failed retcode=%d",resp.errCode);
break;
}
}
}
errCode value list:
Name Description Solution
0 Success Displays the success page
-1 Error This may be caused by signature error, unregistered APPID, incorrect APPID in project settings,
unmatched APPID in the registration and project settings, or other exceptions.
-2 Canceled by This occurs when the Payer cancels payment and returns to the App. In this case, no further steps
user are required.
2 Instructions for Android
1) Backend Settings
After the Vendor has successfully applied for an App in the WeChat Open Platform, the Platform will provide an
unique APPID to the Vendor. For payment security reasons, the Vendor's app package name and signature must match
in the Platform. Only when these are configured properly can payment be initiated. This can be done in App Platform
()->Android App (Android ) on the WeChat Open Platform, as marked in red in Figure 8.8.
Figure 8.8
The App package name is the same as the one set in the configuration file "AndroidManifest.xml" of the apps
project settings. For an example, look at the package name "net.sourceforge.simcpux" in Figure 8.9.
The App signature is the keystore used for compiling according to project's app package name, which should be a
32-bit md5 string generated by a signature tool. If developers install the signature tool on a testing phone, they can run
it to generate the apps signature string, as shown in the strings in green in Figure 8.9. Download a signature tool at the
following URL: https://open.weixin.qq.com/zh_CN/htmledition/res/dev/download/sdk/Gen_Signature_Android.apk
Figure 8.9
2) APPID for Registration
The WeChat JAR package should be imported into the App project. Before calling the API, you need to register
your APPID with WeChat, as shown below:
Before calling the API, you should register your APPID with WeChat, as shown below:
final IWXAPI msgApi = WXAPIFactory.createWXAPI(context, null);
// Register this app with WeChat
msgApi.registerApp("wxd930ea5d5a258f4f");
3) Call Payment
The Vendor's server calls the Unified Order API (for more information, see Section 9.1 Unified Order) to create
an advance transaction. After obtaining prepay_id and signing relevant parameters, the advance transaction data is
transferred to the App to start a payment. See below for an example of how to do this:
IWXAPI api;
PayReq request = new PayReq();
request. appId = "wxd930ea5d5a258f4f";
request. partnerId = "1900000109";
request.prepayId= "1101000000140415649af9fc314aa427",;
request. packageValue = "Sign=WXPay";
request.nonceStr= "1101000000140429eb40476f8896f4c9";
request.timeStamp= "1398746574";
request.sign= "7ffecb600d7157c5aa49810d2d8f28bc2811827b";
api.sendReq(req);
4) Payment Result Callback
As shown in the sample included in the SDK, onResp() can be added to WXPayEntryActivity. After completing
payment, WeChat will be redirected to Vendor's app and do a callback using onResp(). The Developer receives
notifications in this function and determines the returned error code if necessary. If the payment is successful, the
payment result shall be queried from the WeChat payment system and shown to Payer. The payment result is subject to
the payment notifications from the WeChat payment system and the result returned to the Payer after querying the API.
See below for an example on how to do so:
public void onResp(BaseResp resp) {

if (resp.getType() == ConstantsAPI.COMMAND_PAY_BY_WX) {
Log.d(TAG, "onPayFinish, errCode = " + resp.errCode);
AlertDialog.Builder builder = new AlertDialog.Builder(this);
builder.setTitle(R.string.app_tip);
}
}
errCode value list:
-1 Error This may be caused by signature error, unregistered APPID, incorrect APPID in
project settings, unmatched APPID in the registration and project settings, or
other exceptions.
-2 Canceled by This happens occurs when the Payer cancels payment and returns to App. In this
users case, no further steps are required.
APP is required for the field of transaction type (trade_type)
For more information, see Section 9.1 Unfied Order.
7. Query Order API
8. Close Order API
10. Query Refund API

For more information, see Section 9.6 Download Transaction History.
9. PUBLIC API
The Public API serves as the common API interface to be called to access a variety of supplemental functions.
Vendors can choose to integrate these functions based on their needs. The Public API includes the Unified Order,
General Notification, Query Order, Close Order, Submit Refund, Refund Query, Download Transaction History and
Short URL Conversion functions, which are elaborated in the following subsections.
1. Unified Order
1 Use Case
For scenarios other than the Quick Pay method, the Vendors backend calls this API to create an advance
transaction in the WeChat payment service backend, and initiates the payment process via payment by QR Code.
JSAPI, App and other payment methods after the order is submitted successfully.
2 URL
URL: https://api.mch.weixin.qq.com/pay/unifiedorder
Official appid Yes String(32) wx88888888888888 Specifies Official Account ID assigned

Account ID 88 by WeChat
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID assigned by WeChat

Payment
Device ID device_info No String(32) 013467007045764 Specifies the terminal device ID assigned

by WeChat Payment. This field is defined
by the Vendor.
Note: If the payment is performed based

on PC web page or WeChat Web-based
page, please submit the field value as
WEB.
Random nonce_str Yes String(32) 5K8264ILTKCH16 32 characters or fewer. For more

String CQ2502SI8ZNMT information, see Section 4.3.2 Random

AD6 Algorithm.
Sign type sign_type NO String(32) HMAC-SHA256 Currently HMAC-SHA256 and MD5 are
supported, default is MD5. This field is
only required when sign_type is
HMAC-SHA256.
Item body Yes String(128) iPad Mini in white Short description of item(s) to be
Description with 16G memory purchased for the Payer
Item Details detail No String(8192 iPad Mini in white Displays detailed item list
) with 16G memory
Additional attach No String(127) Additional Allow vendors an additional field to be

Data description returned in the payment notification after
submitting a payment to the Query Order
API
Vendor Order out_trade_no Yes String(32) 1217752501201407 32 alphanumeric characters or less. For
Number 033233368018 more information, see Section 4.2
Vendor's Order Number.
Currency fee_type Yes String(16) GBP ISO-4217 standard compliant and be

Type described by three characters based code.
For more information, see Section 4.2
Currency Type.
Total Amount total_fee Yes Int 888 Specifies the total order amount. The
units are expressed in cents and must be
an integer. For more information, see
Section 4.2 Payment Amount.
Terminal IP spbill_create_i Yes String(16) 8.8.8.8 For Native Quick Pay, specifies the
p machine IP that calls WeChat Payment
API. While for In-App Web-based
Payment or In-App Payment, specifies
the client terminal IP
Transaction time_start No String(14) 20091225091010 Specifies the transaction creation time in

Start Time the format yyyyMMddHHmmss, such as
20091225091010 for Dec 25, 2009
09:10:10 (UTC+08). For more
information, see Section4.2 Time
Protocol.
Transaction time_expire No String(14) 20091227091010 Specifies the transaction end time in the
End Time format yyyyMMddHHmmss, such as
20091227091010 for Dec 27, 2009
09:10:10 (UTC+08). The shortest
transaction invalid time should be larger
than 5m. For more information, see
Section4.2 Time Protocol.
Item Label goods_tag No String(32) WXG Specifies the label of goods, which is a
parameter in the coupon feature for
businesses. For more information, see
Section 10 Mobile Coupon.
Notification notify_url Yes String(256) http://www.baidu.co Specifies the callback address for
URL m/ receiving WeChat payment notifications
Transaction trade_type Yes String(16) JSAPI Set to JSAPI, NATIVE, or APP

Type
Product ID product_id No 1223541321407035 This field is only required when

String(32) 6458058 trade_type is NATIVE. This ID contains
the product ID as set by the Vendor.
Specified limit_pay No no_credit

no_credit: Using credit card for payment
Payment String(32)
is not allowed
Method
User Tag openid No oUpF8uMuAJO_M This field is only required when

String(128) 2pxb1Q9zNjWeS6o trade_type is JSAPI. It is the only user
identification under the current appid
Example
<xml>
<attach>Payment Testing</attach>
<body>JSAPI Payment Testing</body>
<nonce_str>1add1a30ac87aa2db72f57a2375d8fec</nonce_str>
<notify_url>http://wxpay.weixin.qq.com/pub_v2/pay/notify.v2.php</notify_url>
<openid>oUpF8uMuAJO_M2pxb1Q9zNjWeS6o</openid>
<spbill_create_ip>14.23.150.211</spbill_create_ip>
<trade_type>JSAPI</trade_type>
<sign>0CB01533B8C1EF103065174F50BCA001</sign>
</xml>
Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.
5 Return Data
Return Status return_code Yes String(16) SUCCESS SUCCESS or FAIL

Code
Specifies communicating label instead of
transaction label. The status of the transaction is
determined by the value of the result_code field.
Return Data return_msg No String(128) Signature failure If not empty, the returned info is the error
description.
Signature failure
Field Name ID Requi Type Example Description

red
Official Account appid Yes String(32) wx88888888888 The Official Account ID submitted when calling
ID 88888 the interface
Vendor ID mch_id Yes String(32) 1900000109 The Vendor ID submitted when calling the
interface
Device ID device_info No String(32) 0134670070457 The Device ID submitted when calling the
64 interface
Random String nonce_str Yes String(32) 5K8264ILTKCH 32 characters or fewer

16CQ2502SI8Z
NMTM67VS
Signature sign Yes String(32) C380BEC2BFD Signature returned. For more information, see
519F3AD6
Service Result result_code Yes String(16) SUCCESS SUCCESS or FAIL
Error Code err_code No String(32) SYSTEMERRO For more information, see Section 5.5.6 Error
R Code
Error Code err_code_des No String(128) System error Describes result data

Description
If both return_code and result_code are SUCCESS, return data will also include the following fields:
Field Name ID Requi Type Example Description

red
Transaction Type trade_type Yes String(16) JSAPI The transaction type submitted. The value could
be JSAPI, NATIVE, or APP
Advance prepay_id Yes String(64) wx20141027200 Specifies the advance transaction ID created by
Transaction ID 9395522657a69 WeChat. It is used to call the Query Order API
0389285100 later. Validity is 2 hours.
QR Code URL code_url No String(64) URl This field is returned when trade_type is
NATIVE. This parameter should be used to
weixin://wxpay/s
create a QR Code that is displayed to the Payer
/An4baqw
later.
Example
<xml>
<nonce_str><![CDATA[IITRi8Iabbblz1Jc]]></nonce_str>
<sign><![CDATA[7921E432F65EB8ED0CE9755F0E86D72F]]></sign>
<prepay_id><![CDATA[wx201411101639507cbf6ffd8b0779950874]]></prepay_id>
<trade_type><![CDATA[JSAPI]]></trade_type>
</xml>
6 Error Code
NOAUTH Vendor doesnt have Vendors hasnt enabled The Vendor should apply for permission to use
permission to use this authorization for this API this API
API
NOTENOUGH Insufficient balance The Payer has an insufficient Inform the Payer to add funds to their account
balance in their payment card or to try another payment card
ORDERPAID Order is paid Order is already paid and The order has already been paid and no further
cannot be paid for again action is required
ORDERCLOSED Order is closed The current order is closed The current order has already been closed. The
and cannot be paid for again Payer should be told to create a new order.
SYSTEMERROR System error System has timed out A system exception has occurred. Call the API
again using the same parameters.
APPID_NOT_EXI APPID DOES NOT Provided APPID in this Check whether provided APPID is correct
ST EXIST parameter does not exist
MCHID_NOT_EXI MCHID DOES NOT Provided MCHID in this Check whether provided MCHID is correct
ST EXIST parameter does not exist
APPID_MCHID_N appid does not match appid does not match mch_id Check whether appid belongs to the associated
OT_MATCH mch_id mch_id
LACK_PARAMS Missing parameter Required parameter is Check whether parameter is provided

missing
OUT_TRADE_NO Duplicate vendor The same transaction can't be Check whether vendor's order number has
_USED order number submitted repeatedly already been submitted or used previously
requirements
XML_FORMAT_E INVALID XML INVALID XML FORMAT Check whether XML parameters are in correct
RROR FORMAT format
REQUIRE_POST_ Use post method Data is not transferred by post Check whether data is submitted via POST
METHOD method
POST_DATA_EM post data is empty post data cant be empty Check whether post data is empty
PTY
NOT_UTF8 Invalid coding format Specified coding format is not Use NOT_UTF8 coding format
used
2. Query Order
1 Use Case
This API allows inquiry of all payment orders made from WeChat. After receiving a status code using this API,
vendors can proceed with the next step in service logic. The following are situations when to use the Query Order API:
1. The Vendor doesnt receive any payment due to an exception in the Vendor's backend, network or
server;
2. A system error or unknown transaction status is returned after calling the payment interface;
3. USERPAYING status is returned after calling the Quick Pay API;
4. To confirm payment status before calling the Close Order API or Revoke Order API;
2 URL
https://api.mch.weixin.qq.com/pay/orderquery
Official Account appid Yes String wx888888888 Specifies Official Account ID assigned by WeChat
ID (32) 8888888
Vendor ID mch_id Yes String 1900000109 Specifies vendor ID assigned by WeChat Payment
(32)
WeChat Order transaction_id String 013467007045

WeChat order number is preferred
Number (32) 764
Choose one
Vendor Order out_trade_no to submit String 121775250120 Specifies an internal order number created by the
Number (32) 140703323336 Vendor's system. This field is required when
8018 transaction_id is not provided.
Random String nonce_str Yes String C380BEC2BF 32 characters or fewer. For more information, see
(32) D727A4B6845 Section 4.3.2 Random String Algorithm
133519F3AD6
Signature sign Yes String 5K8264ILTK Specifies a signature. For more information, see Section
(32) CH16CQ2502 4.3.1 Signature Algorithm.
SI8ZNMTM67
VS
Sign type sign_type NO String HMAC-SHA2 Currently support HMAC-SHA256 and MD5, default is
(32) 56 MD5. This field is only required when sign_type is
HMAC-SHA256
Example
<xml>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<transaction_id>1008450740201411110005820873</transaction_id>
<sign>FDD167FAA73459FD921B144BAF4F4CA2</sign>
</xml>
5 Return Data
Field Name ID Required Type Exampl Description

e
Return Status return_code Yes String(16) SUCCE SUCCESS or FAIL
Code SS
Specifies communicating label instead of transaction
label. The status of a transaction is determined by the
value of trade_state.
Return Data return_msg No String(128 Signatur If not empty, this is the error description
) e failure
Signature failure
Official Account appid Yes String wx888888888 The Official Account ID submitted when calling the
ID (32) 8888888 interface
Vendor ID mch_id Yes String 1900000109 The Vendor ID submitted when calling the interface
(32)
Random String nonce_str Yes String 5K8264ILTKC 32 characters or fewer

(32) H16CQ2502SI
8ZNMTM67V
S
Signature sign Yes String C380BEC2BF Signature returned. For more information, see Section
(32) D727A4B6845 4.3.1 Signature Algorithm.
133519F3AD6
Service Result result_code Yes String SUCCESS SUCCESS or FAIL

(16)
Error Code err_code No String SYSTEMERR For more information, see Section 5.5.6 Error Code.
(32) OR
Error Code err_code_des No String System error Describes result data

Description (128)
If both return_code and result_code are SUCCESS, return data will also include the following fields:
Device ID device_info No String(3 013467007045 Specifies the terminal device ID assigned by WeChat
2) 764 Payment
User Tag openid Yes String(1 wxd930ea5d5a Specifies the user id of the Payer provided by the
28) 258f4f WeChat system in OpenID format unique to each
appid instance
Follows is_subscribe No String(1) Y Specifies whether the payer follows the associated
Official official account or not, with Y meaning follows and
Account or N meaning not follows.
not
Transaction trade_type Yes String(1 JSAPI Set to JSAPI, NATIVE, MICROPAY or APP
Type 6)
Transaction trade_state Yes String(3 SUCCESS SUCCESS: Payment successful

Status 2)
REFUND: Order to be refunded
NOTPAY: Order not paid
CLOSED: Order closed
REVOKED: Order revoked
USERPAYING: Awaiting user to pay
PAYERROR: Payment failed (payment status failed to

be returned by bank or other reasons)
Payment Bank bank_type Yes String(1 CMC String states bank_type

6)
Total Amount total_fee Yes Int 100 Specifies the total amount for a transaction. For more
information, see Section 4.2. Payment Amount.
Currency fee_type Yes String(8) GBP ISO-4217 standard compliant and be described by
Type three characters based code. For more information, see
Cash Payment cash_fee Yes Int 100 Specifies the total cash payment amount of a
Amount transaction. For more information, see Section 4.2
Payment Amount.
Cash Type cash_fee_type No String(1 CNY ISO-4217 standard compliant and be described by
6) three characters based code. For more information, see
Specifies the transaction_id Yes String(3 121775250120 Specifies the WeChat payment order id number
number of a 2) 140703323336
WeChat 8018
payment order
Vendor Order out_trade_no Yes String(3 121775250120 Specifies an order number created by a Vendors'
Number 2) 140703323336 system, which is consistent with request.
8018
Vendor's Data attach No String(1 123456 Specifies vendor's data package, which is returned as it
Package 28) is.
Payment End time_end Yes String(1 201410301335 Specifies the transaction payment time in the format of
Time 4) 25 yyyyMMddHHmmss, such as 20091225091010 for
Exchange rate Yes String(1 650000000 The value is 10 to the 8th power times of the exchange
Rate 6) rate from foreign currency to RMB. For example, the
exchange rate from foreign currency to RMB is 6.5,
the value will be 650000000
Example:
<xml>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[TN55wO9Pba5yENl8]]></nonce_str>
<sign><![CDATA[BDF0099C15FF7BC6B1585FBB110AB635]]></sign>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<trade_type><![CDATA[MICROPAY]]></trade_type>
<bank_type><![CDATA[CCB_DEBIT]]></bank_type>
<attach><![CDATA[Additional Order description]]></attach>
<trade_state><![CDATA[SUCCESS]]></trade_state>
</xml>
6 Error Code
ORDERNOTEXIST This order does This order number does not This API only helps query successfully
not exist exist in the query system paid transactions. The Vendor should
check whether the provided transaction
ID is correct.
SYSTEMERROR System error Exception occurs when data is This is caused by system error. Try to
returned from backend query again.
3. Close Order
1 Use Case
This API needs to be called before a vendor wants to create a new order due to the Payer failing to pay for an
order. The original order will be closed in order to avoid repeat payment. After an order is created in the WeChat
payment system, if the Payer doesn't pay within the required time, no further operation can be performed in the system.
To prevent the Payer from proceeding with their order, this API is called to close the order.
Note: The Close Order API might be used no shorter than 5 minutes after the order is created.
2 URL
https://api.mch.weixin.qq.com/pay/closeorder
Official Account appid Yes String( wx88888888888 Specifies Official Account ID assigned by
ID 32) 88888 WeChat
Vendor ID mch_id Yes String( 1900000109 Specifies vendor ID assigned by WeChat

32) Payment
Vendor Order out_trade_ Yes String( 12177525012014 Specifies an internal order number created
Number no 32) 07033233368018 by the Vendors system
Random String nonce_str Yes String( 5K8264ILTKCH 32 alphanumeric characters or fewer. For
32) 16CQ2502SI8Z more information, see Section 4.2 Vendor's
NMTM67VS Order Number.
Signature sign Yes String( C380BEC2BFD7 Specifies a signature. For more information,
32) 27A4B68451335 see Section 4.3.1 Signature Algorithm.
19F3AD6
Sign type sign_type NO String( HMAC-SHA256 Currently support HMAC-SHA256 and

32) MD5, default is MD5. This field is only
required when sign_type is HMAC-SHA256
Example:
<xml>
<nonce_str>4ca93f17ddf3443ceabf72f26d64fe0e</nonce_str>
<sign>59FF1DF214B2D279A0EA7077C54DD95D</sign>
</xml>
5 Return Data
Return Status return_code Yes String(16) SUCCES SUCCESS or FAIL

Code S
Return Data return_msg No String(128 Signature If not empty, this is the error description
) failure
Signature failure
Official Account appid Yes String(32) wx8888888 The Official Account ID submitted when
ID 888888888 calling the interface
interface
Random String nonce_str Yes String(32) 5K8264ILT 32 characters or fewer

KCH16CQ2
502SI8ZN
MTM67VS
Signature sign Yes String(32) C380BEC2 Specifies a signature. For more information,
BFD727A4 see Section 4.3.1 Signature Algorithm.
B68451335
19F3AD6
Error Code err_code No String(32) SYSTEME For more information, see Section 5.5.6
RROR Error Code
Error Code err_code_des No String(128 System Describes result data

Description ) error
Example:
<xml>
<nonce_str><![CDATA[BFK89FC6rxKCOjLX]]></nonce_str>
<sign><![CDATA[72B321D92A7BFA0B2509F3D13C7B1631]]></sign>
</xml>
6 Error Code
ORDERPAID Order is paid Order is paid and cannot be Order is already paid and cannot be
closed closed. No further operation is required.
SYSTEMERROR System error System error System exception has occurred. Call this
API again.
ORDERNOTEXIST Order does not This order does not exist in the Dont attempt to close this order yet as it
exist system is still a pending transaction
ORDERCLOSED Order is closed Order is closed and cannot be Order is already closed and no further
done again. operation is required
requirements
REQUIRE_POST_METH Use post Data is not transferred by post Check whether data is submitted by
OD method POST method
XML_FORMAT_ERROR INVALID INVALID XML FORMAT Check whether XML parameters are in
XML correct format
FORMAT
4. Submit Refund
1 Use Case
For a period after a payment transaction has been completed and a refund is required by either the Payer or
Vendor, the Vendor can refund the Payer via this API. After the WeChat payment system receives and verifies the
refund request successfully, the Payer will be refunded with the original payment amount according to the refund rules.
Notes:
1. For any transaction completed more than 12 months prior, a refund is not supported;
2. A refund for a transaction can be processed in the form of multiple partial refunds. In this case, the original
order number is required and multiple refund numbers must be set. The total refund amount cannot exceed the original
payment amount.
The Vendor should review the following Submit Refund flowchart demonstrating when this API is called
successfully:
2 URL
URLhttps://api.mch.weixin.qq.com/secapi/pay/refund
Two-way certificate is required
Official appid Yes String(32) wx8888888888 Specifies Official Account ID assigned by WeChat
Account ID 888888
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID assigned by WeChat Payment
Device ID device_info No String(32) 0134670070457 Specifies the terminal device ID assigned by WeChat
64 Payment. This field should match the value of
device_info when the order was created.
Random nonce_str Yes String(32) 5K8264ILTKC 32 characters or fewer. For more information, seeSection
String H16CQ2502SI8 4.3.2 Random String Algorithm.
ZNMTM67VS
Signature sign Yes String(32) C380BEC2BFD Specifies a signature. For more information, see Section
727A4B684513 4.3.1 Signature Algorithm.
3519F3AD6
Sign type sign_type NO String(16) HMAC-SHA25 Currently HMAC-SHA256 and MD5 are supported,
6 default is MD5. This field is only required when
sign_type is HMAC-SHA256
WeChat transaction_i String(32) 1217752501201

Order d 4070332333680 Specifies the WeChat payment order id number
Number 18
Choose
Vendor Order out_trade_n String(32) 1217752501201 out_trade_no is an internal order number within the
one to
Number o 4070332333680 vendors system.
submit
18
transaction_id will be used over out_trade_no if they are
both provided by the vendor.
Vendor out_refund_ Yes String(32) 1217752501201 Specifies the internal refund number, which is unique in
Refund no 4070332333680 the system. A single transaction can be processed as
Number 18 multiple partial refunds, with the total sum of the partial
refunds being equal to the original one.
Total Amount total_fee Yes Int 100 Specifies the total order amount. The units are expressed
in cents and must be an integer. For more information,
see Section 4.2 Payment Amount.
Refund refund_fee Yes Int 100 Specifies the total refund amount for a transaction. The
Amount units are expressed in cents and shall be an
integer.Section 4.2 Payment Amount.
Currency refund_fee_t No String(8) GBP ISO-4217 standard compliant and be described by three
Type ype characters based code. The refund currency type must be
same with the bid currency type. For more information,
see Section 4.2 Currency Type.
Operator op_user_id Yes String(32) 1900000109 Specifies the Operator ID. This field shows vendor's ID
by default.
Example:
<xml>
<nonce_str>6cefdb308e1e2e8aabd48cf79e546a02</nonce_str>
<op_user_id>10000100</op_user_id>
<out_refund_no>1415701182</out_refund_no>
<refund_fee>1</refund_fee>
<transaction_id></transaction_id>
<sign>FE56DD4AA85C0EECA82C35595A69E153</sign>
</xml>
5 Return Data

Code
Return Data return_msg No String(128 Signature failure If not empty, this is the error description
)
Signature failure
Result Code result_code Yes String(16) SUCCESS SUCCESS/FAIL
SUCCESS: Receives refund application

successfully. To get refund status, calling Query
Refund API is required.
FAIL: Submitting refund application failed.
Error Code err_code No String(32) SYSTEMERROR For more information, see Section 9.6 Download
Transaction History.
Error Code err_code_de No String(128 System timed out Describes result data
Description s )
Official appid Yes String(32) wx88888888888888 The Official Account ID submitted when calling
Account ID 88 the interface
interface
Device ID device_info No String(32) 013467007045764 Specifies the terminal device ID assigned by

WeChat Payment. The value in this field must
match the device_info value used when the order
was created.
Random nonce_str Yes String(32) 5K8264ILTKCH16 32 characters or fewer

String CQ2502SI8ZNMT
M67VS
Signature sign Yes String(32) 5K8264ILTKCH16 Specifies a signature. For more information, see
CQ2502SI8ZNMT Section 4.3.1 Signature Algorithm.
M67VS
WeChat Order transaction_ Yes String(32) 1217752501201407

Specifies the WeChat payment order id number
Number id 033233368018
Vendor Order out_trade_n Yes String(32) 1217752501201407

Specifies an internal order number created by the
Number o 033233368018
Vendors system
Vendor out_refund_ Yes String(32) 1217752501201407

Refund no 033233368018 Vendor Refund Number
Number
WeChat refund_id Yes String(32) 1217752501201407

Refund 033233368018 WeChat Refund Number
Number
Refund refund_chan No String(16) ORIGINAL ORIGINAL: Back to the original transaction card
Channels nel or balance.
BALANCE: Back to balance.
Refund refund_fee Yes Int 100 Specifies the total refund amount expressed in
Amount cents and must be an integer. For more
information, see Section 4.2 Payment Amount
A refund can be processed as multiple partial

refunds.
Currency refund_fee_t Yes String(8) GBP ISO-4217 standard compliant and be described by
Type ype three characters based code. The refund currency
type must be same with the bid currency type. For
more information, see Section 4.2 Currency Type.
Total Amount total_fee Yes Int 100 Specifies the total order amount expressed in
cents and must be an integer. For more
Order fee_type Yes String(8) GBP ISO-4217 standard compliant and be described by
Currency three characters based code. For more
Type information, see Section 4.2 Currency Type.
Cash Payment cash_fee Yes Int 100 Specifies the cash payment amount expressed in
Payment cash_fee_ty Yes String(8) CNY Complies with ISO 4217 standards and uses CNY
Currency pe (Chinese yuan) by default. For more information,
Type see Section 4.2 Currency Type.
Cash Refund cash_refund Yes Int 100 Specifies the cash refund amount expressed in
Amount _fee cents and must be an integer. For more
Cash Refund cash_refund No String(8) CNY Complies with ISO 4217 standards and uses CNY
Currency _fee_type (Chinese yuan) by default. For more information,
Type see Section 4.2 Currency Type.
Exchange rate Yes String(16) 650000000 The value is 10 to the 8th power times of the
Rate exchange rate from foreign currency to RMB. For
example, the exchange rate from foreign currency
to RMB is 6.5, the value will be 650000000
Example:
<xml>
<nonce_str><![CDATA[NfsMFbUFpdbEhPXP]]></nonce_str>
<sign><![CDATA[B7274EB9F8925EB93100DD2085FA56C0]]></sign>
<out_refund_no><![CDATA[1415701182]]></out_refund_no>
<refund_id><![CDATA[2008450740201411110000174436]]></refund_id>
<refund_channel><![CDATA[]]></refund_channel>
<coupon_refund_fee>0</coupon_refund_fee>
</xml>
6 Error Code
SYSTEMERROR API return error System timed out Call this API again using the same
parameters
INVALID_TRANSAC Invalid Requested parameters are Incorrect request parameters. Check

TIONID transaction_id not correct whether the original transaction ID exists or
whether data failed to be returned from the
payment interface.
PARAM_ERROR Parameter error Requested parameters are Incorrect request parameters. Check the
not correct parameters and call the Submit Refund API
again.
APPID_NOT_EXIST APPID DOES NOT No APPID in this parameter Check whether the provided APPID is
EXIST correct
MCHID_NOT_EXIST MCHID DOES NOT No MCHID in this Check whether the provided MCHID is
EXIST parameter correct
APPID_MCHID_NOT appid does not match appid does not match Check whether appid belongs to the
_MATCH mch_id mch_id associated mch_id
REQUIRE_POST_ME Use post method Data is not transferred by Check whether data is submitted by POST
THOD post method
SIGNERROR Signature error Incorrect signature result Check whether the signature parameter and
method complies with signature algorithm
requirements
XML_FORMAT_ERR INVALID XML INVALID XML FORMAT Check whether XML parameters are in the
OR FORMAT correct format
5. Query Refund
1 Use Case
After submitting Submit Refund, this API can be called to check the refund status. After submitting a refund, there
may be a delay in processing the refund: 20 minutes for refunding to Balance and 3 working days for refunding to a
bank card.
2 URL
URLhttps://api.mch.weixin.qq.com/pay/refundquery
Official appid Yes String(32) wx88888888888888 Specifies Official Account ID assigned

Account ID 88 by WeChat
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID assigned by

WeChat Payment
Device ID device_info No String(32) 013467007045764 Specifies the terminal device ID

assigned by WeChat Payment
Random String nonce_str Yes String(32) 5K8264ILTKCH16 32 characters or fewer. For more
CQ2502SI8ZNMT information, see Section 4.3.2 Random

AD6 Algorithm.
Sign type sign_type NO String(32) HMAC-SHA256 Currently HMAC-SHA256 and MD5
are supported, default is MD5. This
field is only required when sign_type is
HMAC-SHA256
WeChat Order transaction_id String(32) 1217752501201407 Specifies the WeChat payment order id
Number 033233368018 number
Vendor Order out_trade_no String(32) 1217752501201407 Specifies an internal order number

Number 033233368018 created by the Vendors system
Vendor Refund out_refund_no String(32) 1217752501201407

Vendor Refund Number
Number Choose one 033233368018
to submit
WeChat Refund refund_id String(32) 1217752501201407 WeChat Refund Number. Returned
Number 033233368018 from Submit Refund API.
This field will supply the refund_id,

out_refund_no, out_trade_no, or
transaction_id. Their priority is as
shown below:
refund_id>out_refund_no>transaction_i
d>out_trade_no
Example:
<xml>
<nonce_str>0b9f35f484df17a732e537c37708d1d0</nonce_str>
<out_refund_no></out_refund_no>
<refund_id></refund_id>
<transaction_id></transaction_id>
<sign>66FFB727015F450D167EF38CCC549521</sign>
</xml>
5 Return Data

Code
)
Signature failure
Error Code err_code Yes String(32) SYSTEMERRO For more information, see Section 9.6 Download
R Transaction History.
Error err_code_des Yes String(32) System error Describes result data

Description
Official appid Yes String(32) wx8888888888 The Official Account ID submitted when calling
Account ID 888888 the interface
interface
Device ID device_info No String(32) 0134670070457 Specifies the terminal device ID assigned by

64 WeChat Payment. The value in this field must
match the device_info value used when the order
was created.
Random String nonce_str Yes String(28) 5K8264ILTKC

H16CQ2502SI8 32 characters or fewer
ZNMTM67VS
Signature sign Yes String(32) C380BEC2BFD

Specifies a signature. For more information, see
727A4B684513
Section 4.3.1 Signature Algorithm.
3519F3AD6
WeChat Order transaction_id Yes String(32) 1217752501201

Number 4070332333680 The WeChat payment order id number
18
Vendor Order out_trade_no Yes String(32) 1217752501201

An internal order number created by the
Number 4070332333680
Vendors system
18
Total Amount total_fee Yes Int 100 Specifies the total order amount expressed in
cents and must be an integer. For more
Order Currency fee_type Yes String(8) GBP ISO-4217 standard compliant and be described
Type by three characters based code. For more
information, see Section 4.2 Currency Type.
Cash Payment cash_fee Yes Int 100 Specifies the cash payment amount expressed in
Payment cash_fee_type Yes String(8) CNY Complies with ISO 4217 standards and uses
Currency Type CNY (Chinese yuan) by default. For more
information, see Section 4.2 Currency Type.
Refund refund_fee_$n Yes Int 100 Specifies the bid amount of refund expressed in
A refund can be processed as multiple partial

refunds. The bid currency type should be
consistent with the bid amount.
Exchange Rate rate Yes String(16) 650000000 The value is 10 to the 8th power times of the
exchange rate from foreign currency to RMB.
For example, the exchange rate from foreign
currency to RMB is 6.5, the value will be
650000000
Refund Count refund_count Yes Int 1 Record counts of refund
Vendor Refund out_refund_no_ Yes String(32) 1217752501201 Vendor refund number

Number $n 4070332333680
18
WeChat refund_id_$n Yes String(32) 1217752501201 Wechat refund number

Refund 4070332333680
Number 18
Refund refund_channel No String(16) ORIGINAL ORIGINAL: Back to the original transaction

Channel _$n card or balance.
BALANCE: Back to balance.
Refund Status refund_status_$ Yes String(16) SUCCESS Refund Status:

n
SUCCESS: Refunded successfully
FAIL: Refund failed
PROCESSING: Refund is pending
NOTSURE: Require the Vendor to call the

Submit Refund API again with the original
refund number
CHANGE: Refund can't be processed as the

Payer's bank card is either revoked or blocked.
As a consequence, the refund will be transferred
to the Vendor's cash account. In this case, the
refund must be processed offline via the help of
the vendors customer support staff or by
transferring the refund amount from the Vendor
to the Payer via Tenpay.
Example:
<xml>
<nonce_str><![CDATA[TeqClE3i0mvn3DrK]]></nonce_str>
<out_refund_no_0><![CDATA[1415701182]]></out_refund_no_0>
<refund_count>1</refund_count>
<refund_fee_0>1</refund_fee_0>
<refund_id_0><![CDATA[2008450740201411110000174436]]></refund_id_0>
<refund_status_0><![CDATA[PROCESSING]]></refund_status_0>
<sign><![CDATA[1F2841558E233C33ABA71A961D27561C]]></sign>
</xml>
6 Error Code
SYSTEMERROR API return error System timed out Try to call the API again
INVALID_TRANSAC Invalid transaction_id Requested parameters are Incorrect request parameters. Check whether
TIONID not correct the original transaction ID exists or whether
data failed to be returned from the payment
interface.
PARAM_ERROR Parameter error Requested parameters are Incorrect request parameters. Check
not correct parameters and call the Submit Refund API
again.
APPID_NOT_EXIST APPID DOES NOT No APPID in this parameter Check whether provided APPID is correct
EXIST
MCHID_NOT_EXIST MCHID DOES NOT No MCHID in this Check whether provided MCHID is correct
EXIST parameter
APPID_MCHID_NOT appid does not match appid does not match Check whether appid belongs to the
_MATCH mch_id mch_id associated mch_id
REQUIRE_POST_ME Use post method Data is not transferred via Check whether data is submitted by POST
THOD POST method method
requirements
XML_FORMAT_ERR INVALID XML INVALID XML FORMAT Check whether XML parameters are in
OR FORMAT correct format
6. Download Transaction History
1 Use Case
This API is used to help the Vendors download their transaction record history including missing orders, and can
be used to find unmatched data between vendors and WeChat caused by system error. By downloading transaction
history and doing reconciliation, the Vendor can correct the status of their orders in a timely fashion.
Notes:
1. Transactions that are not ordered successfully are excluded in this reconciliation form, while orders that are
revoked after successful payment will still be included. Included orders shall be consistent with the original payment
bill number, that is, the value of bill_type will be set to REVOKED;
2. Each day's transaction history download is created at 9:00 AM the following day. Therefore, vendors can
download the history after 10:00 AM (UTC+08);
3. The currency unit used in the reconciliation form is bid currency unit. (Like Chinese yuan, US dollar).
2 URL
https://api.mch.weixin.qq.com/pay/downloadbill
Official appid Yes String(3 wx888888888888 Specifies Official Account ID assigned by WeChat
Account ID 2) 8888
Vendor ID mch_id Yes String(3 1900000109 Specifies vendor ID assigned by WeChat Payment
2)
Device ID device_info No String(3 01346700704576 Specifies the terminal device ID assigned by WeChat
2) 4 Payment. This field specifies the transactions related to
this device.
Random nonce_str Yes String(3 5K8264ILTKCH1 32 characters or fewer. For more information, see Section
String 2) 6CQ2502SI8ZN 4.3.2 Random String Algorithm.
MTM67VS
Signature sign Yes String(3 C380BEC2BFD7 Specifies a signature. For more information, see Section
2) 27A4B684513351 4.3.1 Signature Algorithm.
9F3AD6
Sign type sign_type NO String(3 HMAC-SHA256 This field is only required when sign_type is
2) HMAC-SHA256. Default is MD5.
Reconciliati bill_date Yes String(8 20140603 Specifies the date of the transactions to be downloaded in
on Start Date ) the format of yyyymmdd, such as 20140603 for June 3,
2014.
Bill Type bill_type No String(8 ALL ALL: Return all order data from the specified date.
) bill_type is set to ALL by default.
SUCCESS: Return successfully paid orders only
REFUND: Return refunded orders only
<xml>
<bill_date>20141110</bill_date>
<bill_type>ALL</bill_type>
<nonce_str>21df7dc9cd8616b56919f20d9f679233</nonce_str>
<sign>332F17B766FC787203EBE9D6E40457A1</sign>
</xml>
5 Return Data
If the request has failed, the following fields will be returned.
Return Status return_code Yes String(16) FAIL FAIL

Code
Return Data return_msg No String(128) Signature failure If not empty, this is the error description
Signature failure
The order date is not created
When the query has succeeds, the returned data will include a header row containing the data fields of the
subsequent rows.
The first row will be the header row, with the value based upon the Bill Type (as specified by bill_type) requested
by the Vendor and containing the included data fields of the subsequent row.
Transaction records begin from the second row, and transaction fields are comma-separated values and begin with
the ` character (to the right of the 1 key on a standard keyboard) and in the same order as the fields listed in the
header row of the returned data.
The second to last row will contain descriptive headers of the transaction history statistics and the last row will
contain the statistical values of the returned transactions:
Total transactions, Total order amount, Total refunded amount, Total mobile coupon amount, Total mobile
coupon refunds
An example of returned data follows:
Transaction time, Official account ID(appid), Vendor ID(mch_id), Sub vendor ID(sub_mch_id), Device
ID(Device_info), Wechat order number(transaction_id), Vendor order number(out_transaction_id), User tag(openid),
Transaction type(trade_type), Transaction status(trade_state), Payment bank(bank_type), Currency type(fee_type),
Total amount(total_fee), Refund apply time, Refund complete time, Wechat refund number(refund_id), Vendor refund
number(out_refund_no), Refund amount(refund_fee), Refund type, Refund status(refund_status_$n), Product name,
Vendors data package(attach), Fee, Rate, Payment Currency type(Cash_fee_type), Cash payment amount(Cash_fee),
Settlement currency type, Settlement currency amount, Exchange rate, Refund exchange rate, Payers Refund amount,
Payers Refund currency type, Refund currency type, Refund settlement currency type, Refund settlement amount
2016-01-2812:09:57,`wx77f7fce3722c712b,`1277115701,`0,`1002200845,`1000221008201601282949658332,`21241
20160125520751765,`orB2gVv8fX95-ghb8ws3Eunw,`MICROPAY,`SUCCESS,`GDB_CREDIT,`HKD,`198.00,`0.00,
`0,`0,`0,`0,`,`,`,`,`1.19000,`0.60%,`CNY,`168.01,`HKD,`198.00,`84853800,`0,`0,`,`,`,`0
6 Error Code
SYSTEMERROR API return error System timed out Try to query again
INVALID_TRANSACTIONI Invalid transaction_id Requested parameters are not Parameter error. Check
D correct transaction_id and try again.
PARAM_ERROR Parameter error Requested parameters are not Parameter error. Check
correct parameters and try again.
7. General Payment Result Notification
1 Use Case
After completing a payment, the WeChat payment system will send the relevant payment result and user
information to the Vendor. When this happens, the Vendors backend will need to receive the result and return a reply
to the WeChat payment system.
When interacting with this API, if the WeChat payment system does not receive a notification from the Vendor
backend indicating success or timeout, the WeChat payment system will consider it as an unreceived notification and
initiate further payment result notifications at a regular interval, such as 8 times in 30 minutes, so as to ensure
successful receipt. However, the WeChat payment system cannot ensure successful receipt of payment notifications in
every case. (The notification frequency is 15/15/30/180/1800/1800/1800/1800/3600, unit is second)
As payment result notifications may be sent from the WeChat payment system to the Vendors backend multiple
times, a single payment result might be notified to the Vendor's backend multiple times. For this reason, the Vendor's
system must be able to handle duplicate notifications properly.
The best practices for dealing with such case: when a notification is received and processed, the enclosed payment
data should be checked first to confirm whether the payment result has previously been processed or not. If so, return
the processed result; if no, proceed with processing the result first before returning. Before checking the payment data,
a transaction lock shall be used for concurrency to prevent data corruption caused by transaction race conditions.
Developers can log in to the WeChat payment system for vendors and join the API warning group.
2 URL
This URL may be configured via notify_url, a parameter submitted via the Unified Order API, If the URL is
inaccessible, the vendors will not be able to receive any notifications sent from the WeChat payment system.
4 Notification Parameters
Return Status return_code Yes String( SUCCESS SUCCESS or FAIL

Code 16)
Specifies communicating label instead of transaction label. The
status of a transaction is determined by the value of result_code.
Return Data return_msg No String( Signature If not empty, this is the error description
128) failure
Signature failure
Official appid Yes String(32) wx8888888888 The Official Account ID assigned by WeChat
Account ID 888888
Vendor ID mch_id Yes String(32) 1900000109 The vendor ID assigned by WeChat Payment
Device ID device_info No String(32) 0134670070457 The terminal device ID assigned by WeChat Payment
64
Random nonce_str Yes String(32) 5K8264ILTKC 32 characters or fewer

String H16CQ2502SI8
ZNMTM67VS
Signature sign Yes String(32) C380BEC2BFD Specifies a signature. For more information, see
3519F3AD6
Sign Type sign_type No String(32) HMAC-SHA25 Currently HMAC-SHA256 and MD5 are supported,
6 default is MD5. This field is only required when
sign_type is HMAC-SHA256.
Service result_code Yes String(16) SUCCESS SUCCESS or FAIL

Result
Error Code error_code No String(32) SYSTEMERRO The error code returned

R
Error Code error_code_d No String(128 System error The detailed error description returned.
Description es )
User Tag openid Yes String(128 wxd930ea5d5a2 The user id of the Payer provided by the WeChat
) 58f4f system in OpenID format as unique tag on vendors
appid. Also it is unique to each appid instance.
Follows is_subscribe No String(1) Y Specifies whether the payer follows the associated
Official official account or not, with Y meaning follows and
Account or N meaning not follows.
not
Transaction trade_type Yes String(16) JSAPI Set as JSAPI, NATIVE, or APP

Type
Payment bank_type Yes String(16) CMC Use strings for bank type. For more information, see
Bank attachments.
Total Amount total_fee Yes Int 100 Specifies the total amount for a transaction in cents as
integer. For more information, see Section 4.2.
Payment Amount.
Currency fee_type Yes String(8) GBP ISO-4217 standard compliant and be described by
Type three characters based code. For more information, see
Section 4.2 Currency Type
Cash cash_fee Yes Int 100 Specifies the total payment amount of a transaction.
Payment For more information, see Section 4.2 Payment
Amount Amount.
Cash Type cash_fee_typ Yes String(16) CNY Complies with ISO 4217 standards and uses CNY
e (Chinese yuan) by default. For more information, see
Section 4.2 Currency Type
Specifies the transaction_i Yes String(32) 1217752501201 The WeChat payment order id number
number of a d 4070332333680
WeChat 18
payment
order
Vendor Order out_trade_no Yes String(32) 1212321211201 Specifies an order number created by a Vendors'
Number 4070335681123 system, which is consistent with request.
22
Vendor's attach No String(128 123456 Specifies vendor's data package, which is returned as it
Data Package ) is.
Payment End time_end Yes String(14) 2014103013352 Specifies the time of completing payment in the format
Time 5 of yyyyMMddHHmmss, such as 20091225091010 for
Exchange rate Yes String(16) 650000000 The value is 10 to the 8th power times of the exchange
Rate rate from foreign currency to RMB. For example, the
exchange rate from foreign currency to RMB is 6.5,
the value will be 650000000
Example:
<xml>
<attach><![CDATA[Payment Testing]]></attach>
<bank_type><![CDATA[CFT]]></bank_type>
<nonce_str><![CDATA[5d2b6c2a8db53831f7eda20af46e531c]]></nonce_str>
<openid><![CDATA[oUpF8uMEb4qRXf22hE3X68TekukE]]></openid>
<sign><![CDATA[B552ED6B279343CB493C5DD0D78AB241]]></sign>
<sub_mch_id><![CDATA[10000100]]></sub_mch_id>
<trade_type><![CDATA[JSAPI]]></trade_type>
</xml>
5 Return Data
Parameters returned to the WeChat payment system by the Vendors backend immediately after the Vendor has
processed the payment result notification:

Code 16)
SUCCESS indicates that Vendor has received payment
result notification and has verified the payment
successfully
Return Data return_msg No String( OK If not empty, this is the error description
128)
Signature failure
Example:
<xml>
</xml>
1 Use Case
This API is used to assist the Vendors in improving overall service quality when they call the WeChat payment
APIs. With this API, vendors obtain relevant returned data and response duration. Based on the Vendor's uplink
network speed, the WeChat payment system optimizes its networking deployment, so as to continuously improve
service reliability and speed.
2 URL
https://api.mch.weixin.qq.com/payitil/report
No
4 Input Parameter
Official appid No String(32) wx88888888888888 Specifies Official Account ID assigned by WeChat

Account ID 88
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID assigned by WeChat Payment
Device ID device_info No String(32) 013467007045764 Specifies the terminal device ID assigned by WeChat
Payment. This field is defined by vendors.
Random nonce_str Yes String(32) 5K8264ILTKCH16C 32 characters or fewer. For more information, see
String Q2502SI8ZNMTM6 Section 4.3.2 Random String Algorithm.
7VS
Signature sign Yes String(32) C380BEC2BFD727 Specifies a signature. For more information, see
A4B6845133519F3 Section 4.3.1 Signature Algorithm.
AD6
Sign Tyep Sign_type No String(32) HMAC-SHA256 Currently HMAC-SHA256 and MD5 are supported,
default is MD5. This field is only required when
sign_type is HMAC-SHA256.
Interface interface_url Yes String(127 https://api.mch.weixi Complete interface URL to be reported is similar to
URL ) n.qq.com/pay/unified the following:
order
https://api.mch.weixin.qq.com/pay/unifiedorder
When Quick Pay is used, in order to analyze the

overall duration of a single service with vendors,
WeChat requires a report for each Quick Pay service
call made in either mode 1 or mode 2. The report
URL is as below:
https://api.mch.weixin.qq.com/pay/micropay/total
For more information about mode 2, see Section 5.4

Process for vendors.
For other payment methods, calling and reporting is

only required once.
API Execute execute_time Yes Int 1000 Specifies the duration for calling the API. The units
Duration _ are expressed in milliseconds.
Return return_code Yes String(16) SUCCESS SUCCESS or FAIL
Status Code
value of trade_state.
)
Signature failure
Service result_code Yes String(16) SUCCESS SUCCESS or FAIL

Result
Error Code err_code No String(32) SYSTEMERROR ORDERNOTEXIST: Order does not exist
SYSTEMERROR: System error
Error Code err_code_des No String(128 System error Describes result data

Description )
Vendor out_trade_no No String(32) 12177525012014070 Specifies an order number created by the Vendors
Order 33233368018 system. The Vendor can report this order number to
Number WeChat payment system in order to help improve
payment services.
Access user_ip Yes String(16) 8.8.8.8 Specifies the machine IP used when calling this
Interface IP interface
Vendor time No String(14) 20091227091010 Specifies system time in the format of

Report Time yyyyMMddHHmmss, such as 20091227091010 for
Section4.2 Time Protocol.
5 Return Data
Return return_code Yes String(16) SUCCESS SUCCESS or FAIL

Status Code
value of result_code.
Return Data return_msg No String(128) Signature failure If not empty, this is the error description
Signature failure

6 Error Code
None
9. Short URL Conversion
1 Use Case
This API is used for the URL embedded in a QR code when using native payment method 1 and converts it into
short URL (weixin://wxpay/s/XXXXXX), so as to reduce data volume, speed up scanning, and improve accuracy.
2 URL
https://api.mch.weixin.qq.com/tools/shorturl
Official appid Yes String(32) wx888888888888888 Specifies Official

Account ID 8 Account ID assigned
by WeChat
Vendor ID mch_id Yes String(32) 1900000109 Specifies vendor ID
assigned by WeChat
Payment
Long URL long_url Yes String(512) weixin://wxpay/bizpa Specifies the URL to
yurl?sign=XXXXX& be converted. The
appid=XXXXX&mc signature keeps
h_id=XXXXX&prod original string and
uct_id=XXXXXX&ti uses URL encode for
me_stamp=XXXXX transferring data.
X&nonce_str=XXXX
X
Random nonce_str Yes String(32) 5K8264ILTKCH16C 32 characters or

String Q2502SI8ZNMTM67 fewer. For more
VS information, see
Section 4.3.2
Random String
Algorithm.
Signature sign Yes String(32) C380BEC2BFD727A Specifies a signature.
4B6845133519F3AD For more
6 information, see
Section 4.3.1
Signature Algorithm.
Sign type sign_type NO String(32) HMAC-SHA256 Currently

HMAC-SHA256 and
MD5 are supported,
default is MD5. This
field is only required
when sign_type is
HMAC-SHA256
5 Return Data

Code 16) Specifies communicating label
instead of transaction label. The
status of a transaction is determined
by the value of result_code.
Return Data return_msg No String( Signature If not empty, this is the error
128) failure description
Signature failure
Official appid Yes String( wx88888888 The Official Account ID submitted

Account ID 32) 88888888 when calling the interface
Vendor ID mch_id Yes String( 1900000109 The Vendor ID submitted when
32) calling the interface
Random nonce_str Yes String( 5K8264ILTK 32 characters or fewer. For more
String 32) CH16CQ250 information, see Section 4.3.2
2SI8ZNMTM Random String Algorithm.
67VS
Signature sign Yes String( C380BEC2B Specifies a signature. For more
32) FD727A4B68 information, see Section 4.3.1
45133519F3 Signature Algorithm.
AD6
Service result_code Yes String( SUCCESS SUCCESS or FAIL
Result 16)
Error Code err_code No String( SYSTEMER SYSTEMERROR: System error
32) ROR URLFORMATERROR: Incorrect
URL format
Short URL short_url Yes String( weixin://wxp Specifies the converted URL
64) ay/s/XXXXX
X
6 Error Code
SIGNERROR Signature error Incorrect signature result Check whether the signature
parameter and method
comply with signature
algorithm requirements
REQUIRE_POST_METHOD Use post method Data is not transferred by post Check whether data is
submitted by POST method
APPID_NOT_EXIST APPID DOES NOT EXIST No APPID in this parameter Check whether provided
APPID is correct
MCHID_NOT_EXIST MCHID DOES NOT EXIST No MCHID in this parameter Check whether provided
MCHID is correct
APPID_MCHID_NOT_MAT appid does not match mch_id appid does not match mch_id Check whether appid belongs
CH to the associated mch_id
LACK_PARAMS Missing parameter Required parameter is Check whether parameter is

missing provided
XML_FORMAT_ERROR INVALID XML FORMAT INVALID XML FORMAT Check whether XML
parameters are in correct
format
POST_DATA_EMPTY post data is empty post data cant be empty Check whether POST data is
empty
10. QUERYING SETTLED FUNDS
1 Use Case
This API helps query the details of settled funds.
2 URL
https://api.mch.weixin.qq.com/pay/settlementquery
Field Name ID Type Required Example Description
Official appid String(32) Yes Wx1378ac Specifies Official Account ID

Account ID ui7865dt65 assigned by WeChat
125678765 Specifies vendor ID assigned

Vendor ID mch_id String(32) Yes
49 by WeChat Pay
Indicates that the fund has

been settled or is still outstanding:
Settlement
usetag Int Yes 1
Status 1 - settled
2 - outstanding
Random nonce_str String(32) Yes Uihu276jjg A random string. 32

String hxlehu387 characters or fewer.
64409322
Returned query data starts

Offset offset Int Yes 1
from this offset value
Max The max amount of returned

limit Int Yes 10
Records records (generally less than 10)
Start Date date_start String(14) Yes 20150807 In the format of yyyyMMdd.

For example, December 25, 2009 is
expressed as 20091225 in the time
zone (GMT+8). (This field is
optional when inquiring the
outstanding records)
End Date date_end String(14) Yes 20150807 In the format of yyyyMMdd.

For example, December 25, 2009 is
zone (GMT+8). (This field is
optional when inquiring the
outstanding records)
Signature sign String(32) Yes 8439EBD8 For details about signature,

AE742259 see Section 3.2
0E2004D0
C5EBFFB
C
5. Return Data
Field Name ID Required Type Description
Return Status return_co Yes Stri SUCCESS/FAIL

Code de ng(16)
Specifies communicating label (not
transaction label). The status of a transaction is
determined by the value of result_code.
Return Data return_ms No Stri If returned data is not empty, the returned
g ng(128) data is the error description of the following:
- Signature Failure
- Parameter format checking error
If return_code is SUCCESS, the return data also includes the following fields:
Official appid Yes String(32 The Official Account ID submitted when calling the
Account ID ) interface
Vendor ID mch_id Yes String(32 The Vendor ID submitted when calling the interface
)
Random nonce_str Yes String(32 Indicates a random string of less than 32

String ) characters
Service result_cod Yes String(16 SUCCESS/FAIL

Result e )
Error Code err_code No String(32 Please refer to Error code

)
Error Code err_code_ No String(12 Describes detailed error information

Description des 8)
Return Data record_nu Yes String(10 Indicates records amount of return data
Lines m )
The following fields will be returned when both return_code and result_code are SUCCESS. In case
of multiple records, the data will be repeated.
Exchange fbatchno Yes String(32 Indicates the batch number of exchange

Payment ) payment
Batch
Number
Settlement date_settl Yes String(14 In the format of yyyyMMdd. For example,

Date ement ) December 25, 2009 is expressed as 20091225 in
the time zone (GMT+8).
Transaction date_start Yes String(14 In the format of yyyyMMdd. For example,

Start Date ) December 25, 2009 is expressed as 20091225 in
Trasanction date_end Yes String(14 In the format of yyyyMMdd. For example,

End Date ) December 25, 2009 is expressed as 20091225 in
Remit settlement Yes String(32 Priced in foreign currency at the minimum

Amount _fee ) trading unit
Non-Remit unsettlem Yes String(32 Priced in foreign currency at the minimum

Amount ent_fee ) trading unit
Settlement settlement Yes String(8) Comply with ISO 4217 standards and use
Currency fee_type CNY for Chinese currency by default.
Description:
CNYChinese yuan
GBP: Great Britain pound
HKD: Hong Kong dollar
USD: United States dollar
JPY: Japanese yen
CAD: Canadian dollar
AUD: Australian dollar
EUR: Euro
THB: Thailand baht
Notes: The currency type for payment and

refund shall be the same.
Payment pay_fee Yes Int Priced in foreign currency at the minimum trading
Amount unit
Refund refund_fe Yes Int Priced in foreign currency at the minimum trading
Amount e unit
Net Payment pay_net_f Yes Int Priced in foreign currency at the minimum trading
Amount ee unit
Charge poundage Yes Int Priced in foreign currency at the minimum trading
Amount _fee unit
Example:
<xml>
<return_code>SUCCESS</return_code>
<result_code>SUCCESS</result_code>
<record_num>10</record_num>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<fbatchno>10</fbatchno>
<date_settlement>20150807</date_settlement>
<date_start>20150807</date_start>
<date_end>20150807</date_end>
<settlement_fee>1000</settlement_fee>
<unsettlement_fee>0</unsettlement_fee>
<settlement_type>USD</settlement_type>
<pay_fee>1000</pay_fee>
<pay_net_fee>1000</pay_net_fee>
<poundage_fee>0</poundage_fee>
</xml>
11. QUERY EXCHANGE RATE API
1. Use Case
The interface could inquiry the exchange rate which Wechat Payment used in real time. The rate is updated once
each day at 10 a.m. in the time zone (GMT+8).
2. URL
https://api.mch.weixin.qq.com/pay/queryexchagerate
3. Certificate Requirement
4. Request Parameters
Official appid Yes String( wx88888888 Specifies Official Account ID

Account ID 32) 88888888 assigned by WeChat
Vendor ID mch_id Yes String( 1900000109 Specifies Vendor ID assigned by
32) WeChat
Sub Vendor sub_mch_id No String( 1230000100 Specifies Sub Vendor ID assigned
ID 32) by WeChat
Currency fee_type Yes String( USD Foreign currency type. ISO-4217
Type 10) standard compliant and be described
by three characters based code.
Date date Yes String( 20150807 In the format of yyyyMMdd. For
14) example, December 25, 2009 is
zone (GMT+8).
AD6
Example:
<xml>
<fee_type>CNY</fee_type>
<date>20150807</date>
</xml>
5. Return Data

Code 16) Specifies communicating label
instead of transaction label. The
status of a transaction is determined
by the value of result_code.
Return Data return_msg No String( Signature If not empty, this is the error
128) failure description
Signature failure
Official appid Yes String( wx88888888 The Official Account ID submitted

Account ID 32) 88888888 when calling the interface
Vendor ID mch_id Yes String( 1900000109 The Vendor ID submitted when
32) calling the interface
Sub Vendor sub_mch_id No String( 1230000100 The Sub Vendor ID submitted when
ID 32) calling the interface
Currency fee_type Yes String( USD Foreign currency type. ISO-4217
Type 10) standard compliant and be described
by three characters based code.
Exchange rate_time Yes String( 20150807 In the format of yyyyMMdd. For
Rate Time 14) example, December 25, 2009 is
zone (GMT+8).
Exchange rate Yes String( 650000000 The value is 10 to the 8th power
Rate 32) times of the exchange rate from
foreign currency to RMB. For
example, the exchange rate from
foreign currency to RMB is 6.5, the
value will be 650000000
AD6
Example:
<xml>
<fee_type>USD</fee_type>
<rate_time>20150807</rate_time>
<rate>650000000</rate>
</xml>
12. DOWNLOAD PAYMENT SDKS
Download the Quick Pay SDK

Download the Official Account Payment SDK
Download the App-based Payment SDK
13. FAQ AND ADDITIONAL REMARKS
6. SSL Minimum Version Requirement for Servers
As lower-versions of SSL encryption are more susceptible to vulnerabilities, developers should confirm whether
their SSL version requires an update. For more information, see the update notice in the WeChat Official Account
Admin Platform
https://mp.weixin.qq.com/cgi-bin/announce?action=getannouncement&key=1414562353&version=11&lang=zh_CN
Java-based developers can also refer to the instructions on the Oracle website: [Oracle Java disables
SSL3](http://www.oracle.com/technetwork/java/javase/documentation/cve-2014-3566-2342133.html)
7. IPv6 Requirements
If you have enabled IPv6, the IP of your site on as stored on our servers will be an IPv6 address. As IPv6 is not
supported throughout the Internet globally, you may face potentially long connection timeouts on IPv6.
We suggest you use IPv4 to resolve addresses when calling payment APIs.
How to use curl for PHP programing:
if(defined('CURLOPT_IPRESOLVE') && defined('CURL_IPRESOLVE_V4')){

curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
14. CONTACT US
1. Follow the "WeChat Payment for Vendors" official account and send us your feedback;
2. Contact us via email at [email protected]

WeChat Payment API

Uploaded by

Copyright:

Available Formats

WeChat Payment API

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

WeChat Payment API

Uploaded by

Copyright:

Available Formats

1.

ABOUT THIS DOCUMENT

2. TERMS USED IN THIS DOCUMENT

3) In-App Web-based Payment

1) WeChat Official Account Admin Platform

2) WeChat Open Platform

3) WeChat Vendor Platform

4) WeChat Payment System

5) Vendor Point of Sale Terminal

6) Vendor Backend System

10) JSAPI-based Web Payment

11) Native Payment

12) Payment Password

Table 3.1 Account parameters

Parameters in API Description

Table 4.1 API Rules

Transfer Use HTTPS for secure transactions

Submit Mode Use POST method

Data Format Data submitted and returned is in XML format

Char Use UTF-8 character encoding

Signature MD5 or HMAC-SHA256

Logic Determine protocol field, service field and transaction status.

The list of currency types is as below:

GBP: Great Britain pound

HKD: Hong Kong dollar

USD: United States dollar

JPY: Japanese yen

CAD: Canadian dollar

AUD: Australian dollar

NZDNew Zealand Dollar

KRWSouth Korean won

THB: Thailand baht

5) Vendors Order Number

General steps to create a signature:

Empty parameter values are excluded in the signature;

Parameter names are case-sensitive;

For the following transferred parameters:

(2) Join API keys

Obtain data to be transferred below:

2 Random String Algorithm

1) Obtain Vendor Certificate

Table 4.2: Certificate Description

Certificate Description Use Case Remarks

2) Use Vendor Certificate

3) Vendor Certificate Security

4 Vendor's Callback API Security

WeChat Official Account Admin Platform:

WeChat Open Platform:

5. QUICK PAY PROGRAMMING GUIDE

2. Payment Verification Code Rules

Require password verification for any untrusted or suspicious transactions;

Convenience stores: 7-Eleven, Guoda36524, Hi-24, etc.

Chain drugstores: LBX Pharmacy, GuoDa Drugstore, Nepstar Drugstore, etc.

Department stores: Rainbow, etc.

4. Process for Vendors

1 Access Mode - Vendors' Backend Access

2 Access Mode -- Physical Store Access

Figure 5.5 Physical Store Access Process

3 Password-Exempt Payment Process

2) Payer opens WeChat and enters Quick Pay in "Me"->"Wallet";