{"id":6979,"library":"alipay-sdk-python","title":"Alipay SDK for Python","description":"The `alipay-sdk-python` library is the official Python SDK for integrating with Alipay's Open Platform APIs. It provides functionalities for various payment scenarios, including web, app, and QR code payments, as well as refund, query, and notification processing. Maintained by Alipay, it receives regular updates, typically several times a month, reflecting API changes and improvements. The current version is 3.7.1098.","status":"active","version":"3.7.1098","language":"en","source_language":"en","source_url":"https://github.com/alipay/alipay-sdk-python-all","tags":["payment","alipay","sdk","e-commerce","fintech"],"install":[{"cmd":"pip install alipay-sdk-python","lang":"bash","label":"Install the SDK"}],"dependencies":[{"reason":"Required for cryptographic operations, including signature generation and verification.","package":"pycryptodome","optional":false}],"imports":[{"symbol":"AlipayClientConfig","correct":"from alipay.aop.api.AlipayClientConfig import AlipayClientConfig"},{"note":"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.","wrong":"from alipay import AliPay","symbol":"DefaultAlipayClient","correct":"from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient"},{"symbol":"AlipayTradePagePayRequest","correct":"from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest"}],"quickstart":{"code":"import os\nfrom alipay.aop.api.AlipayClientConfig import AlipayClientConfig\nfrom alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient\nfrom alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest\n\n# 1. Configuration (replace with your actual keys or use environment variables)\nAPP_ID = os.environ.get('ALIPAY_APP_ID', 'YOUR_APP_ID')\nAPP_PRIVATE_KEY = os.environ.get('ALIPAY_PRIVATE_KEY', 'YOUR_APP_PRIVATE_KEY')\nALIPAY_PUBLIC_KEY = os.environ.get('ALIPAY_ALIPAY_PUBLIC_KEY', 'YOUR_ALIPAY_PUBLIC_KEY')\n\nalipay_client_config = AlipayClientConfig()\nalipay_client_config.server_url = 'https://openapi.alipaydev.com/gateway.do' # Use 'https://openapi.alipay.com/gateway.do' for production\nalipay_client_config.app_id = APP_ID\nalipay_client_config.app_private_key = APP_PRIVATE_KEY\nalipay_client_config.alipay_public_key = ALIPAY_PUBLIC_KEY\nalipay_client_config.encrypt_type = 'AES' # Optional: set encryption type if needed\n\nalipay_client = DefaultAlipayClient(alipay_client_config=alipay_client_config)\n\n# 2. Prepare API Request\nrequest = AlipayTradePagePayRequest()\nrequest.biz_content = (\n    '{\"out_trade_no\":\"20230817010101001\",'  # Your unique order ID\n    '\"total_amount\":\"88.88\",'             # Total amount\n    '\"subject\":\"Test Product\",'            # Product subject\n    '\"product_code\":\"FAST_INSTANT_TRADE_PAY\"}'\n)\nrequest.return_url = 'http://localhost:8000/alipay/return' # URL for browser redirect after payment\nrequest.notify_url = 'http://localhost:8000/alipay/notify' # URL for async server-to-server notification\n\n# 3. Execute Request and get payment form\ntry:\n    # page_execute returns an HTML form string for browser redirection\n    response_html = alipay_client.page_execute(request=request)\n    print(\"Payment HTML form generated successfully:\")\n    print(response_html) # In a web app, you would render this HTML to the user\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":"< 3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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).","error":"ModuleNotFoundError: No module named 'alipay'"},{"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).","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).","error":"Alipay F21008: 签名验证失败 (Signature verification failed)"},{"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.","cause":"Essential configuration parameters like `app_id` are not provided or are empty when initializing `AlipayClientConfig` or making an API call.","error":"Alipay F40001: Missing Required Arguments: app_id"}]}