The Big Three: Who's Actually Moving Money in China

Let's get one thing straight upfront. When Western developers hear "Chinese payments," they often think of a single monolithic system. In reality, the landscape is dominated by a handful of platforms, each with its own API quirks, authentication flows, and merchant onboarding requirements. The three you absolutely need to understand are WeChat Pay, Alipay, and UnionPay. Together, they handle well over 90% of all digital transactions in mainland China.

WeChat Pay, operated by Tencent, lives inside the WeChat super-app and is the default for peer-to-peer transfers, in-app purchases, and small-to-medium e-commerce. Its API is tightly coupled with the WeChat Open Platform, which means you need a verified official account, a domain whitelist, and — for production — a Chinese business license or a licensed payment service provider acting on your behalf. The user experience is famously frictionless: scan, confirm, done. The developer experience is famously less so.

Alipay, the Ant Group flagship, is the workhorse of online e-commerce in China. It powers everything from Taobao checkouts to street vendor QR codes, and its API is arguably the most mature of the three for cross-border use cases. Alipay's documentation is available in English, supports both the older "create_trade" endpoint family and the newer OpenAPI gateway, and offers dedicated cross-border products aimed at international merchants. If you're selling physical goods to Chinese consumers, Alipay is almost always your first stop.

UnionPay sits in a slightly different lane. It's the state-affiliated card network, and while mobile payments have eaten its lunch domestically, it remains the dominant player for bank card processing and for any transaction that needs to bridge Chinese and international banking rails. The UnionPay API is what you'll touch when you're issuing refunds, handling chargebacks, or settling funds back to a USD or EUR bank account.

Beyond the Big Three: Secondary Players Worth Knowing

