Alipay Components¶

This directory contains various Alipay payment and subscription service components, providing comprehensive payment processing, subscription management, and transaction query functionality.

📋 Component List¶

1. Payment Components¶

MobileAlipayPayment - Mobile Alipay Payment¶

Alipay payment component for mobile browsers, supporting mobile app redirection and in-browser payments.

Prerequisites:

Valid Alipay application configuration
Alipay merchant account and API keys
Mobile browser environment

Input Parameters (MobilePaymentInput):

out_trade_no (str): Merchant order number
order_title (str): Order title
total_amount (float): Payment amount (in yuan, must be greater than 0)

Output Parameters (PaymentOutput):

result (str): Markdown text containing payment link

Key Features:

Uses QUICK_WAP_WAY product code
Supports Alipay app redirection payment
Supports direct in-browser payment
Returns ready-to-use payment links

WebPageAlipayPayment - Desktop Web Alipay Payment¶

Alipay payment component for desktop browsers, providing QR code scanning payment functionality.

Prerequisites:

Valid Alipay application configuration
Alipay merchant account and API keys
Desktop browser environment

Input Parameters (WebPagePaymentInput):

out_trade_no (str): Merchant order number
order_title (str): Order title
total_amount (float): Payment amount (in yuan, must be greater than 0)

Output Parameters (PaymentOutput):

result (str): Markdown text containing payment link

Key Features:

Uses FAST_INSTANT_TRADE_PAY product code
Supports QR code scanning payment
Suitable for desktop websites

2. Transaction Management Components¶

AlipayPaymentQuery - Payment Transaction Query¶

Query the current status and detailed information of created Alipay transaction orders.

Input Parameters (PaymentQueryInput):

out_trade_no (str): Merchant order number

Output Parameters (PaymentOutput):

result (str): Text containing transaction status, amount, Alipay transaction number, and other information

Key Functions:

Retrieve transaction details
Support status validation and synchronization

AlipayPaymentRefund - Payment Transaction Refund¶

Initiate refund requests for successfully paid transactions, supporting full and partial refunds.

Input Parameters (PaymentRefundInput):

out_trade_no (str): Merchant order number
refund_amount (float): Refund amount (must be greater than 0)
refund_reason (str, optional): Refund reason
out_request_no (str, optional): Identifier for a refund request, must be unique under the transaction number. Required for partial refunds

Output Parameters (PaymentOutput):

result (str): Text containing refund result information

Key Functions:

Support full and partial refunds
Refund idempotency guarantee

AlipayRefundQuery - Refund Query¶

Query the current status and processing results of initiated refund requests.

Input Parameters (RefundQueryInput):

out_trade_no (str): Merchant order number
out_request_no (str): Refund request number

Output Parameters (PaymentOutput):

result (str): Text containing refund status and amount information

Key Functions:

Query refund processing status
Retrieve refund details
Support refund status validation

3. Subscription Service Components¶

AlipaySubscribeStatusCheck - Subscription Status Check¶

Check user’s agent subscription status, returning membership information and package details.

Input Parameters (SubscribeStatusCheckInput):

uuid (str): Account ID

Output Parameters (SubscribeStatusOutput):

subscribe_flag (bool): Whether subscribed
subscribe_package (str): Subscription package description

Key Functions:

Check user membership status
Return package validity period or remaining usage count

AlipaySubscribePackageInitialize - Subscription Initialization¶

Generate subscription package purchase links for users to enable subscription services.

Input Parameters (SubscribePackageInitializeInput):

uuid (str): Account ID

Output Parameters (SubscribePackageInitializeOutput):

subscribe_url (str): Subscription purchase link (if not subscribed)

Key Functions:

Generate subscription purchase links
Support both time-based and usage-based subscription models

AlipaySubscribeTimesSave - Subscription Usage Tracking¶

Record user’s usage count of agent services for pay-per-use deduction.

Input Parameters (SubscribeTimesSaveInput):

uuid (str): Account ID
out_request_no (str): External request number (for idempotency control)

Output Parameters (SubscribeTimesSaveOutput):

success (bool): Whether the usage tracking service call was successful

Key Functions:

Pay-per-use deduction
Support idempotent operations

AlipaySubscribeCheckOrInitialize - Subscription Check or Initialize¶

One-stop subscription service component that automatically checks user subscription status and returns purchase links if not subscribed.

Input Parameters (SubscribeCheckOrInitializeInput):

uuid (str): Account ID

Output Parameters (SubscribeCheckOrInitializeOutput):

subscribe_flag (bool): Whether subscribed
subscribe_url (str): Subscription link (if not subscribed)

Key Functions:

Automatically check subscription status
Auto-generate purchase links if not subscribed
Simplify business logic handling

🔧 Environment Variable Configuration¶

