Alipay CN

Accept online payments from Alipay China users through your website using the Alipay CN payment method.

Overview

Alipay CN enables merchants to accept payments from customers with Alipay accounts in China. Customers are redirected to Alipay's secure checkout to authorize the payment, then returned to your website upon completion.

Key Features:

• ✅ 1+ billion users - Access China's largest mobile payment platform
• ✅ Cross-border ready - Built for international merchants
• ✅ Secure checkout - Customers authorize on Alipay's platform
• ✅ Instant confirmation - Real-time payment processing
• ✅ Mobile-optimized - QR code for desktop, app redirect for mobile

Replaces Legacy Integration

Alipay CN is the current standard and replaces the legacy "Alipay (Online)" integration.

Supported Regions

Region	Currency	Min Amount	Max Amount	API Version
Thailand	THB	฿20.00	฿150,000.00	2017-11-02
Singapore	SGD	$1.00	$20,000.00	2017-11-02

How It Works

Payment Flow:

1. Customer selects Alipay CN at checkout
2. Create source and charge
3. Redirect customer to authorize_uri
4. Customer authorizes in Alipay app or scans QR code
5. Customer returns to your site
6. Webhook confirms payment status

Typical completion time: 30 seconds - 2 minutes

Implementation

Step 1: Create Source

cURL

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=150000" \
  -d "currency=SGD" \
  -d "type=alipay_cn" \
  -d "platform_type=WEB"

Node.js

const omise = require('omise')({
    secretKey: 'skey_test_YOUR_SECRET_KEY'
});

const source = await omise.sources.create({
    type: 'alipay_cn',
    amount: 150000,
    currency: 'SGD',
    platform_type: 'WEB'  // WEB, iOS, or ANDROID
});

PHP

<?php
$source = OmiseSource::create([
    'type' => 'alipay_cn',
    'amount' => 150000,
    'currency' => 'SGD',
    'platform_type' => 'WEB'
]);
?>

Step 2: Create Charge

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=150000" \
  -d "currency=SGD" \
  -d "return_uri=https://example.com/payment/complete" \
  -d "source=src_test_xxx"

Step 3: Redirect Customer

// Redirect to Alipay authorization page
window.location.href = charge.authorize_uri;

Step 4: Handle Webhook

app.post('/webhooks/omise', (req, res) => {
    const event = req.body;

    if (event.key === 'charge.complete') {
        const charge = event.data;
        if (charge.status === 'successful') {
            fulfillOrder(charge.metadata.order_id);
        }
    }

    res.status(200).send('OK');
});

Charge Status Values

Status	Description
pending	Awaiting customer authorization
successful	Payment completed
failed	Payment failed or declined
expired	Authorization window expired

Failure Codes

Code	Description
payment_expired	Transaction expired
payment_rejected	Payment rejected by issuer
failed_processing	General processing failure
invalid_account	No valid payment account found
insufficient_fund	Insufficient funds or limit reached

Refunds & Voiding

• Void window: 15 minutes (GMT+8) after creation
• Refunds: Supported via Refunds API

Best Practices

1. Detect device - Use platform_type parameter appropriately
2. Handle timeouts - Show clear expiry countdown
3. Webhook first - Don't rely solely on return redirect
4. Clear branding - Show Alipay logo at checkout

FAQ

What is Alipay CN?

Alipay CN is the Chinese version of Alipay, operated by Ant Group. It's China's largest mobile payment platform with over 1 billion users. Alipay CN allows you to accept payments from customers with mainland China Alipay accounts.

What's the difference between Alipay CN and Alipay+?

Alipay CN is specifically for mainland China Alipay users. Alipay+ is a cross-border network that connects multiple wallets (including Alipay CN, Alipay HK, GCash, KakaoPay, etc.). Use Alipay CN if you specifically want to target Chinese customers; use Alipay+ for broader Asian wallet coverage.

What is the platform_type parameter for?

The platform_type parameter (WEB, iOS, ANDROID) optimizes the payment flow for the customer's device. On mobile, it enables deep linking to the Alipay app. On web, it shows a QR code for scanning.

How long does the customer have to complete payment?

The authorization window is limited. If the customer doesn't complete payment within the timeout period, the charge expires. Always implement webhook handling to detect successful payments rather than relying on the return redirect.

Can I refund Alipay CN payments?

Yes, refunds are supported via the Refunds API. You can also void transactions within 15 minutes (GMT+8) of creation.

Why do I need to enable this payment method?

Alipay CN may require additional merchant verification or agreements. Contact support@omise.co to enable Alipay CN for your account.

Related Resources

• Alipay+ Overview - Multi-wallet integration
• Alipay HK - Hong Kong Alipay
• Alipay - Legacy Alipay integration