Development Guide
Password Verification Rules
The user's payment password shall be verified if the payment amount is greater than 1,000 CNY.
At most 5 password-free transactions are allowed for a single user account every day. Password verification is required if the number is exceeded.
If the WeChat Pay backend determines that the user's payment behavior is abnormal, a transaction conforming to the password-free payment rules may be subject to password verification.
Note: Based on the risk control policy, password verification may be required at any time.
Quick Pay Timing Diagram (Password-Free)
1. The cashier generates a payment order at the merchant cash register and displays the payment amount to the user.
2. The user opens the WeChat client, clicks “Wallet”, and selects “Quick Pay” to enter the barcode interface.
3. The cashier uses a code scanner to read the barcode on the screen of the user's mobile phone.
4. The code scanner uploads the read information to the store's cash register.
5. After receiving the payment information, the cash register sends a payment request to the merchant backend system.
6. The merchant backend system processes the payment request from the store's cash register, generates a signature, and calls the [Quick Pay API] to submit a payment request to the WeChat Pay system.
7. After receiving the payment request from the merchant side, the WeChat Pay system verifies the request, and processes it if it passes the verification. Then, the system returns the processed payment result to the merchant backend system. If the payment is successful, the WeChat Pay system returns the payment result to the merchant, and notifies the user of the payment result (in the form of an SMS message or a WeChat message).
8. The merchant backend system performs signature verification and processing on the payment result obtained, and returns the payment result to the store's cash register.
9. The cashier delivers the goods to the user after seeing the payment result at the cash register.
Quick Pay Timing Diagram (Password Required)
The interactive scenario is the same as the password-free mode, except that after the merchant calls the [Quick Pay API] to send a payment request, the WeChat Pay backend prompts the user to enter the password for payment confirmation, and the API returns the USERPAYING status synchronously. Then the merchant system performs round-robin calling of the [Query Order API] to verify whether the payment is successful.
The following timing diagram illustrates the payment process when password verification is required:
Since the processes before the merchant backend system sends a payment request to the WeChat Pay system are exactly the same between the two modes, only what logically comes after the sent request is described here.
1. After the merchant store generates an order, the cash register sends a payment request to the backend system.
2. The backend system calls the WeChat Pay [Quick Pay API] to generate a payment transaction.
3. The WeChat Pay system verifies the merchant's request, and after the request passes the verification, the system determines that the payment requires the user to input the password.
4. The WeChat Pay system returns the USERPAYING status, and the merchant backend system returns the response to the merchant store's cash register.
5. The WeChat Pay system prompts the user to enter the password in the WeChat app.
6. After receiving the prompt, the user confirms the payment and enters the password.
7. The user inputs the password and submits to WeChat Pay.
8. The WeChat app displays the payment result returned by the WeChat Pay backend system after the user completes the payment, and the WeChat Pay system notifies the user of the payment result in the form of an SMS message or a WeChat message.
9. After the merchant cash register receives the USERPAYING status, the merchant backend system calls the [Query Order API] to query the actual payment result.
10. If the payment result is still USERPAYING, the [Query Order API] will be called every 5 seconds to determine the actual payment result. If the user cancels the payment or fails to complete the payment within 30 seconds, the merchant cash register exits the query process and then calls the [Canceling Order API ] to cancel the payment transaction.
Exception Handling
In case of a payment exception, follow the instructions below.
1. When a system error prompt box appears in the user's WeChat app, the user can view the transaction status in the transaction list. If the order is not found, the merchant needs to initiate a new payment transaction; if successful payment is displayed in the order, the Merchant Cashier System calls the 【Order Query API】again to query the actual payment result.
2. If a payment failure message appears in the user's WeChat app, for example, insufficient balance or invalid credit card number, a new payment needs to be initiated.
3. When the transaction times out or the payment transaction fails, the merchant cashier system must call the 【Cancel Order API】 to cancel this transaction.
4. The Merchant Cashier System shall clearly display the error message to the cashier when the current payment transaction fails due to the abnormal banking system, insufficient funds, unsupported card type, etc.
5. Whether the transaction needs to be canceled is determined according to the error code returned. For details, see the list of error codes returned from the API.
