UnionPay
Channel Overview
UnionPay (also known as Cloud QuickPass / Yunshanfu) is the all-channel payment service of China UnionPay, integrated directly via the UnionPay All-Channel Payment Platform (95516.com) ACP gateway. DaxPay supports the UnionPay direct gateway, covering QR scan, H5, and barcode (merchant-scan) scenarios.
UnionPay (Cloud QuickPass, channel
union_pay) and UMS (UnionPay Merchant Services, channelums_pay) are two independent channels — they differ in signature method, message format, gateway, and products. See Difference from UMS below.
Payment Products
A single product union_pay — no product selection is needed when creating the channel merchant; the sandbox/production environment is decided by the payment product configuration.
Supported Payment Methods
- UnionPay QR (scan): Returns a QR link; the user scans it with the QuickPass App (
union_qr) - UnionPay H5: Redirects via a front-end form submission in a mobile browser (
union_h5) - UnionPay barcode (merchant-scan): The merchant scans the user's QuickPass barcode (
union_barcode)
JSAPI not implemented
union_jsapi (UnionPay JSAPI) is enum-only and not yet implemented in the direct gateway channel. For UnionPay payments within an Official Account / mini-program, use an aggregate channel (e.g. Adapay, Lakala) instead.
Configuration Structure
- Create the channel merchant: Merchant Workbench → Channel Merchants → Create, pick the product and fill in merchant name + UnionPay merchant number (merId);
- Configure keys (Channel Merchant Detail → Key Configuration, group "Merchant certificate configuration"):
| Field | Notes |
|---|---|
| Environment | Production / sandbox |
| UnionPay merchant number | merId |
| Signature type | Certificate signing (RSA2, fixed) |
| Private-key certificate | PKCS12 (.pfx), Base64 |
| Certificate password | Password of the PKCS12 file |
| Intermediate certificate | X.509 DER, Base64 |
| Root certificate | X.509 DER, Base64 |
The UnionPay gateway uses RSA2 certificate signing (signMethod=01, SHA256withRSA). Messages are application/x-www-form-urlencoded (not JSON); all three certificates are required.
Callback Handling
- Supports both synchronous return and async notification
- Async notifications are
form-urlencodedparameters; verify the signature with the UnionPay public-key certificate - After verification, take
queryIdas the channel order number; refund callbacks reference the original transaction viaorigQryId - The callback URL must be configured in the UnionPay merchant portal and be publicly accessible
Notes
- Gateway endpoints: sandbox
test.95516.com/ production95516.com - Keep the private-key certificate secure and renew it before expiry; an expired certificate breaks signing
- Merchant-scan barcodes are identified by the
authCodeprefix (UnionPay62) and mapped tounion_barcodebefore routing - Some capabilities require separate activation with UnionPay
Difference from UMS (UnionPay Merchant Services)
UnionPay (Cloud QuickPass) and UMS are often confused, but they are entirely different channels:
| Dimension | UnionPay (Cloud QuickPass) | UMS |
|---|---|---|
| Channel code | union_pay | ums_pay |
| Counterparty | China UnionPay All-Channel Platform (95516.com) | UnionPay Merchant Services Co. portal |
| Signature | RSA2 certificate signing (PKCS12 private key + intermediate/root certs) | HmacSHA256, no certificate (appKey + secretKey) |
| Message format | form-urlencoded | JSON |
| Products | Single product, 3 methods (QR / H5 / barcode) | 6 products (C-scan-B / Official Account / APP / Mini-program / H5 / B-scan-C) |
Which to choose
- UnionPay (Cloud QuickPass): Direct to the China UnionPay gateway, direct settlement. Best when you need native QuickPass QR / barcode payments.
- UMS: Acquiring via UnionPay Merchant Services; supports all-channel cashier including bank card / gateway / express pay, with richer onboarding options.