Overview

The AlipayPlus MCP Server exposes Ant International’s AlipayPlus payment APIs as Model Context Protocol (MCP) compatible tools so AI assistants can perform payment and refund workflows directly from conversational flows. By implementing a standardized MCP server, this project converts AlipayPlus REST operations (create payment, query transactions, refunds, customs declarations) into callable tools that conform to MCP semantics and lifecycle.

This server is designed for developer teams building assistants that need to initiate payments, verify transaction status, or handle refunds without embedding payment logic into the model itself. It handles request signing, response verification, and callback wiring so your assistant can focus on business logic while the MCP server manages the payment protocol, keys, and gateway details.

Features

Payment lifecycle:
- create_payment — create and return payment requests / URLs
- query_payment — fetch transaction status and metadata
- cancel_payment — attempt to cancel pending payments
Refund operations:
- create_refund — initiate full or partial refunds on completed transactions
Customs and settlement:
- customs_declare — submit or update customs declarations for cross-border payments
- query_customs_declare — check customs declaration status
Security:
- RSA signing of requests and verification of AlipayPlus responses
MCP integration:
- Implements MCP tool contracts so assistants can call payment functions during a chat

Installation / Configuration

Prerequisites:

Python 3.11+
Valid AlipayPlus merchant credentials (CLIENT_ID, MERCHANT_PRIVATE_KEY, ALIPAY_PUBLIC_KEY)
A reachable PAYMENT_NOTIFY_URL for asynchronous callbacks

Install via uvx (recommended):

uvx ant-intl-alipayplus-mcp

Install with pip:

pip install ant-intl-alipayplus-mcp

Install with uv:

uv install ant-intl-alipayplus-mcp

Install from source:

git clone https://github.com/alipay/global-alipayplus-mcp.git
cd global-alipayplus-mcp
uv install

Typical dependencies (installed automatically):

cryptography
pycryptodome
rsa
mcp[cli]

MCP client configuration (example JSON for an MCP-aware assistant):

{
  "mcpServers": {
    "alipayplus-mcp": {
      "command": "uvx",
      "args": ["ant-intl-alipayplus-mcp"],
      "env": {
        "GATEWAY_URL": "https://open-sea-global.alipay.com",
        "CLIENT_ID": "your_client_id",
        "MERCHANT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
        "ALIPAY_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
        "PAYMENT_NOTIFY_URL": "https://your-domain.com/payment/notify",
        "SETTLEMENT_CURRENCY": "USD",
        "MERCHANT_NAME": "Your Store",
        "MERCHANT_ID": "M1234567890",
        "MERCHANT_MCC": "5411",
        "MERCHANT_REGION": "US"
      }
    }
  }
}

Environment variables reference:

Variable	Required	Purpose
GATEWAY_URL	No	AlipayPlus API gateway (defaults to production URL)
CLIENT_ID	Yes	Merchant client identifier
MERCHANT_PRIVATE_KEY	Yes	RSA private key to sign requests
ALIPAY_PUBLIC_KEY	Yes	Alipay public key to verify responses
PAYMENT_REDIRECT_URL	No	Return URL for web-based payments
PAYMENT_NOTIFY_URL	No	Webhook callback for asynchronous payment results
SETTLEMENT_CURRENCY	No	Default currency for settlement
MERCHANT_NAME / MERCHANT_ID / MERCHANT_MCC / MERCHANT_REGION	No	Merchant metadata used in requests

Available Tools

Each MCP tool is exposed as a callable operation with structured input and output.

create_payment
- Inputs: amount, currency, order_id, subject, return_url, notify_url, metadata
- Output: payment_url | SDK payload | order reference
query_payment
- Inputs: order_id or transaction_id
- Output: status, amount, payer_info, timestamps
cancel_payment
- Inputs: order_id or transaction_id, reason (optional)
- Output: cancel_result, new_status
create_refund
- Inputs: order_id or transaction_id, refund_amount, refund_reason, refund_id
- Output: refund_status, refund_id
customs_declare
- Inputs: order_id, declaration_payload
- Output: declaration_result, declaration_id
query_customs_declare
- Inputs: declaration_id or order_id
- Output: customs_status, tracking_info

The server returns machine-readable JSON responses suitable for agent decision-making and follow-up actions.

Use Cases

In-chat payment collection
- User completes checkout in a chat. The assistant calls create_payment with order details and returns a secure payment_url or SDK payload to the user. When the webhook (PAYMENT_NOTIFY_URL) notifies the server, the assistant queries query_payment to confirm the result and updates the user.
Refund handling via assistant
- Customer requests a partial refund. The assistant validates eligibility, calls create_refund with the original transaction_id and amount, and reports refund_status to the user. Refund tracking is available via query_payment or refund-specific responses.
Cross-border and customs flow
- For international sales, the assistant invokes customs_declare after payment creation to submit customs information. Use query_customs_declare to monitor approval and present status updates to customers.

Integration snippet (Python, conceptual):

from qwen_agent.agents import Assistant

tools = [{
  "mcpServers": {
    "alipayplus-mcp": {
      "command": "uvx",
      "args": ["ant-intl-alipayplus-mcp"],
      "env": {
        "CLIENT_ID": "…",
        "MERCHANT_PRIVATE_KEY": "…",
        "ALIPAY_PUBLIC_KEY": "…",
        "PAYMENT_NOTIFY_URL": "https://your-domain/notify"
      }
    }
  }
}]

assistant = Assistant(llm={'model':'qwen-max','api_key':'API_KEY'}, function_list=tools)

Security and best practices

Store private keys securely (use a secrets manager). Never embed keys in source control.
Validate and log webhooks; verify signatures using ALIPAY_PUBLIC_KEY.
Use test credentials and sandbox endpoints during development.
Implement idempotency (use unique order_id / refund_id) to avoid duplicate operations.

For full source, examples, and changelog, see the project repository: https://github.com/alipay/global-alipayplus-mcp.

AlipayPlus MCP Server for AI Payments and Refunds