支付宝配置

Alipay is one of the most popular payment methods in mainland China, ideal for applications targeting Chinese users.

Setup Steps

Visit Alipay Open Platform
Register with enterprise Alipay account
Complete enterprise verification
Create web/mobile application
Enable "PC Website Payment" capability

Environment Variables

# Alipay Configuration
ALIPAY_APP_ID="your-app-id"                    # Application App ID
ALIPAY_APP_PRIVATE_KEY="your-private-key"      # App private key (Base64 string)
ALIPAY_PUBLIC_KEY="your-alipay-public-key"     # Alipay public key (Base64 string)
ALIPAY_NOTIFY_URL="https://yourdomain.com/api/payment/webhook/alipay"
ALIPAY_SANDBOX="false"                         # Set to "true" for sandbox mode

Key Configuration

Alipay uses pure Base64 string format, no PEM headers needed (-----BEGIN...-----).

Key Types

Key Type	Source	Purpose	Config Variable
App Private Key	Generated by key tool	Sign API requests	`ALIPAY_APP_PRIVATE_KEY`
App Public Key	Generated by key tool	Upload to Alipay	Not needed in config
Alipay Public Key	Returned by Alipay	Verify callback signatures	`ALIPAY_PUBLIC_KEY`

Don't confuse "App Public Key" with "Alipay Public Key"! The App Public Key is yours to upload. The Alipay Public Key is returned by Alipay for signature verification.

Key Format

✅ Correct format (pure Base64 string):
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...

❌ Wrong format (with PEM headers):
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...
-----END PUBLIC KEY-----

Sandbox Testing

Alipay provides a sandbox environment for development testing without real payments.

Enable Sandbox Mode

Set environment variable:
```
ALIPAY_SANDBOX=true
```
Get sandbox credentials from Alipay Sandbox
Use sandbox buyer account for testing

Sandbox Gateway: https://openapi-sandbox.dl.alipaydev.com/gateway.do

Virtual balance, no real charges. Features match production environment.

📖 Reference: Alipay Sandbox Guide

Supported Payment Scenarios

Scenario	Description
PC Website Payment	User redirects to Alipay page to complete payment
Credits Recharge	One-time credit purchase

Configure Pricing

export const paymentConfig = {
  mode: 'one-time',
  defaultProvider: 'alipay',
  oneTimePlans: [
    {
      id: 'monthly-alipay',
      name: 'Monthly Plan',
      price: 9.90,
      currency: 'CNY',
      features: ['All premium features', 'Priority support'],
    }
  ]
}

Plan Configuration Example

config/payment.ts

monthlyAlipay: {
  provider: 'alipay',           // Payment provider
  id: 'monthlyAlipay',          // Unique plan ID
  amount: 0.01,                 // Amount (CNY)
  currency: 'CNY',              // Currency
  duration: {
    months: 1,
    type: 'one_time'            // Alipay only supports one-time payment
  },
  i18n: {
    'en': {
      name: 'Alipay Monthly Plan',
      description: 'Monthly one time pay via Alipay',
      duration: 'month',
      features: ['All premium features', 'Priority support']
    },
    'zh-CN': {
      name: '支付宝月度',
      description: '通过支付宝的月度一次性支付',
      duration: '月',
      features: ['所有高级功能', '优先支持']
    }
  }
}

Payment Flow

User selects plan → Create order → Generate payment form → 
Redirect to Alipay → User login and pay → 
Alipay redirects to returnUrl → Webhook async notification → 
Order status update → Subscription activated

Key Features

Redirect Payment: Uses pageExecute to generate HTML form that auto-submits to Alipay
Sync Return: User redirected to returnUrl after payment
Async Notification: Alipay sends Webhook to notifyUrl, must return success
Order Query: Can actively query order status via queryOrder

Important Notes

Alipay only supports CNY (Chinese Yuan)
Only supports one-time payment and credits, no subscription
Uses PC Website Payment (alipay.trade.page.pay) API
Callback URL must use HTTPS
Key content is sensitive, ensure environment variable security
Webhook must return plain text success or fail, not JSON
Signature verification uses checkNotifySignV2 method

Back to Payment Configuration Overview

Alipay is one of the most popular payment methods in mainland China, ideal for applications targeting Chinese users.

Setup Steps

Visit Alipay Open Platform
Register with enterprise Alipay account
Complete enterprise verification
Create web/mobile application
Enable "PC Website Payment" capability

Environment Variables

