Connect JustiFi to Claude: Process Payments, Checkouts & Disputes

If you need to connect JustiFi to Claude to automate payment processing, sub-account onboarding, or dispute management, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and JustiFi's complex financial 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 JustiFi to ChatGPT or explore our broader architectural overview on connecting JustiFi to AI Agents.

Giving a Large Language Model (LLM) read and write access to an embedded fintech platform like JustiFi is a significant engineering challenge. You are not just dealing with simple CRUD operations; you are orchestrating multi-party payouts, handling PCI-sensitive flows through tokenized web components, and reconciling complex ledger data. Every time JustiFi updates an endpoint or deprecates a parameter, 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 MCP server for JustiFi, connect it natively to Claude, and execute complex financial workflows using natural language.

The Engineering Reality of the JustiFi 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 embedded finance APIs is painful.

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

Complex Multi-Entity Hierarchies JustiFi is built for platforms. Almost every meaningful operation requires navigating a strict hierarchy: Platform Accounts manage Sub Accounts, which are tied to Businesses, which have Identities (owners), which map to Bank Accounts. If you simply expose a raw create_a_justi_fi_payment endpoint to Claude without context, the model will hallucinate sub_account_id or platform_account_id values. You have to build specific relational logic into your MCP tool descriptions so the LLM knows it must query the sub-account list before attempting to configure fee structures or payouts for a specific merchant.

Strict Payment Tokenization Rules Unlike legacy gateways where you might pass raw card data, JustiFi strictly enforces PCI compliance via its Web Component. You cannot use the API to directly create a payment method using raw PANs (Primary Account Numbers) unless you have specific elevated permissions and PCI-DSS certification. Creating a JustiFi payment via API requires passing a payment_token generated by the frontend. Your MCP server must properly document these constraints in the JSON Schema so Claude understands it can only process payments against pre-tokenized methods or existing checkouts, rather than asking the user for their credit card number.

Unforgiving Rate Limits Without Built-in Retries Financial APIs enforce strict rate limits to prevent abuse and fraud. When you hit these limits, JustiFi returns an HTTP 429 Too Many Requests error. It is a critical architectural requirement that your middleware handles this correctly. Truto does not retry, throttle, or apply backoff on rate limit errors. Instead, when JustiFi returns a 429, Truto passes that error directly to the caller, normalizing the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (your AI agent or Claude client) is strictly responsible for interpreting these headers and executing its own exponential backoff and retry logic.

Instead of spending weeks building this boilerplate, mapping JSON schemas, and managing authentication tokens, you can use Truto to dynamically generate a managed MCP server.

How to Generate a JustiFi MCP Server with Truto

Truto's MCP architecture turns any connected JustiFi account into an MCP-compatible JSON-RPC 2.0 endpoint. Rather than hand-coding tool definitions, Truto derives them dynamically from JustiFi's resource definitions and API documentation.

You can generate your JustiFi MCP server using either the Truto UI or the API.

Method 1: Via the Truto UI

For internal tooling and administrative agents, generating a server via the dashboard is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected JustiFi account.
2. Click the MCP Servers tab.
3. Click the Create MCP Server button.
4. Select your desired configuration (name, allowed methods like read or write, tags, and optional expiration limits).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

