Skip to main content

Alipay Integration

Alipay is one of China's largest digital payment platforms, offering a comprehensive suite of payment solutions for both online and offline transactions.

Overview​

Alipay (支付宝) is a third-party mobile and online payment platform, established in 2004 by Alibaba Group. It has become the world's largest mobile payment platform, serving over 1.3 billion users globally.

Supported Payment Methods​

Online Payments​

  • Web Payment - Standard web-based payment flow
  • Mobile Web Payment - Optimized for mobile browsers
  • QR Code Payment - Scan-to-pay functionality
  • App Payment - Native mobile app integration

In-Store Payments​

  • Merchant QR Code - Static QR codes for fixed amounts
  • Dynamic QR Code - Variable amount QR codes
  • Barcode Payment - Customer presents barcode to merchant

Integration Requirements​

Prerequisites​

  • Valid Alipay merchant account
  • Alipay API credentials (App ID, Private Key, Public Key)
  • SSL certificate for production environment
  • Compliance with Alipay's security requirements

API Credentials​

{
  "app_id": "your_alipay_app_id",
  "private_key": "your_private_key",
  "public_key": "alipay_public_key",
  "gateway_url": "https://openapi.alipay.com/gateway.do"
}

API Integration​

Create Payment Request​

curl --request POST \
  --url https://api.efundpay.com/v4/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10000,
    "currency": "CNY",
    "payment_method": {
      "method": "alipay",
      "redirect_url": "https://yourdomain.com/return",
      "cancel_url": "https://yourdomain.com/cancel"
    },
    "external_identifier": "order-12345"
  }'

Payment Flow​

  1. Initialize Payment - Create payment request with EFundPay
  2. Redirect to Alipay - User is redirected to Alipay payment page
  3. Payment Processing - User completes payment on Alipay
  4. Return to Merchant - User is redirected back to your site
  5. Webhook Notification - Receive payment status via webhook

Configuration Parameters​

Required Parameters​

  • amount - Payment amount in smallest currency unit (fen for CNY)
  • currency - Currency code (CNY for Chinese Yuan)
  • redirect_url - URL to redirect after successful payment
  • cancel_url - URL to redirect if payment is cancelled

Optional Parameters​

  • subject - Payment description (max 256 characters)
  • body - Detailed payment description
  • timeout_express - Payment timeout period

Response Handling​

Success Response​

{
  "type": "transaction",
  "id": "txn_123456789",
  "status": "processing",
  "payment_url": "https://openapi.alipay.com/gateway.do?...",
  "external_identifier": "order-12345"
}

Webhook Notification​

{
  "ll_transaction_id": "2022012601122644",
  "merchant_transaction_id": "order-12345",
  "payment_data": {
    "payment_status": "SUCCEEDED",
    "payment_amount": "100.00",
    "payment_currency_code": "CNY",
    "payment_time": "20220126141430"
  }
}

Testing​

Sandbox Environment​

  • Use Alipay sandbox credentials for testing
  • Test with Alipay's test accounts
  • Verify webhook notifications in test mode

Test Cards​

Alipay provides test accounts for development:

  • Test Buyer Account: Available in Alipay Developer Console
  • Test amounts: Any amount below 1000 CNY

Security Considerations​

Data Protection​

  • Always use HTTPS for all API communications
  • Store sensitive data encrypted
  • Implement proper session management
  • Follow PCI DSS guidelines if applicable

Fraud Prevention​

  • Implement IP whitelisting
  • Use Alipay's risk control features
  • Monitor transaction patterns
  • Set up alerts for suspicious activities

Common Issues​

Payment Failures​

  • Invalid Amount - Ensure amount is in correct format (fen)
  • Expired Session - Check timeout settings
  • Network Issues - Implement retry logic
  • Invalid Credentials - Verify API keys

Integration Issues​

  • Redirect Loop - Check redirect URL configuration
  • Webhook Not Received - Verify webhook URL and signature
  • Status Mismatch - Implement proper status synchronization

Best Practices​

User Experience​

  • Provide clear payment instructions
  • Show payment progress indicators
  • Handle errors gracefully
  • Offer multiple payment options

Technical Implementation​

  • Implement proper error handling
  • Use webhooks for real-time updates
  • Store transaction references
  • Implement idempotency

Compliance​

  • Follow Alipay's terms of service
  • Comply with local regulations
  • Maintain proper audit trails
  • Regular security assessments

Support​

For technical support with Alipay integration:

  • EFundPay Support - Contact our technical team
  • Alipay Developer Support - Use Alipay's developer resources
  • Documentation - Refer to Alipay's official documentation
Powered by Docusaurus