alipay-sdk-python

library3.7.1160pypypi✓ verified 84d ago

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.

payments

pip install alipay-sdk-python

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ALIPAY-SDK-PYTHON

alipay-sdk-python

paymentspythonv3.7.1160

Install

30.7s avg

Import

—

Disk

417MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.7.1160 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 390.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 30.7s · import 0.000s · 391MB

417MB installed

● package 417MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AlipayClientConfig

✓ from alipay.aop.api.AlipayClientConfig import AlipayClientConfig

DefaultAlipayClient

✓ from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient

✗ from alipay import AliPay

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

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}")

Debug

Known issues

breakingThe `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.

affects: < 3.0.0

gotchaAlipay 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.

affects: All versions

gotchaIncorrect 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.

affects: All versions

gotchaAlipay'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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'alipay'

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)

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

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.

Upgrade

Version history

3.7.1160latest on PyPI · released May 14, 2026

Audit

Dependencies

pycryptodomerequiredRequired for cryptographic operations, including signature generation and verification.

Agent activity

103 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/alipay/alipay-sdk-python-all ↗

packagehttps://pypi.org/project/alipay-sdk-python/ ↗

homepagehttps://open.alipay.com ↗