Transaction Flow

1. On the merchant checkout page, the consumer chooses to pay with WeChat Pay.
2. The merchant/PSP sends PPRO a payment request.
3. PPRO sends the payment request to WeChat.
4. WeChat returns a QR code.
5. The merchant displays the QR code on the PPRO-hosted payment page.
6. The consumer scans the QR code with their WeChat app.
7. They confirm the transaction and enter their payment password.
8. A successful payment message is displayed.

Specific input parameters

For standard input parameters, see Input parameters for the TRANSACTION call.

👍

Note

WeChat Pay Online is available for currencies EUR, GBP, CNY, CHF and USD.

This payment method supports the dynamic descriptor field (see The dynamic descriptor).

Specific output parameters

Specific output parameters for the TRANSACTION call

This payment method will emit the output parameters outlined below:

For standard output parameters, check Output parameters for the TRANSACTION call.

Specific output parameters for the REFUND call

TRANSACTION call input

tag=wechatpay
&txtype=TRANSACTION
&countrycode=CN
&currency=EUR
&amount=1055
&merchanttxid=J2wkc3cdDaJS
&login=johndoe
&password=fsdfgsfer498^%wd
&contractid=JOHNDOECONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fhappylanding.php
&notificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fnotification.php
&specin.dynamicdescriptor=DynDescriptor
&specin.locale=zh-CN
&accountholdername=John%20Doe
&returnmode=urlencodeext

TRANSACTION call output

REQUESTSTATUS=SUCCEEDED  
&STATUS=SUCCEEDED  
&TXID=881495832  
&ERRMSG=  
&CHANNEL=testchannel  
&TAG=wechatpay  
&REDIRECTSECRET=1O2jLKHsCxaHejbQuCOR6nIFpaXKi343  
&SPECOUT_EXPIRYTIMESTAMP=1618842495  
&SPECOUT_PAYMENTPURPOSE=2LUPW10 DynDescriptor  
&SPECOUT_QRCODEURL=weixin://wxpay/bizpayurl?pr=abcdefg  
&SPECOUT_SRCAMOUNT=8274  
&SPECOUT_SRCCURRENCY=CNY  
&SPECOUT.FXRATE:6.59430000  
&SPECOUT.SETTLEMENTAMOUNT: 15  
&SPECOUT.SETTLEMENTCURRENCY: EUR

Additional Information

Notes on CNY Processing

All transactions processed in CNY are settled in USD or EUR. Alipay applies a foreign exchange rate per transaction and settles to us the converted amount in the predetermined settlement currency (USD or EUR). We also settle with you the converted amounts. This means you must track the foreign exchange rate per transaction for reconciliation purposes into the settlement currency (USD or EUR). We provide the foreign exchange rate between CNY and the settlement currency in SPECOUT.FXRATE.

Refunds are handled similarly. The SPECOUT.FXRATE parameter tracks the amount that will be deducted from your settlement. The consumer never pays any foreign exchange costs in none of the cases above. In both cases, you handle the cost through the USD or EUR settlement.

The table below shows the differences between CNY versus like-for-like processing currency.

Examples

The example used below shows a WeChat Pay transaction with USD as the settlement currency.

Table 8. Transaction call example (only key parameters)

Table 9. Succeeded Transaction response example (only key parameters)

In the example above, the consumer will be billed CNY 10.00 and you will be settled USD 1.60.

Table 10. Refund call example (only key parameters)

Table 11. Succeeded Refund response example (only key parameters)

In the sample above, the consumer will be refunded CNY 10.00; you will be debited USD 1.60.

Settlement file examples

Table 12. Volume-per-transaction settlement file

Only the converted amount (USD or EUR) will show in this file.

Table 13. Volume-per-refund settlement file

Only the converted amount (USD or EUR) will show in this file.

Table 14. Aggregate settlement file

Only the converted amount (USD or EUR) will show in this file.

Payment Scenarios

PPRO hosts the QR code

In this scenario, you don't build the logic to render a QR code. You also don't handle the additional logic to redirect the consumer based on a payment success notification from PPRO.

We assume the consumer uses a desktop/laptop/tablet or other large-screen device and is redirected to the PPRO-hosted payment page (via the returned REDIRECTURL).

The consumer can use the WeChat application on a mobile device to scan the payment QR code. The PPRO-hosted payment page automatically redirects the consumer back to the merchant website once the transaction is completed (via the merchantredirecturl; see Specific input parameters for the TRANSACTION call).

You host the QR code

In this scenario, you or the end merchants build the logic to render a QR code. You also handle the additional logic to redirect the consumer based on a payment success notification from PPRO.

We assume the consumer uses a desktop/laptop/tablet or other large-screen device and sees the payment QR code you or the merchant generated via the SPECOUT.QRCODEURL output parameter value. Optionally, you can use the SPECOUT.EXPIRYTIMESTAMP output parameter value to indicate for how long the payment QR code will be valid. To drive consumer behavior appropriately, we recommend showing a running timer.

The consumer can use the WeChat application on a different mobile device to scan the payment QR code. After the consumer pays on their phone, PPRO will send you a notification on the transaction status change. You must inform the merchant and have the consumer redirected to a final landing page (for example, a "thank you" page).

❗️

Caution

Do not poll PPRO for transaction status. Wait for the notification of a status change as the trigger to take further action on the consumer's browser.