home / mcp / alipayplus mcp server

AlipayPlus MCP Server

Provides an MCP server that wraps AlipayPlus payment APIs to create payments, query status, refunds, and customs declarations.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "alipay-global-alipayplus-mcp": {
      "command": "uvx",
      "args": [
        "ant-intl-alipayplus-mcp"
      ],
      "env": {
        "CLIENT_ID": "your_client_id_here",
        "GATEWAY_URL": "https://open-sea-global.alipay.com",
        "MERCHANT_ID": "Your Merchant ID",
        "MERCHANT_MCC": "5411",
        "MERCHANT_NAME": "Your Merchant Name",
        "MERCHANT_REGION": "US",
        "ALIPAY_PUBLIC_KEY": "your_alipay_public_key_here",
        "PAYMENT_NOTIFY_URL": "https://your-domain.com/payment/notify",
        "SETTLEMENT_CURRENCY": "USD",
        "MERCHANT_PRIVATE_KEY": "your_merchant_private_key_here"
      }
    }
  }
}

You set up the AlipayPlus MCP Server to let your AI assistants securely create payments, check statuses, process refunds, and handle customs declarations through standardized MCP tools. This server wraps Ant International’s AlipayPlus payment APIs into a consistent, programmable interface you can call from conversations and automations, enabling seamless payment operations within AI workflows.

How to use

Use the AlipayPlus MCP Server as a tool inside your MCP client. You configure the tool to run the server locally and expose a set of payment-related actions that your AI agent can invoke during conversations. The server supports creating payments, querying payments, canceling payments, creating refunds, and handling customs declarations. When your agent needs to process a payment or refund, call the corresponding tool, pass the required parameters, and receive a structured response with the outcome. Maintain secure handling of sensitive credentials and set up the payment notification callback URL so you can receive asynchronous results.

How to install

Prerequisites: ensure you have Python 3.11 or higher and a package manager such as uvx or pip. You also need a valid AlipayPlus Merchant Account with the required credentials.

1. Install using uvx (recommended) or via pip or uv.

Direct Usage with 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

Prerequisites for installation include Python 3.11+ and dependencies such as cryptography==44.0.3, mcp[cli]>=1.9.1, pycryptodome==3.22.0, rsa>=4.9.1.

Configuration and usage notes

Configure your MCP client to connect to the AlipayPlus MCP Server using the provided stdio configuration. You will launch the server with a runtime command and supply environment variables that hold your credentials and gateway details.

Key environment variables you will use include gateway URL, client ID, merchant private key, Alipay public key, and a payment notify URL. You can also set optional values for settlement currency and merchant identifying details to customize the integration.

Available MCP tools and operations

Create Payment: Initiate a payment request for a transaction.

Query Payment: Retrieve status and details of a previously submitted payment.

Cancel Payment: Cancel a payment when the result is not received within the expected timeframe.

Create Refund: Initiate a full or partial refund against a successful payment.

Customs Declare: Declare a payment to customs or update an existing declaration.

Query Customs Declaration: Check the status of declared payments.

Security and reliability notes

Treat all credentials as secrets. Use secure storage for CLIENT_ID, MERCHANT_PRIVATE_KEY, and ALIPAY_PUBLIC_KEY. Ensure PAYMENT_NOTIFY_URL is accessible only by trusted systems and protected behind proper network controls.

Troubleshooting tips

If you don’t receive payment results in a timely manner, verify the PAYMENT_NOTIFY_URL is reachable and that your gateway credentials are correctly configured. Check logs for any authentication or signature verification failures and ensure the API gateway URL (GATEWAY_URL) is correct.

Notes

This MCP server integrates with AI workflows to perform payments, refunds, and customs-related actions during conversations. Ensure you provide accurate merchant details and test in a staging environment before going to production.

Available tools

create_payment

Create a payment request to initiate a transaction through the AlipayPlus MCP Server.

query_payment

Query the status and details of a submitted payment to track progress.

cancel_payment

Cancel a payment when the result is not returned or needs to be aborted.

create_refund

Initiate a refund against an existing, successful payment.

customs_declare

Declare or update a payment with customs information.

query_customs_declare

Check the status of a customs declaration for a payment.