Skip to content
Truto
Truto Blog
Back
AI & Agents

Connect JustiFi to AI Agents: Automate Payouts, Fees & Reporting

Learn how to connect JustiFi to ai agents using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Sidharth Verma Sidharth Verma · · 10 min read
Connect JustiFi to AI Agents: Automate Payouts, Fees & Reporting

You want to connect JustiFi to an AI agent so your internal financial systems can independently orchestrate payouts, update sub-account fee configurations, onboard business entities, and generate reconciliation reports. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code dozens of endpoints or maintain complex payment integration wrappers.

Giving a Large Language Model (LLM) read and write access to a fintech platform like JustiFi is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom connector that handles the intricacies of financial data states, or you use a managed infrastructure layer that handles the boilerplate for you. If your team relies on OpenAI's interface, check out our guide on connecting JustiFi to ChatGPT, or if you are building primarily with Anthropic's models, read our guide on connecting JustiFi to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for JustiFi, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex financial operations workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom JustiFi Connectors

Building AI agents is easy. Connecting them to external fintech APIs is hard. Giving an LLM access to external payment data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely, especially with an ecosystem as sensitive and state-heavy as JustiFi.

If you decide to build a direct API integration yourself, you own the entire API lifecycle. JustiFi's API introduces several highly specific integration challenges that break standard LLM assumptions.

The Temporal Fee Configuration Trap

JustiFi manages fee structures using a temporal ledger system. When you want to change a fee, you do not simply PATCH /fees/:id. The API uses an active/retired model governed by effective_start and effective_end timestamps. Creating a new Standard Fee Configuration for a specific fee type on a sub-account automatically retires the previous configuration by setting its effective_end. There is no traditional update or delete operation for active fees.

If you hand-code this integration, you have to write complex prompts to teach the LLM the exact lifecycle of these fee models. When the LLM inevitably hallucinates a DELETE request or attempts to PATCH a fee cap, the request fails. Worse, if the LLM misunderstands the timestamp logic, it could accidentally schedule fees incorrectly.

Deprecated Entities and Migration Paths

Fintech APIs evolve rapidly. JustiFi has deprecated several core endpoints in favor of new paradigms. For example, direct sub-account creation via the API is deprecated for new platforms; they must use Hosted Onboarding or Onboarding via API instead. Similarly, the Proceeds Report endpoint is deprecated in favor of the newer Reports API.

If you pass raw JustiFi API documentation to an LLM, the model cannot distinguish between active and deprecated endpoints unless heavily prompted. It will try to use the legacy sub-account creation flow, resulting in failed calls and broken workflows.

Stateful Payment Lifecycles

The payment capture lifecycle is strictly timed. Authorized payments in JustiFi are automatically canceled after 7 days if not captured. Voiding a payment is only possible within a strict 25-minute window of the original transaction, or if the authorized payment has a manual capture strategy that has not yet been triggered.

LLMs are stateless text predictors. They do not inherently track time windows or strict state machines. If an agent tries to void a payment 48 hours after capture, the API will reject it. You have to write extensive defensive code to validate states before allowing the tool call to execute.

Why a Unified Proxy Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools (one tool per raw JustiFi endpoint) look convenient but they push provider quirks into the LLM's context. The model has to remember pagination limits, complex query parameters, and deprecated object structures.

Truto's approach sits in front of the raw APIs. Every integration on Truto maps underlying product APIs into a REST-based CRUD model using Resources and Methods. These methods handle pagination, authentication, and query parameter processing automatically. We then expose these pre-processed methods via the /tools endpoint, giving your agent a clean, standardized schema.

This gives you concrete safety wins:

  1. Smaller attack surface for hallucination. The LLM only chooses from defined, active tools. It never invents deprecated endpoint structures.
  2. Deterministic input validation. Every tool has a strict JSON schema derived from the Method definition. Invalid arguments are rejected before they hit JustiFi.
  3. Abstracted pagination. The LLM does not need to manage cursor tokens or page_info loops. The proxy handles data retrieval boundaries.

Handling JustiFi Rate Limits Programmatically

When deploying AI agents in production, rate limiting becomes a primary failure vector. Agents can loop rapidly, attempting to query hundreds of payments or payout records in seconds.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. Truto's proxy layer is designed for deterministic execution. When the upstream JustiFi API returns an HTTP 429 Too Many Requests, Truto passes that 429 error directly back to your caller.

However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification. Regardless of how JustiFi formats its specific rate limit responses, Truto returns:

  • ratelimit-limit: The maximum number of requests permitted in the current window.
  • ratelimit-remaining: The number of requests remaining in the current window.
  • ratelimit-reset: The time (in seconds or timestamp format) until the rate limit window resets.