# Alipay Configuration
ALIPAY_APP_ID="your-app-id"                    # Application App ID
ALIPAY_APP_PRIVATE_KEY="your-private-key"      # App private key (Base64 string)
ALIPAY_PUBLIC_KEY="your-alipay-public-key"     # Alipay public key (Base64 string)
ALIPAY_NOTIFY_URL="https://yourdomain.com/api/payment/webhook/alipay"
ALIPAY_SANDBOX="false"                         # Set to "true" for sandbox mode

Key Configuration

Alipay uses pure Base64 string format, no PEM headers needed (-----BEGIN...-----).

Key Types

Key Type	Source	Purpose	Config Variable
App Private Key	Generated by key tool	Sign API requests	`ALIPAY_APP_PRIVATE_KEY`
App Public Key	Generated by key tool	Upload to Alipay	Not needed in config
Alipay Public Key	Returned by Alipay	Verify callback signatures	`ALIPAY_PUBLIC_KEY`

Don't confuse "App Public Key" with "Alipay Public Key"! The App Public Key is yours to upload. The Alipay Public Key is returned by Alipay for signature verification.

Key Format

✅ Correct format (pure Base64 string):
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...

❌ Wrong format (with PEM headers):
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgatiwfGM3RTwpedahWmpzO...
-----END PUBLIC KEY-----

Sandbox Testing

Alipay provides a sandbox environment for development testing without real payments.

Enable Sandbox Mode

Set environment variable:
```
ALIPAY_SANDBOX=true
```
Get sandbox credentials from Alipay Sandbox
Use sandbox buyer account for testing

Sandbox Gateway: https://openapi-sandbox.dl.alipaydev.com/gateway.do

Virtual balance, no real charges. Features match production environment.

📖 Reference: Alipay Sandbox Guide

Supported Payment Scenarios

Scenario	Description
PC Website Payment	User redirects to Alipay page to complete payment
Credits Recharge	One-time credit purchase

Configure Pricing

export const paymentConfig = {
  mode: 'one-time',
  defaultProvider: 'alipay',
  oneTimePlans: [
    {
      id: 'monthly-alipay',
      name: 'Monthly Plan',
      price: 9.90,
      currency: 'CNY',
      features: ['All premium features', 'Priority support'],
    }
  ]
}

Plan Configuration Example

config/payment.ts

monthlyAlipay: {
  provider: 'alipay',           // Payment provider
  id: 'monthlyAlipay',          // Unique plan ID
  amount: 0.01,                 // Amount (CNY)
  currency: 'CNY',              // Currency
  duration: {
    months: 1,
    type: 'one_time'            // Alipay only supports one-time payment
  },
  i18n: {
    'en': {
      name: 'Alipay Monthly Plan',
      description: 'Monthly one time pay via Alipay',
      duration: 'month',
      features: ['All premium features', 'Priority support']
    },
    'zh-CN': {
      name: '支付宝月度',
      description: '通过支付宝的月度一次性支付',
      duration: '月',
      features: ['所有高级功能', '优先支持']
    }
  }
}

Payment Flow

User selects plan → Create order → Generate payment form → 
Redirect to Alipay → User login and pay → 
Alipay redirects to returnUrl → Webhook async notification → 
Order status update → Subscription activated

Key Features

Redirect Payment: Uses pageExecute to generate HTML form that auto-submits to Alipay
Sync Return: User redirected to returnUrl after payment
Async Notification: Alipay sends Webhook to notifyUrl, must return success
Order Query: Can actively query order status via queryOrder

Important Notes

Alipay only supports CNY (Chinese Yuan)
Only supports one-time payment and credits, no subscription
Uses PC Website Payment (alipay.trade.page.pay) API
Callback URL must use HTTPS
Key content is sensitive, ensure environment variable security
Webhook must return plain text success or fail, not JSON
Signature verification uses checkNotifySignV2 method

Back to Payment Configuration Overview

Alipay Configuration

Setup Steps

Environment Variables

Key Configuration

Key Types

Key Format

Sandbox Testing

Enable Sandbox Mode

Supported Payment Scenarios

Configure Pricing

Plan Configuration Example

Payment Flow

Key Features

Important Notes

On this page

Alipay Configuration

Setup Steps

Environment Variables

Key Configuration

Key Types

Key Format

Sandbox Testing

Enable Sandbox Mode

Supported Payment Scenarios

Configure Pricing

Plan Configuration Example

Payment Flow

Key Features

Important Notes

On this page