---
title: "Connect Midtrans to Claude: Orchestrate QRIS, VA & Transaction Status"
slug: connect-midtrans-to-claude-orchestrate-qris-va-transaction-status
date: 2026-09-07
author: Nachi Raman
categories: ["AI & Agents"]
excerpt: "Learn how to connect Midtrans to Claude using a managed MCP server. This guide covers orchestrating QRIS, Virtual Accounts, refunds, and transaction statuses."
tldr: "Connect Midtrans to Claude via Truto's managed MCP server to orchestrate payments. We cover bypassing BI-SNAP cryptography complexity, securely generating tools, and building FinOps AI workflows."
canonical: https://truto.one/blog/connect-midtrans-to-claude-orchestrate-qris-va-transaction-status/
---

# 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](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). 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](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), 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](https://truto.one/connect-midtrans-to-chatgpt-manage-payments-refunds-subscriptions/) or explore our broader architectural overview on [connecting Midtrans to AI Agents](https://truto.one/connect-midtrans-to-ai-agents-automate-gopay-linking-billing-flows/).

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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/), and execute complex payment operations using natural language.

> Want to give your AI agents secure, authenticated access to Midtrans and 100+ other SaaS APIs? Let's talk about managed MCP architecture.
>
> [Talk to us](https://truto.one/book-a-demo/)

## 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](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). 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.

```bash
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:

```json
{
  "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:

```json
{
  "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](https://truto.one/integrations/detail/midtrans).

## 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."*

```mermaid
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.

> Ready to orchestrate Midtrans transactions with Claude? Let's talk about secure MCP architecture for your AI agents.
>
> [Talk to us](https://truto.one/book-a-demo/)