The caller (your agent framework or custom backend) is responsible for reading these headers and implementing retry or exponential backoff logic. Do not assume the integration layer will absorb these spikes. You must configure your LangChain or LangGraph execution loops to catch 429s, read the ratelimit-reset header, pause execution, and retry the tool call.

Fetching and Binding JustiFi Tools via Truto

To give your AI agent access to JustiFi, you first need to connect an account and fetch the tool definitions.

Truto provides a /tools endpoint that dynamically returns the schema for all active methods on an integrated account. You can use the truto-langchainjs-toolset SDK to automatically fetch and bind these tools to your model.

Step 1: Initialize the Tool Manager

First, install the required packages:

npm install @trutohq/truto-langchainjs-toolset @langchain/openai

Then, initialize the TrutoToolManager with your JustiFi Integrated Account ID and your Truto API key.

import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
 
// Initialize the Truto Tool Manager for your connected JustiFi account
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "your-justifi-integrated-account-id",
});

Step 2: Fetch and Bind the Tools

You can pull all tools, or filter them based on the HTTP methods required (e.g., read-only tools). Once fetched, bind them directly to your LLM.

// Fetch the tools from Truto's dynamic proxy
const justifiTools = await toolManager.getTools();
 
// Initialize your LLM
const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0,
});
 
// Bind the tools natively to the model
const llmWithTools = llm.bindTools(justifiTools);

Step 3: Execute a Function Call with Rate Limit Handling

When you pass a prompt to the bound LLM, it will return a tool call if it decides to execute a JustiFi action. You invoke the tool and handle any potential 429 rate limit errors using the standardized headers.

import { HumanMessage } from "@langchain/core/messages";
 
const response = await llmWithTools.invoke([
  new HumanMessage("List the active fee configurations for sub-account sub_12345")
]);
 
if (response.tool_calls && response.tool_calls.length > 0) {
  for (const toolCall of response.tool_calls) {
    const tool = justifiTools.find((t) => t.name === toolCall.name);
    if (tool) {
      try {
        const result = await tool.invoke(toolCall.args);
        console.log("Tool Execution Result:", result);
      } catch (error) {
        // Handle standard 429 passing from Truto
        if (error.response && error.response.status === 429) {
          const resetTime = error.response.headers.get('ratelimit-reset');
          console.warn(`Rate limited by JustiFi. Reset in ${resetTime} seconds.`);
          // Implement your wait and retry logic here
        } else {
          console.error("Tool execution failed:", error);
        }
      }
    }
  }
}

JustiFi Hero Tools for AI Agents

Truto exposes the full JustiFi API surface as tools. Here are the highest-leverage tools for building autonomous financial operations.

List All Payouts

list_all_justi_fi_payouts

This tool retrieves payouts with optional creation and deposit date filters. Agents use this to reconcile end-of-month financials, verify settlement priorities, and audit refund counts against total payout amounts.

"Fetch all payouts deposited last week. Identify any payouts with a status other than 'paid' and summarize the total fees deducted."

Create a Sub-Account Fee Configuration

create_a_justi_fi_sub_account_fee_configuration

Creates a Standard Fee Configuration for a specific fee type. Crucially, calling this tool automatically retires the previous configuration. Agents can use this to programmatically adjust customer pricing tiers based on contract updates in your CRM.

"Update the transaction fee for sub-account X to 2.5%. Set the variable rate accordingly. Remember this will retire their active rate immediately."

Create a Report

create_a_justi_fi_report

Queues the creation of a report in JustiFi for types like interchange_fee, proceeds, or payout. Since this is an asynchronous job, the agent receives a scheduled status and a presigned URL that becomes active once the run completes.

"Generate an interchange fee report for the platform. Return the scheduled ID so we can poll for the download link in a few minutes."

List All Checkouts

list_all_justi_fi_checkouts

Lists checkouts with filters for payment mode and status. Agents use this to monitor conversion rates, identify abandoned checkouts, or verify application fees on completed transactions.

"List all checkouts from today that are stuck in a 'pending' status. Extract the checkout IDs and the associated payment descriptions."

Create a Business Entity

create_a_justi_fi_entities_businesis

Creates a new business entity in JustiFi, handling the legal name, classification, address, and owner structure. Agents connected to a CRM or onboarding form can use this to push structured KYB (Know Your Business) data directly into the payment system.

"Take the approved merchant data for 'Acme Corp' and create a new business entity in JustiFi. Map their industry classification and assign the provided representative."

