UnionPay and QuickPass Integration: Channel Messages, Signing, and Reconciliation Files

UnionPay and QuickPass Integration: Channel Messages, Signing, and Reconciliation Files

For domestic collection, Alipay and WeChat Pay usually cover most users, but UnionPay remains mandatory in two situations: enterprise customers and some user segments still prefer paying directly by bank card, and offline acquiring plus online orders need unified settlement. For the product positioning of the UnionPay channel, see China UnionPay.

One warning up front: the integration experience differs substantially from Alipay and WeChat Pay. Messages are form-style key=value strings, signing depends on a merchant certificate, notifications come in front-end and back-end pairs, and reconciliation requires downloading files. Teams integrating for the first time routinely spend more time than expected. For general chain concepts, see the guide to adding Alipay and WeChat Pay to a website.

1. Prerequisites

The merchant structure differs from the other two. UnionPay merchants are typically onboarded through an acquirer or a UnionPay Merchant Services channel rather than self-registering on an open platform. The flow usually looks like this:

1. Submit corporate qualifications through an acquirer for merchant onboarding.
2. Receive a merchant number (merId) and terminal number (terminalId).
3. Apply for and download the merchant certificate, a pfx file containing a private key and a password.
4. Configure front-end and back-end notification URLs and complete integration testing.
5. Activate transaction permissions in the production environment.

The key difference is that the certificate is a file with a password, unlike Alipay's pure string configuration. That file is highly sensitive and belongs in secure key storage, never committed with code.

2. Message Structure and Signing

UnionPay channel requests are key=value&key=value form strings, neither JSON nor XML. Signing works as follows:

1. Concatenate all non-empty parameters in lexicographic order into the string to be signed.
2. Sign with SHA-256 plus RSA using the merchant certificate private key.
3. Base64 and URL-encode the signature value and submit it as the signature field.
4. The receiver verifies with the UnionPay public key.

Four frequent mistakes:

• Empty parameters included in the signature. UnionPay requires empty values to be excluded, and one extra empty field breaks verification.
• Inconsistent encoding. Message encoding must match the encoding used when signing, and Chinese parameters are especially error-prone.
• Wrong environment certificate. Test and production certificates are not interchangeable, and mixing them yields immediate signature errors.
• Timestamp expiry. The time field format in the message must match server time.

3. Front-End and Back-End Notifications

This is the design point that requires the biggest adjustment: two separate notifications exist.

The front-end notification (frontUrl) is where the browser returns after the user pays. It belongs to the user experience layer and is never proof of payment, because users close pages and connections drop.

The back-end notification (backUrl) is the asynchronous result pushed by UnionPay servers, and that is the trustworthy source. Back-end notifications can also be delivered repeatedly and require idempotency.

The correct approach: the front-end return only shows that the payment result is being confirmed, while the true state comes from the back-end notification or an active query. Relying on the front-end return alone reliably produces tickets along the lines of the user paid but the order never shipped.

4. Common Transaction Types

Here is a concept specific to domestic channels: a void is not a refund. A void is generally limited to same-day transactions and leaves the original transaction as if it never happened. A refund reverses an already cleared transaction and generates its own refund record. Cancellation logic must first determine whether the transaction has cleared, or it may call the wrong endpoint.

5. Payment Product Forms

UnionPay online products mainly include:

• Gateway payment: the desktop browser redirects to UnionPay's online banking page, where the user enters card details, covering debit and credit cards.
• WAP payment: mobile browser scenarios.
• Mobile control payment: invoked from a native app.
• UnionPay QR: generates a code the user scans with QuickPass or a bank app.

The selection logic matches the other two providers, decided by the user's environment. Note that gateway payment takes users off your site to UnionPay's page, which fragments the brand experience and affects conversion. If a unified experience matters, QR or control payment fits better.

6. Reconciliation Files and Discrepancy Handling

UnionPay reconciliation is not a table downloaded with one click from a merchant portal like Alipay and WeChat Pay. It typically involves downloading daily reconciliation files from a file server, with access arranged by the acquirer. Files contain every transaction of the day and must be matched against local orders one by one.

Reconciliation does three things:

1. Count and amount check: reconcile total counts and totals first, then compare line by line.
2. State comparison: locally successful but absent at UnionPay suggests a lost order, while present at UnionPay but absent locally suggests a missed order.
3. Discrepancy ledger: record the cause, owner and outcome of every difference to form a traceable log.

For standard reconciliation methodology, see the reconciliation and bill download handbook. This article does not repeat it.

7. Comparison With Alipay and WeChat Pay

Understanding this table saves substantial debugging time: when something breaks, first confirm which ecosystem you are debugging in. Applying Alipay instincts to UnionPay sends you down the wrong path.

8. Launch Checklist

Merchant and terminal numbers are managed centrally; certificate files are encrypted at rest and isolated per environment; empty parameters are filtered before signing; the front-end notification only displays and never posts accounting entries; the back-end notification has an idempotency key and returns the prescribed response; the query endpoint is implemented with timeout fallbacks; reconciliation downloads are scheduled with failure alerting; the discrepancy ledger has defined owners and SLAs.

The WeChat Pay side appears in WeChat Pay APIv3 integration in practice, the Alipay side in Alipay Open Platform integration, and the multi-channel approach in aggregate payment and the service provider model. More options are collected under the Payment category.

Source: 16IDC original. Product capabilities, pricing and eligibility requirements follow open.unionpay.com and related official documentation and contract terms.