Connect Midtrans to Claude: Orchestrate QRIS, VA & Transaction Status

If your team needs to connect Midtrans to Claude to automate payment orchestration, issue refunds, or track QRIS and Virtual Account (VA) transaction statuses, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and the Midtrans REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Midtrans to ChatGPT or explore our broader architectural overview on connecting Midtrans to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling payment gateway like Midtrans is a massive engineering challenge. You have to handle complex API authentication schemas, map massive JSON payloads to MCP tool definitions, and deal with Midtrans's strict transactional state machines. Every time Midtrans updates an endpoint to comply with Bank Indonesia regulations (like the BI-SNAP standards), you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Midtrans, connect it natively to Claude, and execute complex payment operations using natural language.

The Engineering Reality of the Midtrans API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a payment gateway's APIs is painful. You are not just integrating a simple database - you are interacting with financial networks, e-wallets, and credit card acquirers, all of which have different operational constraints.

If you decide to build a custom MCP server for Midtrans, you own the entire API lifecycle. Here are the specific challenges you will face:

The BI-SNAP Protocol Migration Bank Indonesia mandated the National Standard Open API Payment (BI-SNAP) protocol. Midtrans now enforces this for specific endpoints (like Virtual Accounts, Direct Debit, and QRIS). SNAP endpoints require complex asymmetric and symmetric cryptography for request signing (e.g., generating a SHA-256 hash of the payload, signing it with an RSA private key, and passing specific X-TIMESTAMP and X-SIGNATURE headers). An LLM cannot generate these cryptographic signatures on the fly. Your MCP server must intercept the LLM's raw intent, generate the correct SNAP headers, and proxy the request to Midtrans. A managed MCP server abstracts this away entirely, presenting Claude with a clean, flat JSON schema.

Complex Payment State Machines Midtrans transactions do not simply return a success or failure boolean. They follow a strict state machine: authorize, capture, settlement, deny, cancel, expire, and pending. If Claude tries to refund a transaction that is still pending or authorize, the API will throw an error. The model must explicitly check the transaction_status first, determine if a capture is required (for credit cards), or if the transaction is ready for refund (if in settlement state). Without strict tool schemas guiding this logic, LLMs will hallucinate state transitions and fail.

Endpoint Fragmentation Across Payment Types The way you handle a GoPay Tokenization transaction is completely different from a standard credit card charge. Refunding a standard transaction uses the Core API /v2/{id}/refund, but refunding a QRIS or Direct Debit transaction requires hitting specific BI-SNAP /v1.0/qr/qr-mpm-refund endpoints. You must build an abstraction layer that presents a unified set of tools to Claude, hiding the underlying endpoint fragmentation.

Handling Midtrans Rate Limits When building against Midtrans, you will hit rate limits (for example, the BIN lookup endpoint is strictly capped at 100 requests per minute). Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API like Midtrans returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your MCP client or agent framework is entirely responsible for managing retry and backoff logic.

Generating a Midtrans MCP Server

Truto's MCP server feature turns any connected Midtrans account into an MCP-compatible JSON-RPC 2.0 endpoint. Truto dynamically derives the tool definitions from its underlying proxy API documentation, ensuring Claude only sees highly curated, accurately described endpoints.

There are two ways to generate your Midtrans MCP server URL: via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

If you are setting up an internal tool or testing locally with Claude Desktop, the Truto UI is the fastest path.

1. Log into your Truto environment and navigate to the Integrated Accounts list.
2. Select the specific Midtrans connection you want to expose to Claude.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. For a read-only support agent, you might check only the read method filter to ensure Claude cannot accidentally capture funds or issue refunds.
6. Click Generate and copy the resulting MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

If you are building a multi-tenant platform where every one of your customers brings their own Midtrans keys, you must generate MCP servers programmatically on their behalf.

You do this by making a POST request to the /integrated-account/:id/mcp endpoint. Truto will validate the requested tool filters, generate a cryptographically secure token, and return the server URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Midtrans FinOps Agent Server",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["transactions", "qris", "virtual_accounts"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API responds with the active server URL:

{
  "id": "mcp_8a9b0c1d",
  "name": "Midtrans FinOps Agent Server",
  "url": "https://api.truto.one/mcp/f7e8d9c0b1a2...",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["transactions", "qris", "virtual_accounts"]
  }
}

This URL is fully self-contained. It encodes the tenant routing, the allowed tools, and the authentication token.

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your Claude environment. You can do this through the Claude UI or via a configuration file for local development.

Method A: Via the Claude UI

If you are using an Enterprise or Team plan with web-based connector management:

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
2. Provide a recognizable name (e.g., "Midtrans Production").
3. Paste the Truto MCP URL into the Server URL field.
4. Click Add.

Claude will immediately handshake with the Truto server, execute the tools/list JSON-RPC method, and map the available Midtrans endpoints into its context window.

Method B: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally to build and test agents, you must edit the claude_desktop_config.json file. Because Truto MCP servers operate over standard HTTPS connections, you use the official @modelcontextprotocol/server-sse package to proxy the local stdio connection into an SSE (Server-Sent Events) HTTP transport.

Locate your config file at ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the following configuration:

{
  "mcpServers": {
    "midtrans": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The application will boot the SSE client, connect to Truto, and pull the Midtrans tool definitions.

Hero Tools for Midtrans

The Truto MCP server maps Midtrans's complex architecture into clean, callable tools. By abstracting away the BI-SNAP signatures and pagination, Claude can focus purely on business logic. Here are the highest-leverage tools available for orchestrating payments.

midtrans_transactions_get_status_b_2_b

This tool retrieves the B2B transaction status for a specific order ID or transaction ID. It is essential for determining the current state of a payment (pending, settlement, etc.) before attempting any subsequent actions like refunds or captures.

"Check the transaction status for order ID 'INV-2026-0899'. What is the current fraud status and settlement time?"

midtrans_qris_create_qr

This tool generates a QRIS MPM (Merchant Presented Mode) QR code transaction. It handles the BI-SNAP requirements automatically. It requires payment_type and transaction_details to return the acquirer data and the URL to generate the QR image.

"Generate a new QRIS payment for order 'QR-9941' for 50000 IDR. Provide the URL where the customer can scan the code."

midtrans_virtual_account_create_va

This tool provisions a new Virtual Account using the BI-SNAP Core API. It requires the partnerServiceId, customerNo, and totalAmount. This is critical for B2B invoicing where clients pay via bank transfer.

"Create a new Virtual Account for customer number '8849302' with a total amount of 1500000 IDR using partner service ID 'BCA'."

midtrans_transactions_refund

This tool initiates a refund for a transaction that has already reached the settlement state. It supports standard credit cards, GoPay, ShopeePay, and QRIS. It requires the order_id_or_transaction_id and will return the refund_chargeback_id.

"Issue a full refund for transaction ID '65a7d9f-1234'. Tell me the refund chargeback ID once it succeeds."

midtrans_transactions_cancel

This tool voids a Midtrans transaction. It is specifically used for transactions that have not yet been settled (e.g., still in pending or authorize states). If a transaction is already settled, Claude must use the refund tool instead.

"Cancel the pending transaction for order ID 'CART-8123' since the customer changed their mind before capturing the payment."

midtrans_subscriptions_cancel

This tool cancels a recurring payment subscription by its ID, stopping all future charges and pending retries from previous failed attempts.

"Cancel the subscription for ID 'sub-1938472'. Confirm when the status message returns success."

For a complete list of all available Midtrans endpoints, schemas, and required parameters, visit the Midtrans integration page.

Workflows in Action

When Claude has access to the Midtrans MCP server, it can orchestrate multi-step payment operations that usually require custom backend scripts. Here are real-world examples of how AI agents interact with the payment gateway.

Scenario 1: The Automated Refund and Reconciliation Flow

Customer support agents often waste time looking up transaction statuses in the Midtrans dashboard before issuing refunds. Claude can automate this safely by checking the state machine rules first.

"A customer requested a refund for order INV-8812. Please check if the payment is actually settled. If it is, issue a full refund and give me the reference ID."

Step-by-step execution:

1. Claude calls list_all_midtrans_transactions passing order_id: "INV-8812" to retrieve the current state.
2. Claude parses the JSON response and observes that transaction_status is equal to settlement.
3. Because the status allows for a refund, Claude calls midtrans_transactions_refund with the transaction ID.
4. Claude returns a natural language summary to the support rep: "The order was settled yesterday. I have successfully processed the refund. The chargeback ID is ref_88192a."

sequenceDiagram
    participant User as Support Agent
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant API as Midtrans API
    
    User->>Claude: Refund order INV-8812 if settled
    Claude->>MCP: Call list_all_midtrans_transactions<br>{"order_id": "INV-8812"}
    MCP->>API: GET /v2/INV-8812/status
    API-->>MCP: status: "settlement"
    MCP-->>Claude: JSON response
    Claude->>MCP: Call midtrans_transactions_refund<br>{"order_id": "INV-8812"}
    MCP->>API: POST /v2/INV-8812/refund
    API-->>MCP: refund_chargeback_id: "ref_88192a"
    MCP-->>Claude: JSON response
    Claude-->>User: Refund successful, ID ref_88192a

Scenario 2: Orchestrating a QRIS Payment Generation

Field sales reps or self-serve kiosks need to generate localized payment methods dynamically. Claude can generate a QRIS code and instruct the user on the next steps.

"I am closing a sale for $50 (750,000 IDR) for customer 'Jane Doe'. Generate a QRIS payment code for order ID 'POS-554' and give me the image link to display."

Step-by-step execution:

1. Claude structures the payload for midtrans_qris_create_qr, formatting the transaction_details block with order_id: "POS-554" and gross_amount: 750000.
2. Claude calls the tool via the MCP server.
3. The Truto MCP server translates this request, applies the necessary BI-SNAP cryptography, and routes it to Midtrans.
4. Midtrans returns the QR configuration data. Claude extracts the actions array to find the URL for the QR code image.
5. Claude presents the image link to the user: "Here is the QRIS code for Jane Doe. Please have her scan this URL: https://api.midtrans.com/v2/qris/12345/qr-code"

Scenario 3: Investigating Denied Transactions

When the Midtrans Fraud Detection System (FDS) flags a transaction, it places it in a challenge or deny state. FinOps teams need to investigate these rapidly.

"List the details for transaction ID 'tx_9921'. If the fraud status is 'challenge', go ahead and approve it."

Step-by-step execution:

1. Claude calls list_all_midtrans_transactions for tx_9921.
2. Claude examines the transaction_status and fraud_status fields in the response.
3. Upon seeing fraud_status: "challenge", Claude triggers the midtrans_transactions_approve tool for that specific ID.
4. Claude reports the success: "The transaction was challenged by the FDS. I have manually approved it, and it will now proceed to settlement."

Security and Access Control

Giving an AI agent access to a live financial gateway requires strict security boundaries. Truto's MCP architecture provides several layers of control to ensure your Midtrans environment remains secure:

• Method Filtering: Limit the server to specific HTTP methods. You can restrict an agent to only use read operations, completely blocking it from executing create, update, or delete actions (like generating transactions or issuing refunds).
• Tag Filtering: Restrict access to specific functional domains. By configuring the server with tags: ["virtual_accounts"], the agent will only be able to view and manage VA tools, keeping it away from credit card routing or subscription management.
• API Token Authentication: Enable require_api_token_auth to force the MCP client to pass a valid Truto API token in the header. This means possession of the MCP URL alone is useless without valid secondary credentials.
• Automatic Expiration: Use the expires_at parameter to generate short-lived, ephemeral MCP servers. The underlying KV storage and Durable Object alarms will automatically destroy the server token at the specified time, ensuring temporary contractors or temporary agent instances don't leave lingering access vectors.

Architecting Financial AI Workflows

Integrating AI with payment infrastructure like Midtrans is no longer a theoretical exercise - it is a production requirement for FinOps automation and advanced customer support. However, building custom integration code to handle BI-SNAP crypto, state machine validation, and API maintenance defeats the agility that LLMs provide.

By leveraging a managed MCP server, you eliminate the integration debt. Truto handles the dynamic tool generation, the proxy routing, and the API normalizations, allowing your engineers to focus on designing reliable agent workflows instead of reading payment gateway documentation.