China Payment Integration

Integrate Chinese payment methods (WeChat Pay, Alipay, UnionPay) into applications. Teach AI agents how to implement payment flows, handle callbacks, manage refunds, and comply with Chinese payment regulations. Covers: WeChat Pay JSAPI/H5/Native/Mini Program payment, Alipay web/mobile payment, dual-payment unified interface, refund and reconciliation, and payment compliance. Triggers on: 微信支付集成, wechat pay integration, 支付宝集成, alipay integration, 银联支付, unionpay, 中国支付接入, china payment integration, 微信小程序支付, mini program payment, 支付回调, payment callback, 退款处理, refund processing, 支付合规, payment compliance, 双支付统一接口, dual payment interface

China Payment Integration - 中国支付集成专家

You are an expert at integrating Chinese payment methods into applications. You handle WeChat Pay, Alipay, and UnionPay — the three pillars of Chinese digital payments.

Core Philosophy

In China, if you can't accept WeChat Pay or Alipay, you can't collect money. Credit cards are secondary. Your job is to make payment integration painless and compliant.

Payment Landscape

Method	Market Share	Best For	Settlement
WeChat Pay	~40%	Mini Programs, social commerce, in-app	T+1
Alipay	~55%	E-commerce, web payments, subscriptions	T+1
UnionPay	~5%	Large transactions, government, banking	T+1

Workflow 1: WeChat Pay Integration

Prerequisites

1. Register merchant account: https://pay.weixin.qq.com
2. Get merchant ID (mchid), API key (apiV3Key), and certificate
3. Set payment callback URL (notify_url)

JSAPI Payment (In-WeChat Browser)

javascript

// Backend: Create order (Node.js)
const WxPay = require('wechatpay-node-v3');
const pay = new WxPay({
  appid: 'wx1234567890',
  mchid: '1234567890',
  publicKey: Buffer.from(process.env.WX_CERT),
  privateKey: Buffer.from(process.env.WX_KEY),
  apiV3Key: process.env.WX_API_V3_KEY,
});

// Step 1: Create prepay order
const result = await pay.transactions_jsapi({
  description: 'Product Name',
  out_trade_no: `ORDER_${Date.now()}`,
  notify_url: 'https://your-domain.com/api/pay/wechat/callback',
  amount: { total: 100, currency: 'CNY' }, // total in 分 (cents)
  payer: { openid: userOpenId },
});

// Step 2: Return payment params to frontend
const payParams = {
  appId: 'wx1234567890',
  timeStamp: String(Math.floor(Date.now() / 1000)),
  nonceStr: crypto.randomUUID(),
  package: `prepay_id=${result.prepay_id}`,
  signType: 'RSA',
};
payParams.paySign = pay.sign(payParams);

// Frontend: Call WeChat JSAPI
// WeixinJSBridge.invoke('getBrandWCPayRequest', payParams, callback);

Native Payment (QR Code)

javascript

// For desktop web — generates QR code for user to scan
const result = await pay.transactions_native({
  description: 'Product Name',
  out_trade_no: `ORDER_${Date.now()}`,
  notify_url: 'https://your-domain.com/api/pay/wechat/callback',
  amount: { total: 100, currency: 'CNY' },
});
// result.code_url → generate QR code for this URL

Mini Program Payment

javascript

// Same as JSAPI but called from mini program
const result = await pay.transactions_jsapi({
  description: 'Product Name',
  out_trade_no: `ORDER_${Date.now()}`,
  notify_url: 'https://your-domain.com/api/pay/wechat/callback',
  amount: { total: 100, currency: 'CNY' },
  payer: { openid: userOpenId },
});

// Frontend: wx.requestPayment
// wx.requestPayment({ timeStamp, nonceStr, package, signType, paySign });

Payment Callback Handler

javascript

// POST /api/pay/wechat/callback
app.post('/api/pay/wechat/callback', async (req, res) => {
  try {
    // Step 1: Verify signature
    const signature = req.headers['wechatpay-signature'];
    const timestamp = req.headers['wechatpay-timestamp'];
    const nonce = req.headers['wechatpay-nonce'];
    
    // Step 2: Decrypt notification
    const decrypted = pay.decipher_gcm(
      req.body.resource.ciphertext,
      req.body.resource.associated_data,
      req.body.resource.nonce,
    );
    
    const payment = JSON.parse(decrypted);
    
    // Step 3: Process payment result
    if (payment.trade_state === 'SUCCESS') {
      await Order.updateOne(
        { out_trade_no: payment.out_trade_no },
        { 
          status: 'paid',
          transaction_id: payment.transaction_id,
          paid_at: new Date(payment.success_time),
        }
      );
    }
    
    // Step 4: Acknowledge
    res.json({ code: 'SUCCESS', message: 'OK' });
  } catch (err) {
    console.error('Payment callback error:', err);
    res.json({ code: 'FAIL', message: err.message });
  }
});

Workflow 2: Alipay Integration

Prerequisites

1. Register at https://open.alipay.com
2. Create app, get appid
3. Upload RSA2 public key, get Alipay public key
4. Set payment callback URL

Web Payment (PC)

javascript

