MCP Server

The Airpay MCP Server lets AI assistants — Claude, Cursor, VS Code, ChatGPT, Perplexity — interact with Airpay Payment Gateway through natural language. Once connected, your AI can verify payments, generate QR codes, and process refunds directly in the chat.

Hosted MCP endpoint: https://mcp.airpay.co.in/mcp

Features

• Payment Verification: Check the status of any transaction by order ID, transaction ID, or RRN — get real-time payment status, amounts, and processing details.
• Refund Processing: Initiate full or partial refunds with a built-in two-phase confirmation guard — the AI previews the refund and waits for your explicit approval before processing.
• UPI QR Code Generation: Generate dynamic UPI QR codes for any amount and customer — ready to share instantly for payment collection.
• UPI Address Validation: Validate any UPI Virtual Payment Address (VPA) before initiating a transfer to prevent failed payments.
• Subscription Management: Check the status of eNACH and Standing Instruction mandates — see whether a subscription is active, paused, or completed.
• Bank & Payment Options: Retrieve the list of supported banks and payment modes available for your merchant account.
• Built-in Security Guardrails: Read-only mode disables all write tools with a single environment variable. Selective toolsets let you expose only the tools your workflow needs.
• Stateless HTTP Transport: Each tool call is a self-contained HTTP request — no session state, safe to restart, compatible with load balancers and shared deployments.

How It Works

Remote Hosted — OAuth 2 authentication is required once before your AI client can call any tool. After that, tool calls flow directly through the hosted server.

sequenceDiagram
    actor User
    participant AI as AI Client
    participant Auth as OAuth 2
    participant GW as Airpay Gateway

    Note over User,Auth: One-time login
    User->>AI: Connect to MCP Server
    AI->>Auth: Redirect to login
    User->>Auth: Enter credentials
    Auth-->>AI: Access token

    Note over User,GW: Tool calls
    User->>AI: "Status of ORD123?"
    AI->>GW: airpay_verify_order (token)
    GW-->>AI: Payment status
    AI-->>User: "ORD123 paid ₹500"

Self-Hosted — No OAuth 2 required. Your AI client connects directly to your local server using the credentials already configured in .env.

sequenceDiagram
    actor User
    participant AI as AI Client
    participant MCP as MCP Server
    participant GW as Airpay Gateway

    User->>AI: "Status of ORD123?"
    AI->>MCP: airpay_verify_order (.env creds)
    MCP->>GW: API request
    GW-->>MCP: Payment status
    MCP-->>AI: Result
    AI-->>User: "ORD123 paid ₹500"

Prerequisites

• Go 1.25+ or Docker
• An Airpay merchant account with API credentials (Merchant ID, username, password, secret key, OAuth2 client ID and secret)

Setup

Binary (Go)

1. Clone the repository

git clone https://github.com/airpay/airpay-mcp-server.git
cd airpay-mcp-server
go mod download

2. Configure credentials

cp .env.example .env

Edit .env with your Airpay credentials:

AIRPAY_MERCHANT_ID=your_merchant_id
AIRPAY_USERNAME=your_username
AIRPAY_PASSWORD=your_password
AIRPAY_SECRET=your_secret_key
AIRPAY_CLIENT_ID=your_oauth2_client_id
AIRPAY_CLIENT_SECRET=your_oauth2_client_secret
PAYMENT_DOMAIN=https://yourstore.com
ENVIRONMENT=sandbox

3. Build and run

Linux / macOS

go build -o airpay-mcp-server ./cmd/airpay-mcp-server
./airpay-mcp-server
# Running over Streamable HTTP on :8888

Windows

go build -o airpay-mcp-server.exe ./cmd/airpay-mcp-server
.\airpay-mcp-server.exe
# Running over Streamable HTTP on :8888

go run (any OS)

go run ./cmd/airpay-mcp-server
# Running over Streamable HTTP on :8888

Docker

1. Clone and configure

git clone https://github.com/airpay/airpay-mcp-server.git
cd airpay-mcp-server
cp .env.example .env

Edit .env with your Airpay credentials (same variables as the Binary tab).

2. Run with Docker

docker build -t airpay-mcp-server .
docker run --env-file .env -p 8888:8888 airpay-mcp-server

Connect Your AI Client

There are two ways to connect your AI client to the Airpay MCP Server:

Method	Best For
Remote Hosted (recommended)	Most users — no setup, always up to date, hosted by Airpay at https://mcp.airpay.co.in/mcp
Self-Hosted (Local)	Developers who need full control or want to run in a private network

Recommended

Use the Airpay-hosted MCP Server at https://mcp.airpay.co.in/mcp. No infrastructure to manage just point your AI client at the URL and you’re ready.

Remote Hosted (Recommended)

Point your AI client at the Airpay-hosted server. On first connection, you will be redirected through an OAuth 2 login flow — log in with your Airpay merchant credentials to authorize access. After that, your AI client uses the issued token automatically for all subsequent tool calls.

MCP endpoint: https://mcp.airpay.co.in/mcp

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}

Restart Cursor after saving.

VS Code

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}

Reload the VS Code window (Ctrl+Shift+P → Reload Window).

Claude