If you are provisioning AI agents programmatically for your end-users, you can generate MCP servers on the fly via the Truto API. This validates that the JustiFi integration has tools available, generates a secure hashed token, and returns a ready-to-use URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "JustiFi Finance Agent MCP",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["payments", "payouts", "disputes"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response contains the exact URL your LLM client needs to connect:

{
  "id": "mcp_abc123",
  "name": "JustiFi Finance Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["payments", "payouts", "disputes"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude is a matter of configuration. The server is completely self-contained - the cryptographic token in the URL handles routing and authentication to the specific JustiFi tenant.

Method A: Via the Claude UI

If you are using Claude Desktop or Claude for Enterprise, you can add the server directly through the application settings.

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server (or "Add custom connector" depending on your tier).
3. Provide a recognizable name (e.g., "JustiFi Operations").
4. Paste the Truto MCP server URL you generated earlier.
5. Click Add.

Claude will immediately initialize the connection, perform the JSON-RPC handshake, and discover the available JustiFi tools.

Method B: Via Manual Config File (Claude Desktop)

For developers managing their own Claude Desktop configurations, you can add the server by editing your claude_desktop_config.json file. Because Truto provides a remote SSE (Server-Sent Events) endpoint, you use the standard @modelcontextprotocol/server-sse package to proxy the connection.

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

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

Restart Claude Desktop. The model will now have direct access to your JustiFi environment.

Hero Tools for JustiFi

Truto automatically translates JustiFi's API documentation into LLM-friendly schemas. By injecting cursor-based pagination instructions and standardizing required fields, Truto ensures Claude understands exactly how to invoke each operation.

Here are 6 high-leverage hero tools your AI agent can use to manage your JustiFi environment.

list_all_justi_fi_sub_accounts

Retrieves a list of all sub-accounts associated with your JustiFi platform. This is typically the foundational tool Claude must call to discover the correct sub_account_id before executing targeted operations like creating checkouts or checking payout settings.

"Fetch all active sub-accounts on the platform and build a table showing their names, account types, and current operational statuses."

create_a_justi_fi_checkout

Generates a hosted checkout session to initiate the collection of a card, ACH, or card reader payment in a single, PCI-compliant flow. This returns a checkout_id and a URL that can be sent to customers.

"Create a new checkout session for $1,500.00 USD for the 'Annual SaaS Subscription' invoice. Return the secure checkout link so I can email it to the client."

list_all_justi_fi_payouts

Lists the payouts distributed from JustiFi to the connected bank accounts. This tool is essential for financial reconciliation, allowing the agent to verify when funds from processed checkouts actually settled into the merchant's account.

"List all payouts for the sub-account associated with 'Acme Corp' over the last 7 days. Summarize the total amount deposited versus the total fees collected."

list_all_justi_fi_disputes

Retrieves chargebacks and disputes lodged against payments processed on the platform. Claude can use this tool to triage incoming disputes, check deadlines (due_date), and extract the reason codes provided by the issuing banks.

"Find any new disputes created this week. Create a summary of the disputed amounts, the reasons provided by the cardholders, and the deadline for us to respond to each one."

create_a_justi_fi_dispute_response

Submits a formal response to an active dispute, either contesting it with evidence or explicitly forfeiting the funds. This is a critical workflow automation that saves finance teams hours of manual portal work.

"Forfeit the dispute on payment ID pmt_8x9y0z because the amount is under our $15 threshold for contesting chargebacks."

create_a_justi_fi_report

Triggers the asynchronous generation of financial reports (e.g., interchange fees, proceeds, sub-account summaries). Claude can initiate the report generation, then periodically check the status to retrieve the presigned download URL.

"Generate an interchange fee report for last month. Once it is queued, give me the report ID so we can poll for the download link later."

For a complete list of available JustiFi tools and their detailed JSON schemas, visit the JustiFi integration page.

Workflows in Action

Exposing individual endpoints to an LLM is useful, but the real power of MCP lies in autonomous workflow orchestration. Here is how Claude handles complex, multi-step JustiFi operations.

Workflow 1: Automated Dispute Triage and Forfeiture

Finance teams waste hours manually reviewing low-value chargebacks. You can instruct Claude to act as a Level 1 dispute analyst, automatically forfeiting disputes below a certain financial threshold.

"Review all open disputes in JustiFi. If the disputed amount is less than $25.00 USD and the reason is 'fraudulent', automatically forfeit the dispute. For all others, create a summary report of the payment IDs and due dates."

Step-by-step execution:

1. Claude calls list_all_justi_fi_disputes with a filter for the 'open' status.
2. It analyzes the returned JSON array, isolating objects where the amount is under 2500 cents and the reason matches fraud parameters.
3. For each matching dispute, Claude iterates and calls create_a_justi_fi_dispute_response passing forfeit: true.
4. Claude aggregates the remaining high-value disputes and outputs a formatted Markdown summary to the user.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant JustiFi as JustiFi API

    User->>Claude: "Review open disputes..."
    Claude->>MCP: Call list_all_justi_fi_disputes
    MCP->>JustiFi: GET /v1/disputes
    JustiFi-->>MCP: Returns array of disputes
    MCP-->>Claude: JSON response
    Claude->>Claude: Filter for amount < 2500 & fraud
    Claude->>MCP: Call create_a_justi_fi_dispute_response (forfeit: true)
    MCP->>JustiFi: POST /v1/disputes/{id}/response
    JustiFi-->>MCP: Success confirmation
    MCP-->>Claude: JSON response
    Claude-->>User: Returns summary of forfeited and pending disputes

Workflow 2: End-to-End Invoice to Checkout Generation

Sales and support reps frequently need to generate payment links on the fly without logging into a separate billing portal.

"The customer at Acme Logistics needs to pay their setup fee of $500. Find their sub-account, generate a payment checkout link, and draft a polite email sending them the link."

Step-by-step execution:

1. Claude calls list_all_justi_fi_sub_accounts to find the internal JustiFi ID for 'Acme Logistics'.
2. It extracts the exact id string for that merchant.
3. Claude calls create_a_justi_fi_checkout, passing the amount (50000 cents), currency (USD), a description ("Setup Fee"), and the target account ID.
4. The tool returns the checkout object containing the secure hosted URL.
5. Claude drafts the email content directly in the chat interface, embedding the secure link.

Workflow 3: Payout Reconciliation Analysis

Operations teams struggle to map gross payment volume to actual net bank deposits due to withheld fees and platform cuts.

"Look up the payout history for the past 14 days. Calculate our total platform net revenue after JustiFi fees, and verify if any payouts are currently in a 'held' status."

Step-by-step execution:

1. Claude calls list_all_justi_fi_payouts filtering by the last two weeks.
2. It analyzes the amount (gross), fees_total, and refunds_total fields across the dataset.
3. Claude calls list_all_justi_fi_payout_holds to check for active holds.
4. It performs the math (Gross - Fees - Refunds) and delivers a concise financial summary, highlighting any funds trapped by active risk holds.

Security and Access Control

Giving AI agents access to your fintech infrastructure requires strict security boundaries. Truto provides four native enforcement layers that act directly on the MCP server token:

• Method Filtering: Use config.methods to enforce read-only access. Passing ["read"] ensures the agent can query payouts and disputes, but cannot create checkouts, refund payments, or forfeit disputes.
• Tag Filtering: Scope the server to specific operational domains using config.tags. You can restrict an agent to ["reports"] so it can only generate financial exports, blocking it from accessing core payment workflows.
• Extra Authentication: Enable require_api_token_auth: true to force the client to pass a valid Truto API token in the Authorization header. This ensures that even if the MCP URL is leaked, unauthorized users cannot execute tools.
• Ephemeral Servers: Set an expires_at ISO datetime when creating the MCP server. Truto will automatically destroy the token and flush it from edge KV storage at the exact specified time, perfect for granting temporary access to automated CI/CD pipelines or short-lived agent sessions.

Architecting for Agentic Finance

Building integrations for LLMs requires fundamentally different infrastructure than traditional point-to-point software. AI agents need standardized pagination, pristine schemas, and predictable JSON-RPC transport layers to function without hallucinating.

By routing your JustiFi integration through Truto's MCP servers, you eliminate the boilerplate of schema mapping, OAuth lifecycles, and endpoint maintenance. Your engineering team can focus on designing complex financial workflows and reconciliation logic, while Truto handles the translation between natural language and the REST API.