Alipay SDK for Python

Common errors

• ModuleNotFoundError: No module named 'alipay'

  cause Attempting to import classes from `alipay` directly (e.g., `from alipay import AliPay`) which was the import path for older versions of the SDK (v2.x and below).
  fix Update your imports to use the new package structure, primarily `from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient` and `from alipay.aop.api.AlipayClientConfig import AlipayClientConfig`. Refer to the quickstart example.

• Alipay F21008: 签名验证失败 (Signature verification failed)

  cause This error indicates a mismatch in the cryptographic keys used for signing the request or verifying the response. Common causes include incorrect `app_private_key`, `alipay_public_key`, or `app_id`, or an incorrect key format (e.g., not PKCS8, or containing headers/footers).
  fix Double-check your `APP_ID`, `APP_PRIVATE_KEY`, and `ALIPAY_PUBLIC_KEY` in your configuration. Ensure the private key is in PKCS8 format without headers/footers. Also, confirm you are using the correct keys for the specified Alipay environment (sandbox vs. production).

• Alipay F40001: Missing Required Arguments: app_id

  cause Essential configuration parameters like `app_id` are not provided or are empty when initializing `AlipayClientConfig` or making an API call.
  fix Ensure that `alipay_client_config.app_id` is set to your actual Alipay App ID. Review all required configuration parameters for the `AlipayClientConfig` and for the specific API request you are making, as some `biz_content` fields might also be mandatory.

Warnings

• breaking The `alipay-sdk-python` library underwent a significant API refactor around version 3.0.0. Older versions (2.x and below) used a different package structure and client initialization pattern (e.g., `from alipay import AliPay`). Version 3.x and above use `from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient`.
  Fix: Update your import paths and client initialization logic to match the 3.x API. Refer to the official documentation or the quickstart for the correct patterns.
• gotcha Alipay private keys must be in PKCS8 format without headers/footers (`-----BEGIN RSA PRIVATE KEY-----` / `-----END RSA PRIVATE KEY-----`). If your private key is generated with headers, you must remove them before providing it to the SDK, or convert it to PKCS8.
  Fix: Ensure your `app_private_key` value is a plain string containing only the base64 encoded private key material. For example, if you have a key file, open it, copy only the content between `BEGIN` and `END` lines, and remove all newlines.
• gotcha Incorrect configuration of `server_url` or mismatch between keys (App Private Key / Alipay Public Key) and the environment (sandbox vs. production) is a frequent cause of 'Signature verification failed' errors or other API communication issues.
  Fix: Verify that `alipay_client_config.server_url` points to the correct environment (`https://openapi.alipaydev.com/gateway.do` for sandbox, `https://openapi.alipay.com/gateway.do` for production) and that the corresponding `app_id`, `app_private_key`, and `alipay_public_key` are valid for that environment.
• gotcha Alipay's asynchronous notifications (`notify_url`) require strict signature verification to prevent spoofing. Failing to correctly verify the signature on incoming notifications can lead to security vulnerabilities.
  Fix: Always use the SDK's built-in signature verification utility (e.g., `alipay_client.verify_notification`) when processing `notify_url` callbacks. Do not manually parse or trust notification data without verification.

Install

• pip install alipay-sdk-python Install the SDK

Imports

• AlipayClientConfig

  from alipay.aop.api.AlipayClientConfig import AlipayClientConfig

• DefaultAlipayClient
  wrong:

  from alipay import AliPay

  correct:

  from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient

  This import path was used in older `alipay-sdk-python` versions (2.x and earlier) and is not compatible with the 3.x series and above.
• AlipayTradePagePayRequest

  from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest

Quickstart

This quickstart demonstrates how to initialize the Alipay client and create a basic web page payment request. It configures the client with essential keys and a sandbox server URL, then constructs a `AlipayTradePagePayRequest` to generate an HTML form string for redirecting the user to Alipay for payment. Remember to replace placeholder keys with your actual Alipay developer credentials and adjust the `server_url` for production.

import os
from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest

# 1. Configuration (replace with your actual keys or use environment variables)
APP_ID = os.environ.get('ALIPAY_APP_ID', 'YOUR_APP_ID')
APP_PRIVATE_KEY = os.environ.get('ALIPAY_PRIVATE_KEY', 'YOUR_APP_PRIVATE_KEY')
ALIPAY_PUBLIC_KEY = os.environ.get('ALIPAY_ALIPAY_PUBLIC_KEY', 'YOUR_ALIPAY_PUBLIC_KEY')

alipay_client_config = AlipayClientConfig()
alipay_client_config.server_url = 'https://openapi.alipaydev.com/gateway.do' # Use 'https://openapi.alipay.com/gateway.do' for production
alipay_client_config.app_id = APP_ID
alipay_client_config.app_private_key = APP_PRIVATE_KEY
alipay_client_config.alipay_public_key = ALIPAY_PUBLIC_KEY
alipay_client_config.encrypt_type = 'AES' # Optional: set encryption type if needed

alipay_client = DefaultAlipayClient(alipay_client_config=alipay_client_config)

# 2. Prepare API Request
request = AlipayTradePagePayRequest()
request.biz_content = (
    '{"out_trade_no":"20230817010101001",'  # Your unique order ID
    '"total_amount":"88.88",'             # Total amount
    '"subject":"Test Product",'            # Product subject
    '"product_code":"FAST_INSTANT_TRADE_PAY"}'
)
request.return_url = 'http://localhost:8000/alipay/return' # URL for browser redirect after payment
request.notify_url = 'http://localhost:8000/alipay/notify' # URL for async server-to-server notification

# 3. Execute Request and get payment form
try:
    # page_execute returns an HTML form string for browser redirection
    response_html = alipay_client.page_execute(request=request)
    print("Payment HTML form generated successfully:")
    print(response_html) # In a web app, you would render this HTML to the user
except Exception as e:
    print(f"An error occurred: {e}")