Environment Variable	Required	Default Value	Description
`ALIPAY_APP_ID`	✅	-	Alipay application ID
`ALIPAY_PRIVATE_KEY`	✅	-	Application private key
`ALIPAY_PUBLIC_KEY`	✅	-	Alipay public key
`ALIPAY_GATEWAY`	❌	https://openapi.alipay.com/gateway.do	Alipay gateway address
`AP_RETURN_URL`	❌	-	Payment completion callback URL
`AP_NOTIFY_URL`	❌	-	Payment asynchronous notification URL
`SUBSCRIBE_PLAN_ID`	✅	-	Subscription plan ID
`X_AGENT_NAME`	✅	-	Agent name
`USE_TIMES`	❌	1	Usage count deducted per use

🚀 Usage Examples¶

Basic Payment Example¶

from agentscope_runtime.tools.alipay.payment import (
    MobileAlipayPayment,
    WebPageAlipayPayment
)
import asyncio

# Mobile payment
mobile_payment = MobileAlipayPayment()
webpage_payment = WebPageAlipayPayment()

async def mobile_payment_example():
    result = await mobile_payment.arun({
        "out_trade_no": "ORDER_20241218_001",
        "order_title": "AI Agent Service",
        "total_amount": 99.99
    })
    print("Mobile payment link:", result.result)

async def webpage_payment_example():
    result = await webpage_payment.arun({
        "out_trade_no": "ORDER_20241218_002",
        "order_title": "AI Agent Premium Service",
        "total_amount": 199.99
    })
    print("Web payment link:", result.result)

asyncio.run(mobile_payment_example())
asyncio.run(webpage_payment_example())

Transaction Management Example¶

from agentscope_runtime.tools.alipay.payment import (
    AlipayPaymentQuery,
    AlipayPaymentRefund,
    AlipayRefundQuery
)

query_component = AlipayPaymentQuery()
refund_component = AlipayPaymentRefund()
refund_query_component = AlipayRefundQuery()

async def transaction_management_example():
    # Query payment status
    query_result = await query_component.arun({
        "out_trade_no": "ORDER_20241218_001"
    })
    print("Transaction status:", query_result.result)

    # Initiate refund
    refund_result = await refund_component.arun({
        "out_trade_no": "ORDER_20241218_001",
        "refund_amount": 50.0,
        "refund_reason": "User requested refund"
    })
    print("Refund result:", refund_result.result)

    # Query refund status
    refund_query_result = await refund_query_component.arun({
        "out_trade_no": "ORDER_20241218_001",
        "out_request_no": "ORDER_20241218_001_refund_1734509344"
    })
    print("Refund status:", refund_query_result.result)

asyncio.run(transaction_management_example())

Subscription Service Example¶

from agentscope_runtime.tools.alipay.subscribe import (
    AlipaySubscribeStatusCheck,
    AlipaySubscribePackageInitialize,
    AlipaySubscribeTimesSave,
    AlipaySubscribeCheckOrInitialize
)

status_check = AlipaySubscribeStatusCheck()
initialize = AlipaySubscribePackageInitialize()
times_save = AlipaySubscribeTimesSave()
check_or_init = AlipaySubscribeCheckOrInitialize()

async def subscription_example():
    user_uuid = "user_12345"

    # Check subscription status
    status = await status_check.arun({"uuid": user_uuid})
    print(f"Subscription status: {status.subscribe_flag}")
    if status.subscribe_flag:
        print(f"Package info: {status.subscribe_package}")

    # If not subscribed, get subscription link
    if not status.subscribe_flag:
        init_result = await initialize.arun({"uuid": user_uuid})
        if init_result.subscribe_url:
            print(f"Subscription link: {init_result.subscribe_url}")

    # Track usage after service use
    if status.subscribe_flag:
        times_result = await times_save.arun({
            "uuid": user_uuid,
            "out_request_no": "user_12345_20241218_001",
        })
        print(f"Usage tracking result: {times_result.success}")

async def one_step_subscription_example():
    user_uuid = "user_67890"

    # One-step subscription check or initialization
    result = await check_or_init.arun({"uuid": user_uuid})

    if result.subscribe_flag:
        print("User is subscribed, can use service")
    else:
        print(f"User not subscribed, subscription link: {result.subscribe_url}")

asyncio.run(subscription_example())
asyncio.run(one_step_subscription_example())

🏗️ Architecture Features¶

Payment Flow¶

Payment Link Generation: Choose appropriate payment method based on device type
User Payment: User completes payment through payment link
Status Query: Query payment status, confirm transaction results
Post-processing: Perform refunds and other operations as needed

Subscription Models¶

Time-based Subscription: Users purchase service permissions for a specific time period
Usage-based Subscription: Users purchase a specific number of service uses

📦 Dependencies¶

alipay-sdk-python: Official Alipay Python SDK
cryptography: Encryption-related operations

⚠️ Usage Notes¶

Configuration Security¶

Use environment variables to store sensitive configuration information
Properly safeguard application private keys, do not expose them in code repositories
Merchants or service providers can integrate this product through various methods based on actual situations. For details, refer to https://opendocs.alipay.com/open/203/107084?pathHash=a33de091
For subscription-related configuration, refer to https://opendocs.alipay.com/solution/0i40x9?pathHash=29e2835d