# Hyperswitch MCP MCP > Hyperswitch MCP manages complex payment infrastructure operations, giving your AI client direct access to core financial data. You can list and retrieve details for customers, payments, refunds, payouts, and disputes, all through one interface. It's built for automating fintech workflows, monitoring payment health, and reconciling ledgers without manual API calls. ## Overview - **Category:** money-moves - **Price:** Free - **Tags:** payment-gateway, open-source, refund-management, dispute-resolution, payouts, fintech-api ## Description Need to track down a specific customer refund or reconcile a batch of payments? This MCP connects your AI agent directly to the Hyperswitch API endpoints. Instead of building complex multi-step sequences just to get basic data points, you can ask for it naturally. Your agent handles the necessary lookups—whether that means gathering all recent payments, checking an active dispute's status, or pulling a specific customer's profile. It makes automating core fintech operations simple. Vinkius hosts this MCP so your AI client can treat payment monitoring like any other native capability; you just connect once and get access to the full suite of financial tools. ## Tools ### get_customer Fetches detailed information for a specific client by ID. ### get_dispute Retrieves all details associated with one particular dispute case. ### get_payment Gets the full record for a single payment transaction. ### get_payout Retrieves specific details regarding a disbursed payout. ### get_refund Fetches the complete record for a single refund transaction. ### list_customers Generates a comprehensive list of all registered customers in the system. ### list_disputes Provides an overview and listing of all currently active disputes. ### list_payments Returns a list summary of multiple payment transactions over time. ### list_payouts Lists and summarizes all payouts that have been processed or are pending. ### list_refunds Generates a list of historical refund records, useful for auditing purposes. ## Prompt Examples **Prompt:** ``` List the last 10 payments processed through Hyperswitch. ``` **Response:** ``` I'll fetch your recent payment history from Hyperswitch. ``` **Prompt:** ``` Check for any active disputes. ``` **Response:** ``` I'll look up the current disputes in your account. ``` **Prompt:** ``` Show me the details for customer ID 'cust_123'. ``` **Response:** ``` I'll retrieve that customer's information for you. ``` ## Capabilities ### Audit Customer Records Retrieves complete profiles for individual customers, including associated activity. ### Track Payment Life Cycles Lists and retrieves specific details for every payment transaction recorded in the system. ### Manage Payout Statuses Gathers current payout information, allowing you to verify funds dispersal and status. ### Reconcile Refund Activity Provides access to all refund records, letting you track when money was returned and why. ### Investigate Disputes Retrieves detailed information on active disputes or lists historical dispute logs for review. ## Use Cases ### Investigating Missing Funds A payments analyst notices a discrepancy between the expected revenue and the recorded payouts. The agent first calls `list_payouts` to get the general timeframe, then uses `get_payment` on specific transaction IDs; finally, it pulls up `list_refunds` to see if any clawbacks or refunds account for the missing amount. ### Customer Service Account Audit A customer calls about a billing issue. The agent first uses `get_customer` with the provided ID, then checks both `list_payments` and `list_disputes`. This gives the service rep all necessary context—payment failure history and active dispute status—in minutes. ### Quarterly Ledger Review The finance team needs to prove that every customer who received a payout has also had their corresponding payments recorded. The agent runs `list_customers`, cross-references this list against results from `list_payments` and `list_payouts` to flag any discrepancies. ### Handling Chargebacks When a dispute arises, the system needs background context. The agent first calls `get_dispute`, then uses `get_payment` for the original transaction details and reviews the customer record using `get_customer` to understand the account's full history. ## Benefits - Automate dispute investigation. Instead of manually checking multiple dashboards, your agent can use `list_disputes` followed by `get_dispute` to give you a full status report immediately. - Simplify customer onboarding validation. You can cross-reference new user data using `get_customer` against their recent payment history via `list_payments`, verifying identity and account health in one go. - Eliminate reconciliation delays. When money moves, it's recorded somewhere. Use the MCP to query specific payout statuses with `get_payout` or audit refund trails using `list_refunds`, knowing exactly where funds are. - Improve fraud detection speed. Quickly check transaction patterns by comparing a general list of payments (`list_payments`) against current payouts (`list_payouts`) to spot anomalies faster than manual review. - Standardize financial lookups. All critical data—from listing all customers with `list_customers` to getting details on one refund via `get_refund`—is routed through a single, predictable interface. ## How It Works The bottom line is, it lets your agent perform complex financial queries without you writing any repetitive boilerplate code. 1. Your agent determines the required financial action, such as checking a payout status or listing customers. 2. The MCP maps that request to the appropriate tool (e.g., `get_payout` or `list_customers`), executing the call against the Hyperswitch API. 3. It returns structured data directly to your AI client, which then formats it into conversational text for you. ## Frequently Asked Questions **How do I use the `list_payments` tool to check payment history?** The `list_payments` tool returns an overview of multiple transactions. Use it when you need a summary or list view, not just one specific transaction's details. **Can I use `get_customer` to see their payment history?** `get_customer` retrieves core profile data only. To see the full financial activity, you must call separate tools like `list_payments` or `list_disputes` using the customer's ID. **What is the difference between `get_payout` and `list_payouts`?** `list_payouts` gives you a list summary of payouts. Use it for an overview; use `get_payout` when you need every single detail on one specific payout record. **Does the MCP help with reconciliation across all tools?** It doesn't run the math itself, but by providing structured access to `list_payments`, `get_payout`, and `list_refunds`, it gives your agent all the necessary inputs for you to reconcile manually or programmatically. **What parameters do I pass to `list_disputes` to filter by status?** The API allows you to narrow down results. You can restrict the list using a dedicated status parameter (like 'open' or 'resolved') directly in your call to `list_disputes`. This saves you from having to process large volumes of irrelevant disputes. **When running bulk checks across multiple endpoints like `list_payments` and `list_payouts`, should I worry about rate limits?** Yes, watch for rate limiting errors when processing high volume. If you expect to handle thousands of records in a single session, implement an exponential backoff strategy or check the Hyperswitch documentation for bulk processing endpoints. **If I use `get_refund`, does it require the original payment ID?** Yes. You must provide a specific transaction identifier. The system requires linking the refund request to its originating payment via IDs so that your agent can accurately retrieve the correct details using `get_refund`. **How can I efficiently get payment details after listing multiple customers using `list_customers`?** You should first use `list_customers` to gather all necessary IDs. Then, iterate through those IDs calling the relevant tools for each customer—like `get_customer` or related endpoints—to build your full data set. **How do I get Hyperswitch API credentials?** You can find your API Secret Key in the Hyperswitch dashboard under 'API Keys'. **Does it support multiple processors?** Hyperswitch is a payment switch that abstracts multiple processors. This MCP interacts with the Hyperswitch unified API. **Can I process refunds with this MCP?** This version focus on listing and retrieving refund details. Actions to trigger new refunds may be added in future updates.