Alipay

Alipay is one of the main payment methods in mainland China.

Setup

1. Register on the Alipay Open Platform

   • Go to the Alipay Open Platform
   • Sign in or register with an enterprise Alipay account
   • Finish business verification (business license and related documents)

2. Create an application

   • In the console, create a Web/Mobile App (网页/移动应用)
   • Enable PC website payment (电脑网站支付)
   • Submit the app for review

3. Configure keys

   • Under App details (应用详情) → Development settings (开发设置), configure the keys
   • Use RSA2 (SHA256)
   • Generate an app key pair and store it
   • Upload the application public key to Alipay and copy the Alipay public key (支付宝公钥) that Alipay returns

4. Collect the parameters

   • App ID: the application's unique ID
   • App private key: signs your API requests
   • Alipay public key: verifies signatures on Alipay callbacks

5. Set the callback URL

   • Set the authorization callback in the app settings
   • The URL must be reachable from the public internet

Environment variables

Add these to .env:

# Alipay
ALIPAY_APP_ID=2021000000000000              # App ID

# Keys are raw Base64 strings (no PEM headers)
# App private key: signs API requests (from the key generator)
ALIPAY_APP_PRIVATE_KEY="MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC..."

# Alipay public key: verifies callback signatures.
# This is the key Alipay returns, not your app public key.
ALIPAY_PUBLIC_KEY="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTw..."

# Async notify URL. Must be publicly reachable.
# For local development, use a tunnel.
ALIPAY_NOTIFY_URL=https://yourdomain.com/api/payment/webhook/alipay

# Sandbox (optional, default false)
ALIPAY_SANDBOX=false

The webhook path is https://yourdomain.com/api/payment/webhook/alipay.

Key format

Alipay expects a raw Base64 string. Do not include PEM headers (-----BEGIN...-----).

Where each key comes from

1. App private key

   • Generate it with Alipay's key tool
   • Choose RSA2 (SHA256)
   • Copy the private key as raw Base64

2. Alipay public key

   • Upload your app public key on the Alipay Open Platform
   • Alipay returns an "Alipay public key"
   • Copy that value as raw Base64

Format

Correct (raw Base64):
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...

Incorrect (PEM headers):
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...
-----END PUBLIC KEY-----

Which key goes where

Sandbox

Alipay provides a sandbox so you can test without a real charge.

Turn the sandbox on

1. Set the environment variable

   ALIPAY_SANDBOX=true

2. Get sandbox credentials

   • Open the Alipay sandbox
   • Copy the sandbox App ID and keys
   • Use the sandbox Alipay app or a sandbox buyer account

3. What the sandbox does

   • Gateway: https://openapi-sandbox.dl.alipaydev.com/gateway.do
   • Balances are virtual. Nothing is charged
   • Behavior matches production

Sandbox flow

1. Configure the app with the sandbox App ID
2. Start a payment. The app redirects to the sandbox checkout page
3. Sign in with a sandbox buyer account and pay
4. Confirm the webhook and the order status update

Reference: Alipay sandbox guide

Notes

• Alipay accepts CNY only
• One-time payments and credit packs only. Subscriptions are not supported
• Checkout uses PC website payment (alipay.trade.page.pay). The buyer completes payment on Alipay's page
• The callback URL must be HTTPS
• Keys are secrets. Keep them in environment variables
• The webhook response is plain text success or fail
• Signature checks use checkNotifySignV2

Plan example

amount is in yuan.

monthlyAlipay: {
  provider: 'alipay',
  id: 'monthlyAlipay',          // Each plan needs its own id
  amount: 0.01,                 // Yuan
  currency: 'CNY',
  duration: {
    months: 1,
    type: 'one_time'            // Alipay is one-time only
  },
  i18n: {
    'en': {
      name: 'Alipay Monthly Plan',
      description: 'Monthly one-time payment via Alipay',
      duration: 'month',
      features: ['All premium features', 'Priority support']
    },
  }
}

Payment flow

PC website payment

Buyer selects a plan → order is created → payment form is generated →
redirect to Alipay → buyer signs in and pays →
Alipay redirects to returnUrl → webhook notify →
order status updates → access is granted

What the integration does

• Redirect checkout: pageExecute builds an HTML form that submits to Alipay
• Return URL: after payment, the buyer is sent to returnUrl
• Webhook: Alipay posts to notifyUrl. The handler must respond with success
• Order query: queryOrder can read the order status directly

Back to Payment overview