Overview

The Antom MCP Server is an MCP (Model Context Protocol)–compatible adapter that exposes Ant International’s Antom payment APIs as standardized MCP tools. It lets AI assistants (or any MCP-aware agent) create payment sessions, check transaction status, cancel pending payments, and initiate or query refunds — all via protocol-native tool calls instead of custom API wiring.

This server simplifies integrating payment flows into conversational agents by handling request signing, response verification, and Antom-specific payloads behind an MCP-friendly interface. Developers can run the server alongside their assistant and declare it as an MCP tool so the model can call payment and refund operations directly during dialogue.

Features

Create payment sessions for client-side SDKs (hosted or redirect flows)
Query payment transaction details and status
Cancel payments that remain unresolved within expected time windows
Create full or partial refunds against successful payments
Query refund request status and details
Compatible with MCP tooling patterns so LLM-driven assistants can orchestrate transactions securely

Prerequisites

Python 3.11+
uv (uvx / uv install) or pip for installation
Antom (Alipay International) merchant credentials:
- CLIENT_ID
- MERCHANT_PRIVATE_KEY (RSA)
- ALIPAY_PUBLIC_KEY (RSA)
- Optional: PAYMENT_REDIRECT_URL, PAYMENT_NOTIFY_URL

Installation / Configuration

Install and run the MCP server using uvx (recommended) or from source.

Install via uvx

uvx ant-intl-antom-mcp

Install from source

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

Example MCP client configuration (JSON) — register the MCP server as a tool in your assistant runtime:

{
  "mcpServers": {
    "antom-mcp-server": {
      "command": "uvx",
      "args": ["ant-intl-antom-mcp"],
      "env": {
        "GATEWAY_URL": "https://open-sea-global.alipay.com",
        "CLIENT_ID": "your_client_id_here",
        "MERCHANT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
        "ALIPAY_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
        "PAYMENT_REDIRECT_URL": "/",
        "PAYMENT_NOTIFY_URL": "https://your-domain.com/payment/notify"
      }
    }
  }
}

Environment variables

Variable	Required	Purpose
GATEWAY_URL	No	Antom API gateway (default: https://open-sea-global.alipay.com)
CLIENT_ID	Yes	Merchant client identifier
MERCHANT_PRIVATE_KEY	Yes	RSA private key used to sign requests
ALIPAY_PUBLIC_KEY	Yes	Alipay RSA public key for response verification
PAYMENT_REDIRECT_URL	No	Redirect URL after hosted payment completion
PAYMENT_NOTIFY_URL	No	Server callback URL for payment notifications

Available Tools / Operations

The MCP server exposes a small set of operations (calls) that assistant agents can invoke. Typical tool names and behaviors:

create_payment_session
- Create a payment session or payload for client-side SDK / hosted checkout.
query_payment_detail
- Retrieve the current status and metadata for a payment transaction.
cancel_payment
- Attempt to cancel a payment when a result is not received within an expected window.
create_refund
- Initiate a full or partial refund for a completed payment.
query_refund_detail
- Check status and details of an existing refund request.

Each tool handles Antom-specific signing and verification; callers provide business identifiers and amounts while the server manages protocol-level fields.

Use Cases

Checkout flow in a conversational assistant
- Assistant calls create_payment_session with order_id and amount.
- The server returns a hosted checkout URL or SDK payload which the client opens.
- After redirect or notify event, the assistant calls query_payment_detail to confirm success and continue order fulfillment.
Refund handling via conversation
- Customer asks for a refund in chat. Assistant validates eligibility, then calls create_refund with the payment_id and refund_amount.
- Assistant later calls query_refund_detail to inform the user about refund processing or completion.
Managing stuck or delayed payments
- If a payment remains pending, the assistant can call cancel_payment to avoid orphaned transactions and notify the user.
Automated reconciliation
- Backoffice workflows or agents can periodically call query_payment_detail and query_refund_detail to reconcile transaction records with Antom.

Best practices & troubleshooting

Keep private keys secure and rotate per your security policy.
Use PAYMENT_NOTIFY_URL to receive asynchronous notifications and reconcile state; do not rely solely on synchronous responses.
Test in a sandbox gateway before production (check GATEWAY_URL for test endpoints).
Log signed requests and verification outcomes for diagnostics while avoiding logging raw private keys.

Resources

GitHub: https://github.com/alipay/global-antom-mcp
MCP spec: https://modelcontextprotocol.io/
Antom (Alipay International) docs: Antom cashier/pay integration guides

License: MIT (see repository for details)

Antom MCP Server for Payments and Refunds