Create a Payment Refund

create_a_justi_fi_payment_refund

Issues a full or partial refund against a specific payment ID. Agents can process customer service requests autonomously, validate that the refund reason is logged, and ensure multiple partial refunds do not exceed the total payment amount.

"The customer for payment ID pay_98765 requested a 50% refund due to a missing item. Issue a partial refund for half the payment amount and log the reason as 'partial fulfillment'."

To view the complete schema for these tools and dozens of others, including detailed request parameters for disputes, terminals, and identity verification, visit the JustiFi integration page.

Workflows in Action

When you expose these proxy methods to an agent, you stop writing rigid linear code and start orchestrating goals. Here is how specific personas use these workflows in production.

1. The RevOps Fee Realignment Workflow

Revenue Operations teams frequently adjust merchant fees based on processing volume. Manually updating these across hundreds of sub-accounts is error-prone. An agent can automate this ledger management.

"Audit the active fee configurations for sub-account sub_444. If their current variable rate is higher than 2.9%, issue a new fee configuration setting it exactly to 2.9% to honor their new enterprise contract."

Execution Steps:

  1. The agent calls list_all_justi_fi_sub_account_fee_configurations passing sub_account_id: sub_444.
  2. It inspects the variable_rate in the returned active configuration.
  3. Seeing the rate is 3.5%, the agent calls create_a_justi_fi_sub_account_fee_configuration with the new 2.9% rate.
  4. JustiFi natively retires the 3.5% configuration and applies the new rate. The agent reports back that the pricing tier has been updated.

2. The Automated Dispute Evidence Coordinator

When a chargeback hits, support teams have limited time to compile and submit evidence. An AI agent can detect the dispute and generate the initial response packet by correlating payment data.

"Find any new disputes logged today. For each dispute, extract the payment ID, look up the original payment metadata, and draft a summary of the transaction history for the dispute response."

Execution Steps:

  1. The agent calls list_all_justi_fi_disputes filtering by the current date.
  2. For the identified dispute, it extracts the payment_id and calls get_single_justi_fi_payment_by_id.
  3. The agent reads the payment_method, checkout_id, and timeline from the payment object.
  4. The agent formulates a summary and can either post it to a Slack channel or queue it for a human review before calling create_a_justi_fi_dispute_response.

Building Multi-Step Workflows

To build highly reliable financial agents, you must map the execution flow carefully. Frameworks like LangGraph excel at this by defining nodes for the LLM, the tool execution, and the retry logic.

Because Truto normalizes the JustiFi API into discrete proxy tools, the execution loop remains clean. The agent decides what to do, Truto executes it safely, and standard HTTP behavior is maintained.

Here is what that architecture looks like for a multi-step reporting flow:

sequenceDiagram
    participant Agent as AI Agent (LangGraph)
    participant Truto as Truto Tool Manager
    participant JustiFi as JustiFi API
    
    Agent->>Truto: Call create_a_justi_fi_report<br>{"report_type": "payout"}
    Truto->>JustiFi: POST /reports
    JustiFi-->>Truto: 200 OK (id: rpt_123, status: scheduled)
    Truto-->>Agent: Return Report Scheduled
    
    loop Polling for Status
        Agent->>Agent: Wait 30 seconds
        Agent->>Truto: Call get_single_justi_fi_report_by_id<br>{"id": "rpt_123"}
        Truto->>JustiFi: GET /reports/rpt_123
        
        alt Rate Limit Hit
            JustiFi-->>Truto: 429 Too Many Requests<br>(ratelimit-reset: 15)
            Truto-->>Agent: Throw 429 Error with headers
            Agent->>Agent: Backoff for 15s (Custom Logic)
        else Success
            JustiFi-->>Truto: 200 OK (status: completed, presigned_url: ...)
            Truto-->>Agent: Return Report Data URL
        end
    end

This framework-agnostic approach means you can swap out the LLM provider, switch from LangChain to the Vercel AI SDK, or modify your prompt instructions without ever touching the underlying JustiFi integration code. The proxy layer remains stable, the tools remain strictly validated, and your agent operates safely within the financial system boundaries.

Moving Past Manual Integration Builds

Connecting AI agents to fintech infrastructure like JustiFi does not require building a bespoke service to manage API lifecycles, read rate limit headers, or map complex fee configuration structures.

By leveraging Truto's proxy API architecture and the /tools endpoint, you give your agents deterministic, schema-validated access to the exact resources they need. You maintain complete control over the execution loop, handle backoffs natively, and abstract away the vendor-specific quirks that cause LLMs to hallucinate in production.

More from our Blog