Alipay HK

Accept online payments from Alipay Hong Kong users through your website using the Alipay HK payment method.

Overview

Alipay HK enables merchants to process payments from Hong Kong residents using their AlipayHK wallet. This payment method allows you to reach Hong Kong consumers without requiring them to have a mainland China Alipay account.

Key Features:

• ✅ Hong Kong users - Reach HK residents directly
• ✅ No China account needed - Works with AlipayHK wallet only
• ✅ Cross-border - Accept HK tourists and online shoppers
• ✅ QR and redirect - Desktop QR or mobile app redirect
• ✅ Secure checkout - Customers authorize on AlipayHK platform

Enablement Required

To activate Alipay HK payments, contact support@omise.co with a feature request.

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

Mobile Flow

Desktop Flow

On desktop, customers scan a QR code using their AlipayHK app instead of being redirected.

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_hk" \
  -d "platform_type=WEB"

Node.js

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

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

PHP

<?php
$source = OmiseSource::create([
    'type' => 'alipay_hk',
    '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"

Combined Request

Create source and charge in one request:

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[type]=alipay_hk" \
  -d "source[platform_type]=WEB"

Step 3: Redirect Customer

// Redirect to AlipayHK 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_rejected	Payment rejected by issuer
failed_processing	General processing error
invalid_account	No valid account found
insufficient_fund	Insufficient funds or limit reached

Refunds & Voiding

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

Best Practices

1. Show AlipayHK branding - Use distinct branding from Alipay CN
2. Detect device - Use appropriate platform_type
3. Handle mobile/desktop - QR for desktop, redirect for mobile
4. Webhook handling - Always verify via webhook

FAQ

What is Alipay HK?

Alipay HK (AlipayHK) is the Hong Kong version of Alipay, designed for Hong Kong residents. It's separate from mainland China Alipay (Alipay CN) and doesn't require a Chinese bank account or identity verification.

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

Alipay HK is for Hong Kong residents and operates in HKD. Alipay CN is for mainland China users and operates in CNY. They are separate wallet systems. If you want to accept both, you need to integrate both payment methods or use Alipay+ which covers both.

Do I need to enable Alipay HK separately?

Yes, Alipay HK requires enablement. Contact support@omise.co to request activation for your merchant account.

How does the payment flow differ on mobile vs desktop?

On mobile devices, customers are redirected to the AlipayHK app to authorize payment. On desktop, a QR code is displayed which customers scan using their AlipayHK app. Set the platform_type parameter appropriately for the best experience.

Can I refund Alipay HK payments?

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

What currencies does Alipay HK support?

Through Omise, Alipay HK supports THB (Thailand) and SGD (Singapore). The payment is processed in these currencies and converted for the Hong Kong customer.

Related Resources

• Alipay+ Overview - Multi-wallet integration
• Alipay CN - Mainland China Alipay
• Alipay - Legacy Alipay integration