Spaces:
Sleeping
Sleeping
| # Paytm Payment MCP Server & AI Router API Documentation | |
| This documentation is curated for Large Language Models (LLMs) and developers integrating Paytm's Model Context Protocol (MCP) Server and AI Router services. It covers everything from conversational AI integration to specific transactional workflows and routing configurations. | |
| --- | |
| ## Part 1: Paytm MCP Server | |
| Paytm MCP Server enables AI agents and developers to securely access Paytm's Payments and Business Payments APIs securely via the Model Context Protocol (MCP). | |
| ### Main Features | |
| - **Smart Payment Ops**: Automate refund workflows, settlement tracking, and transaction status checks. | |
| - **Context-Aware AI Assistants**: Trigger queries via natural language (e.g. \"Create a ₹500 payment link\"). | |
| - **Agentic AI Payments**: Provide enhanced automated and dynamic shopping experiences. | |
| ### MCP Tools Available | |
| The MCP exposes a set of tools mapped to Paytm's underlying REST APIs. An LLM agent can invoke these exact tools: | |
| | Tool Name | Description | Underlying API Context | | |
| |--------------------------------------|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| | |
| | `create_link` | Creates a new payment link. | Create Link API | | |
| | `fetch_link` | Fetches details of a created payment link. | Fetch Link API | | |
| | `fetch_transaction` | Fetches transaction details specific to a payment link. | Fetch Transaction Link API | | |
| | `fetch_order_list` | Fetches list of orders within a 30-day date range. | Order List API | | |
| | `initiate_refund` | Initiates a refund for a specific transaction. | Initiate Refund API | | |
| | `check_refund_status` | Checks the status of a previously initiated refund. | Check Refund Status API | | |
| | `fetch_refund_list` | Fetches a list of refunds within a 30-day date range. | Fetch Refund List API | | |
| | `get_settlement_summary` | Retrieves overall summary details of payouts for a date range or payout ID. | Get Settlement Summary API | | |
| | `get_settlement_detail` | Retrieves a granular/transactional view of all settled transactions at the payout level. | Get Settlement Details API | | |
| | `get_settlement_order_details` | Retrieves settlement details at an order level (needs payout date and order ID). | Get Settlement Order Details API | | |
| | `get_settlement_transaction_details` | Retrieves settlement details of a specific order based on transaction ID. | Get Settlement Transaction Details API | | |
| ### Deployment Modes | |
| 1. **Remote MCP (Recommended)**: Hosted by Paytm. Requires requesting a `Client ID` and `Secret Key` from `devsupport@paytmpayments.com`. You will use your `PAYTM_MID`. Cursor setup via `generate_mcp_token_cursor.sh` to generate a JWT token. | |
| 2. **Local MCP (Self-Hosted)**: Run locally via `Claude Desktop`. | |
| - Requires Python 3.12+, `uv`, and Claude Desktop. | |
| - Env variables required: `PAYTM_MID`, `PAYTM_KEY_SECRET`. | |
| - `claude_desktop_config.json` uses `uv path --directory <dir> run paytm_mcp.py`. | |
| --- | |
| ## Part 2: AI Router Payment Flow | |
| The AI Router serves to centralize the checkout process and smartly route payments across configured payment aggregators (PAs)/payment gateways (PGs). | |
| ### Standard Transaction Journey | |
| 1. **Initiation**: Merchant initiates the transaction by calling the **Create Order API**. | |
| 2. **Token Generation**: AI Router creates an order and returns a **Transaction Token** along with an Order ID. | |
| 3. **Fetch Options**: Merchant calls **Fetch Payment Options API** to retrieve available payment methods. | |
| 4. **Checkout Rendering**: AI Router provides the configured options, which populate the cashier page. | |
| 5. **Execution**: User selects an option and clicks Pay. The **Pay API** is then called. | |
| 6. **Routing**: AI Router intelligently evaluates and routes the transaction to the most appropriate PA/PG. | |
| 7. **Processing**: Gateway processes the transaction and returns status to AI Router. | |
| 8. **Verification**: | |
| - Polling: Merchant polls the **Order Status API** (using the Order ID). | |
| - Server-to-Server: Alternatively, AI Router triggers a real-time **Payment Webhook** with the updated payment status. | |
| --- | |
| ## Part 3: AI Router Routing Rule Configuration | |
| If no rules are created, the AI Router defaults to selecting the gateway with the highest historical/real-time success probability. Merchants can explicitly define routing constraints via the dashboard or APIs. | |
| ### 1. Gateway Routing Configuration | |
| Routing can be applied to One-Time payments and Subscription payments. | |
| - **UPI Routing**: Filtered by UPI Intent vs. UPI Collect, and optionally limited by transaction amount ranges. | |
| - **Bank Mandates Routing**: Filtered by Mandate Type (Netbanking vs Debit Card) and applied against specific Issuing Banks. | |
| - **Cards Routing**: Rules set by card attributes (Credit, Debit, Prepaid, Visa, Mastercard, RuPay, Amex, Diners, Issuing Bank). | |
| - **Cost-Based Routing**: Optimizes for gateway costs. | |
| - *Relative Cost*: Ranked priority preference according to cheapest. | |
| - *Absolute Cost*: Flat value or percentage based. Minimum Success Rate baselines can also be configured so cheap traffic ensures minimum reliability. | |
| ### 2. API Based / Enforced Routing | |
| Transaction-level control that overrides dashboard configurations, primarily used for targeted business campaigns/promotions. | |
| - **How to Use**: Pass special parameter variables via code during runtime. | |
| - **Payload**: Provide `enforcedRoutingParam` inside the `txnRoutingParams` object. | |
| - **Endpoint Injection**: This object must be pushed in either the **Create Order API** or **Pay API**. (If a conflict exists between the two, parameters sent via the Pay API take precedence). | |
| --- | |
| ## Part 4: General Developer Implementation Notes & FAQs | |
| - **Gateways requirement**: Merchants must independently onboard with third-party payment aggregators. Once keys are received, submit them statically inside the Paytm AI Router Dashboard. | |
| - **Fallback Logic**: If the lowest cost gateway drops below the success rate baseline, AI Router will auto-skip to the next cheapest that meets strict success margins. | |
| - **Integration**: The unified AI Router architecture prevents merchants from having to build split/custom integrations for every gateway backend. Call the AI Router suite uniformly, and routing configs isolate the complexities. | |
| --- | |
| ## Part 5: Core Transaction APIs | |
| 1. **Initiate Transaction API**: Used to create an order and retrieve a transaction token. | |
| - Endpoint: `POST /theia/api/v1/initiateTransaction?mid={MID}&orderId={ORDERID}` | |
| - Body contains: `requestType` (Payment), `txnAmount` (value, currency), `userInfo` (custId), `callbackUrl` | |
| 2. **Process Transaction API**: Used to process the payment using the generated token. | |
| - Body contains: `paymentMode` (e.g., `CC`, `DC`, `NET_BANKING`, `UPI`, `BALANCE`), `cardInfo`, `channelCode`. | |
| 3. **Transaction Status API**: Query the status of a specific order. | |
| - Body contains: `ORDERID`, `MID`. Returns `STATUS` (e.g., `TXN_SUCCESS`, `TXN_FAILURE`). | |
| --- | |
| ## Part 6: JS Checkout Integration | |
| A customized frontend layer that natively displays payment options on the merchant's site. | |
| 1. Inject the script: `<script src="https://securegw.paytm.in/merchantpgpui/checkoutjs/merchants/{MID}.js"></script>` | |
| 2. Initialize and Invoke: | |
| ```javascript | |
| var config = { "root": "", "flow": "DEFAULT", "data": { "orderId": "{ORDERID}", "token": "{TXN_TOKEN}", "tokenType": "TXN_TOKEN", "amount": "{AMOUNT}" }, "handler": { "notifyMerchant": function(eventName,data){ ... } } }; | |
| window.Paytm.CheckoutJS.init(config).then(function() { | |
| window.Paytm.CheckoutJS.invoke(); | |
| }); | |
| ``` | |
| --- | |
| ## Part 7: Subscriptions | |
| - **Initiate Subscription API**: Used to create a subscription mandate. | |
| - **List Subscriptions API**: Used to view active/inactive mandates. | |
| - **JS Checkout for Subscriptions**: Extends JS Checkout by passing subscription-specific flags (e.g., `requestType: "SUBSCRIBE"`) during checkout initialization. | |
| --- | |
| ## Part 8: Post-Transaction & Financials | |
| 1. **Refund API**: Initiate a partial or full refund against a `TXNID`. | |
| - Requires: `ORDERID`, `TXNID`, `refId` (merchant-generated unique refund ID), `refundAmount`. | |
| 2. **Settlement APIs**: | |
| - **Settlement Summary API**: Fetches the gross/net settlement summary against the Payout Date. | |
| - **Settlement Detail API**: Provides transactional-level granularity of an executed settlement. | |
| --- | |
| ## Part 9: Webhooks & Callbacks | |
| 1. **Payment Status Webhook**: Paytm pushes real-time server-to-server updates when an order transitions to a terminal state (Success/Failure). | |
| - Payload includes: `ORDERID`, `TXNID`, `TXNAMOUNT`, `STATUS`, `RESPCODE`, `RESPMSG`, `CHECKSUMHASH`. | |
| - Merchants must validate the `CHECKSUMHASH` against their `PAYTM_KEY_SECRET` to prevent spoofing. | |
| - Webhook URL is setup via the Merchant Dashboard. | |
| --- | |
| ## Part 10: AI Router Analytics & Reports | |
| Paytm provides a rich dashboard for visualizing and analyzing transaction data. This is particularly useful when building merchant-facing LLM agents that need to query or interpret performance graphs, failures, and reconciliations. | |
| ### 1. Analytics Dashboards | |
| - **Successful Payments Analysis**: Tracks successful payment volumes. Supports Historical Benchmarking (Yesterday, Current Week vs Last Week, Current Month comparisons) and Historic Trends. Can overlay **Gateways**, **Payment Source**, and **Moving Averages**. | |
| - **Total Collection Analysis**: Similar to volume tracking, but tracks the Total Collection Amount in INR. | |
| - **Success Rate Analysis**: Tracks the transaction success percentage. Includes **Failure Reasons Analytics** (identifies if the failure was caused by the user, bank, or the router) and highlights the top failure contributors. | |
| ### 2. Standard Reports | |
| - **Payments Report**: Offers a List View (Transaction ID, Date, Order ID, Payment Source, Gateway, Amount) and a Detailed View (Response Codes, Customer details). Allows single-click refund initiation. | |
| - **Refunds Report**: Offers List View and Detailed View (shows RRN [Refund Reference Number]). | |
| - **Bulk Refunds**: Merchants can upload a CSV (containing `TXN_ID`, `REFUND_AMOUNT`, and `REFUND_REASON`) to process mass bulk refunds directly from the dashboard panel. | |
| ### 3. Report Generation and Downloads | |
| - **Exporting**: Reports can be downloaded offline (CSV/Excel/PDF) or emailed directly. | |
| - **Constraints**: Maximum querying duration for a single report export is 3 months. | |
| - **Filters Supported**: Date/Time Range, Specific Payment Gateway, Payment Source (CC/DC/UPI), Status (Success, Pending, Failed), Order ID, etc. | |