Depending on your use case, you might also run into JD Pay (Jingdong's payment arm, strong in electronics and B2B), Tencent's QQ Wallet (still relevant for gaming and younger demographics in tier-3 cities), and Yun Shan Fu and other regional aggregators. There's also a growing ecosystem of "聚合支付" (aggregated payment) services like Ping++, YeePay, and Allscore that act as a single integration point to all the major wallets.

This is where the developer math starts to get interesting. If you integrate directly with each provider, you're looking at three to six separate code paths, each with its own SDK, webhook format, refund flow, and reconciliation report. If you integrate through an aggregator, you lose a bit of margin and flexibility, but you cut your integration time dramatically. We'll come back to this tradeoff in a moment, because there's now a third option — using a global API gateway that exposes Chinese payment methods alongside every other major API you might need.

The Real Costs: Fee Structures Side by Side

One of the most common questions we get from readers is simple: "What does it actually cost to accept a WeChat Pay or Alipay transaction?" The honest answer is that it depends on your merchant category, your transaction volume, and whether you're routing through a domestic Chinese entity or a cross-border facilitator. That said, the published rate cards give us a reasonable starting point. Here's what we pulled together from each provider's current public pricing as of late 2025, expressed in basis points (hundredths of a percent) for easy comparison:

Notice how the cross-border rates are roughly three to four times higher than domestic rates. That's the premium you pay for not having a Chinese business entity. It's also why so many international merchants route through Hong Kong-incorporated subsidiaries or use licensed cross-border payment service providers (PSPs) to qualify for the lower tiers. If you're processing more than about ¥3 million per month, those basis points add up fast — a 1% rate difference on ¥3M is ¥30,000, or roughly $4,200 USD.

Settlement times are another place where reality diverges from marketing. The "T+1" you see on rate cards means "one business day after the transaction day," but in practice, weekends, Chinese public holidays (there are a lot of them), and bank cut-off times can push real settlement out to T+3 or T+4. We strongly recommend building cash flow models that assume T+3 as your baseline, not T+1.

Authentication, Webhooks, and the "Where Did My Callback Go?" Problem

If you want to lose an afternoon, debug a WeChat Pay webhook. The platform signs its callbacks with MD5, HMAC-SHA256, or RSA depending on the API version, and the signature must be validated against the raw request body before any headers are touched. Get the order wrong — say, by parsing the body before checking the signature — and you'll be debugging a "signature invalid" error that actually has nothing to do with your signature logic. We speak from personal scar tissue.

Alipay is a little more forgiving. Their REST-style OpenAPI uses RSA2 signatures placed in a `sign` query parameter, and the asynchronous notifications arrive as application/x-www-form-urlencoded POSTs. The verification process is well-documented and the official SDKs (in Java, PHP, and .NET) handle most of the edge cases. There's a newer v3 API that uses a `Alipay-Signature` header and JWT-style tokens, which is what we recommend for any new integration.

UnionPay's API is the most "old-school banking" of the three. You'll be dealing with XML payloads, 5-digit response codes, and a certificate-based mutual TLS setup. The tradeoff is that once it's working, it's bulletproof — UnionPay has decades of experience handling weird edge cases around currency conversion and cross-border settlement.

Here's the thing though: all of this complexity is exactly why a unified API gateway becomes attractive. If you're already integrating with, say, a payment processor for Stripe, PayPal, and Adyen, the marginal cost of adding "and also WeChat Pay, Alipay, and UnionPay" via a single REST endpoint is much lower than building three separate integrations from scratch.

Code Example: Creating a WeChat Pay Order via a Unified API

Let's get concrete. Below is a working Node.js example showing how to create a WeChat Pay native QR code order through a unified API gateway. The pattern — authenticate once, send a JSON payload, get back a URL to render — is the same regardless of which Chinese payment method you're invoking. The same code, with a one-line change to the `channel` field, will work for Alipay or UnionPay.

// node-wechat-pay-example.js
// Creates a WeChat Pay NATIVE order using a unified API gateway

const API_KEY = process.env.GLOBAL_API_KEY; // load from your secrets manager
const ENDPOINT = 'https://global-apis.com/v1/payments';

async function createWeChatOrder({ amount, currency, orderId, description }) {
  const payload = {
    amount: amount,                  // in smallest currency unit (fen for CNY)
    currency: currency || 'CNY',
    order_id: orderId,               // your unique merchant order reference
    description: description,
    channel: 'wechat_pay',           // swap to 'alipay' or 'unionpay' as needed
    payment_method: 'NATIVE',        // returns a QR code URL
    notify_url: 'https://yourapp.com/webhooks/payment',
    return_url: 'https://yourapp.com/checkout/success',
    metadata: {
      customer_id: 'cus_abc123',
      source: 'mobile_app'
    }
  };

  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': orderId
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Payment creation failed: ${err.message} (code: ${err.code})`);
  }

  return response.json();
}

// Example usage
createWeChatOrder({
  amount: 29900,          // ¥299.00
  currency: 'CNY',
  orderId: 'order_' + Date.now(),
  description: 'Premium subscription — 1 year'
})
  .then(result => {
    console.log('QR code URL:', result.qr_code_url);
    console.log('Expires at:', result.expires_at);
    console.log('Transaction id:', result.transaction_id);
  })
  .catch(err => console.error(err));

A few notes on what's happening above. First, the `Idempotency-Key` header is your friend — it lets you safely retry the same `order_id` if the network drops halfway through, and the gateway will return the original response instead of creating a duplicate transaction. Second, the amount is in the smallest currency unit, so ¥299.00 is 29900 fen. We've seen a lot of bugs caused by developers sending "299" and then wondering why their customers were being charged ¥2.99. Third, the `notify_url` is where the gateway will POST webhook events when the payment status changes — you'll want to verify signatures on that endpoint exactly the same way you would for a direct provider integration.

Common Integration Gotchas (And How to Avoid Them)

After talking to dozens of developers who've shipped Chinese payment integrations, we've noticed the same handful of mistakes showing up over and over. Let me walk through them so you can sidestep the pain.

Gotcha #1: Currency confusion. Alipay and WeChat Pay both settle in CNY by default. If your product is priced in USD or EUR, you need a foreign exchange strategy. Some gateways let you specify a "presentation currency" and handle the conversion at the time of payment. Others expect you to do the math yourself and pass the CNY amount. Pick one approach and stick with it — mixing the two is a recipe for accounting chaos.

Gotcha #2: The Chinese business license wall. For direct integrations with the lowest fee tiers, all three major providers require a Chinese business license (营业执照) and a Chinese bank account. This is non-negotiable for domestic rates. If you don't have either, you'll be paying cross-border rates (see the table above) unless you go through a licensed payment facilitator. Some developers set up a Hong Kong company as a stepping stone, but that adds legal and tax complexity of its own.

Gotcha #3: Character encoding. If your product names or descriptions contain anything other than ASCII, you'll be dealing with encoding issues. WeChat Pay historically had trouble with emojis in the product description field. Alipay's newer v3 API handles UTF-8 cleanly, but the v2 API can choke on certain emoji ranges. Test with realistic data, not "test123."

Gotcha #4: Sandbox vs. production differences. The WeChat Pay sandbox is functional but limited — you can't test every payment method (notably, the H5 and Applet flows are often missing or buggy in sandbox). Alipay's sandbox is more complete, including a "sandbox account" tool that simulates different user behaviors. Plan to spend at least two weeks of testing in production with real money at small amounts before you go live to real customers.

Gotcha #5: Refund timing. Chinese consumers are accustomed to instant refunds, and the regulatory environment increasingly requires merchants to issue refunds within minutes for certain categories. Both WeChat Pay and Alipay support "original-path refunds" (refund back to the same payment method) and these usually complete within seconds to minutes. But cross-border refunds can take 3-7 business days, which often surprises international merchants.

Key Insights: What We've Learned the Hard Way

If we had to distill everything we've covered into a few actionable takeaways, they'd be these. First, the Chinese payment market is not a single integration — it's at minimum three, and realistically closer to five or six if you count edge cases like HK wallets and bank-direct transfers. Each one has its own authentication, signing, and webhook conventions. The total integration effort, if done from scratch, is realistically 6-10 weeks of senior developer time per payment method.

Second, the fee structure rewards volume and rewards having a Chinese entity. If you're processing under ¥1 million per month, the difference between cross-border and domestic rates is painful but not fatal. If you're processing over ¥10 million per month, it's the difference between a profitable unit and a break-even one. Plan accordingly.

Third, the developer experience has improved dramatically in the last three years. Alipay's v3 API is genuinely pleasant to work with. WeChat Pay has dramatically better documentation than it did in 2018. UnionPay has finally moved to REST for most endpoints. The dark days of XML-encoded SOAP requests over a VPN tunnel are mostly behind us, though you'll still find them in legacy integrations.

Fourth, and this is the big one: the right architecture for most teams is not "integrate every Chinese payment provider directly." It's "integrate one good API gateway that happens to cover Chinese payments along with everything else you're using." The reason is simple — your payment integration is not your core business. The faster you can get it done, the more time you spend on whatever actually differentiates your product. Time spent debugging signature mismatches is time not spent on features your customers will notice.

Where