1. Visit the Anthropic MCP Directory or open Claude.ai → Settings → Integrations
2. Search for Airpay MCP Server
3. Click Connect
4. A browser window will open — log in with your Airpay merchant credentials to complete authentication
5. Once authenticated, the Airpay tools are available immediately in Claude

Ask Claude: “What Airpay payment tools are available?”

ChatGPT

1. Open ChatGPT and go to Explore → Plugins or Settings → Connected Apps
2. Search for Airpay MCP Server
3. Click Enable
4. Log in with your Airpay merchant credentials when prompted
5. The Airpay tools are now available in your ChatGPT conversations

Ask ChatGPT: “What Airpay payment tools are available?”

Self-Hosted (Local)

Run your own instance for private or on-premise deployments. No OAuth 2 required — your AI client connects directly to the local server using the credentials you configured in .env. See Setup above to build and start the server, then point your client at http://localhost:8888/mcp.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}

Restart Cursor after saving.

VS Code

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}

Reload the VS Code window (Ctrl+Shift+P → Reload Window).

Available Tools

Tool	Read-Only	Description
airpay_verify_order	✅	Check payment status by order ID, transaction ID, or RRN
airpay_get_bank_list	✅	List supported banks and payment options
airpay_pos_transaction_detail	✅	Get POS terminal transaction details
airpay_initiate_refund	❌	Initiate full or partial refund — requires user confirmation
airpay_validate_vpa	✅	Validate a UPI Virtual Payment Address
airpay_generate_qr	❌	Generate a dynamic UPI QR code for payment
airpay_check_subscription_status	✅	Check eNACH / SI subscription status

Refund confirmation: Before any refund is processed, the AI will show you a preview and ask for explicit approval. The refund only executes after you confirm.

Configuration

All configuration is via environment variables.

Required:

Variable	Description
AIRPAY_MERCHANT_ID	Your Airpay merchant ID
AIRPAY_USERNAME	API username
AIRPAY_PASSWORD	API password
AIRPAY_SECRET	Secret key
AIRPAY_CLIENT_ID	OAuth2 client ID
AIRPAY_CLIENT_SECRET	OAuth2 client secret
PAYMENT_DOMAIN	Merchant domain for QR/bank-list requests (e.g. https://yourstore.com)

Optional:

Variable	Default	Description
PORT	8888	Server listen port
ENVIRONMENT	sandbox	sandbox or production
TOOLSETS	all	Comma-separated toolsets: payments, refunds, qr_upi, subscriptions
READ_ONLY	false	Set true to disable all write tools
LOG_LEVEL	info	debug, info, warn, or error

Sandbox vs production

Use ENVIRONMENT=sandbox while testing. Switch to ENVIRONMENT=production only with live merchant credentials.

Examples

Example 1: Verify a Payment

User prompt:

“What is the status of order ORD123456?”

What happens: The AI looks up the order and returns the current payment status.

User: What is the status of order ORD123456?
Assistant: Let me check that order for you.
→ Calls: airpay_verify_order(orderid="ORD123456")
→ Returns:
  Order: ORD123456
  Status: SUCCESS
  Amount: ₹500.00
  Transaction ID: 7891234

---

Example 2: Process a Refund

User prompt:

“Refund ₹250 for transaction 7891234.”

What happens: The AI previews the refund and waits for explicit confirmation before processing.

User: Refund ₹250 for transaction 7891234
Assistant: I'll initiate a refund preview for you.
→ Calls: airpay_initiate_refund(transactions=[{ap_transactionid: "7891234", amount: "250.00"}])
→ Returns:
  Preview — Refund ₹250.00 for transaction 7891234
  Confirmation required to proceed.

User: Yes, confirm
Assistant: Processing the refund now.
→ Calls: airpay_initiate_refund(transactions=[...], confirmed=true, confirmation_token="abc123")
→ Returns: Refund of ₹250.00 initiated successfully for transaction 7891234.

---

Example 3: Generate a UPI QR Code

User prompt:

“Generate a UPI QR code for ₹500 for customer John Doe, john@example.com.”

What happens: The AI generates a dynamic UPI QR code for the specified amount and customer.

User: Generate a UPI QR code for ₹500 for customer John Doe, john@example.com
Assistant: Generating the QR code now.
→ Calls: airpay_generate_qr(orderid="ORD789", amount="500.00",
    customer_name="John Doe", customer_email="john@example.com")
→ Returns:
  QR code generated for order ORD789
  Amount: ₹500.00
  Share the QR with the customer to complete payment.

---

Example 4: Validate a UPI Address

User prompt:

“Is merchant@okaxis a valid UPI address?”

What happens: The AI validates the UPI Virtual Payment Address before a payment is initiated.

User: Is merchant@okaxis a valid UPI address?
Assistant: Let me validate that UPI address.
→ Calls: airpay_validate_vpa(vpa="merchant@okaxis")
→ Returns: merchant@okaxis is a valid UPI Virtual Payment Address.

---

Example 5: Check a Subscription

User prompt:

“What is the status of subscription SUB123456?”

What happens: The AI looks up the eNACH or SI mandate and returns its current status.

User: What is the status of subscription SUB123456?
Assistant: Let me check that subscription.
→ Calls: airpay_check_subscription_status(subscription_id="SUB123456")
→ Returns:
  Subscription: SUB123456
  Status: SUBSCRIBED
  Next debit scheduled as per the mandate cycle.