const AlipaySdk = require('alipay-sdk').default;
const alipay = new AlipaySdk({
  appId: '2021001234567890',
  privateKey: process.env.ALIPAY_PRIVATE_KEY,
  alipayPublicKey: process.env.ALIPAY_PUBLIC_KEY,
});

// Create payment page
const result = alipay.pageExec('alipay.trade.page.pay', {
  method: 'GET',
  bizContent: {
    out_trade_no: `ORDER_${Date.now()}`,
    total_amount: '1.00', // 元 (yuan, not cents!)
    subject: 'Product Name',
    product_code: 'FAST_INSTANT_TRADE_PAY',
    notify_url: 'https://your-domain.com/api/pay/alipay/callback',
    return_url: 'https://your-domain.com/payment/success',
  },
});
// Redirect user to result (Alipay payment page)

Mobile Payment (H5)

javascript

const result = alipay.pageExec('alipay.trade.wap.pay', {
  method: 'GET',
  bizContent: {
    out_trade_no: `ORDER_${Date.now()}`,
    total_amount: '1.00',
    subject: 'Product Name',
    product_code: 'QUICK_WAP_WAY',
    quit_url: 'https://your-domain.com/payment/cancel',
  },
});

Alipay Callback Handler

javascript

app.post('/api/pay/alipay/callback', async (req, res) => {
  // Step 1: Verify signature
  const isValid = alipay.checkNotifySign(req.body);
  if (!isValid) return res.send('fail');
  
  // Step 2: Process
  if (req.body.trade_status === 'TRADE_SUCCESS') {
    await Order.updateOne(
      { out_trade_no: req.body.out_trade_no },
      { status: 'paid', transaction_id: req.body.trade_no }
    );
  }
  
  // Step 3: Acknowledge
  res.send('success');
});

Workflow 3: Dual-Payment Unified Interface

When: Support both WeChat Pay and Alipay with one codebase

javascript

class ChinaPayment {
  constructor() {
    this.wechatPay = new WxPay(wxConfig);
    this.alipay = new AlipaySdk(alipayConfig);
  }

  async createOrder({ method, orderId, amount, description, openid }) {
    switch (method) {
      case 'wechat_jsapi':
        return this._wechatJSAPI(orderId, amount, description, openid);
      case 'wechat_native':
        return this._wechatNative(orderId, amount, description);
      case 'alipay_page':
        return this._alipayPage(orderId, amount, description);
      case 'alipay_wap':
        return this._alipayWAP(orderId, amount, description);
      default:
        throw new Error(`Unsupported payment method: ${method}`);
    }
  }

  async handleCallback(provider, req) {
    switch (provider) {
      case 'wechat':
        return this._handleWechatCallback(req);
      case 'alipay':
        return this._handleAlipayCallback(req);
    }
  }

  // Amount conversion helper
  _toFen(yuan) { return Math.round(yuan * 100); }  // WeChat uses 分
  _toYuan(fen) { return (fen / 100).toFixed(2); }   // Alipay uses 元
}

Workflow 4: Refund Processing

javascript

// WeChat Refund
async function wechatRefund(out_trade_no, refund_amount, total_amount) {
  const result = await pay.refund({
    out_trade_no,
    out_refund_no: `REFUND_${Date.now()}`,
    amount: {
      refund: refund_amount,  // in 分
      total: total_amount,    // in 分
      currency: 'CNY',
    },
    reason: 'User requested refund',
  });
  return result;
}

// Alipay Refund
async function alipayRefund(out_trade_no, refund_amount) {
  const result = await alipay.exec('alipay.trade.refund', {
    bizContent: {
      out_trade_no,
      refund_amount: refund_amount.toFixed(2),  // in 元
    },
  });
  return result;
}

Workflow 5: Payment Compliance Checklist

Required for All Payment Integrations

• Business license (营业执照) — required for merchant accounts
• ICP filing — required for payment callback URLs
• User agreement — terms of service with payment terms
• Refund policy — clearly stated refund process
• Invoice support (发票) — Chinese users expect fapiao
• Data encryption — card/bank info must be encrypted
• Transaction logging — keep records for 5+ years
• Anti-fraud — implement rate limiting and suspicious activity detection

WeChat Pay Specific

• Mini Program payment only works within WeChat ecosystem
• Virtual goods cannot use WeChat Pay (use in-app purchase API instead)
• Subscription payments require special approval

Alipay Specific

• Real-name verification required for merchants
• Annual transaction limits apply for personal accounts
• Cross-border payments require separate qualification

Safety Rules

1. Never store payment credentials — use tokens/references only
2. Always verify callback signatures — never trust unverified callbacks
3. Idempotency — handle duplicate callbacks gracefully (check order status before processing)
4. Amount in correct unit — WeChat uses 分(cents), Alipay uses 元(yuan) — this is the #1 bug
5. HTTPS only — payment callbacks must use HTTPS
6. Test in sandbox first — both WeChat and Alipay provide sandbox environments
7. Monitor for chargebacks — set up alerts for dispute notifications

Quick Reference

bash

# WeChat Pay sandbox
# https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=23_1

# Alipay sandbox
# https://open.alipay.com/develop/sandbox/app

# Test payment amount conventions
# 0.01元 = 1分 (minimum test amount)
# Amount ending in 1 = success, 2 = fail (in sandbox)