Connect Adyen to AI Agents: Handle Onboarding, Balances, and Transfers

You want to connect Adyen to an AI agent so your system can autonomously handle payment links, process refunds, manage merchant onboarding, and orchestrate treasury transfers. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom financial integration from scratch.

Giving a Large Language Model (LLM) read and write access to a global payments processor is an exercise in extreme precision. When AI agents write data back to Adyen, a hallucination does not just cause a broken string - it can initiate unauthorized transfers or improperly formatted refunds. If your team uses ChatGPT, check out our guide on connecting Adyen to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Adyen 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 Adyen, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex financial operations workflows safely. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

The Engineering Reality of the Adyen API

Giving an LLM access to external 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 against a tier-one financial system like Adyen, this approach collapses.

Adyen's API is engineered for extreme scale, strict consistency, and regulatory compliance. It introduces specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Minor Units Trap

Financial APIs do not use floating-point numbers for currency because of inherent precision errors in computing. Adyen requires all amounts to be specified in minor units. To charge $10.00 USD, you do not send 10.00. You send 1000.

Standard LLMs are terrible at remembering this unprompted. If a user asks the agent to "Refund the customer 50 dollars", a naive agent will send "value": 50 to the Adyen API, resulting in a 50-cent refund. You cannot rely on system prompts alone to fix this. You need a strict, schema-enforced tool layer that explicitly defines the modificationAmount.value field as requiring minor units, rejecting non-compliant payloads before they ever reach the Adyen gateway.

Asynchronous Eventual Consistency

Adyen relies heavily on webhooks for state changes. When you tell Adyen to capture a payment or process a refund via the API, the response is often an HTTP 202 Accepted or a status of Received. The actual outcome (success, failure, chargeback) arrives asynchronously via an HTTPS webhook (e.g., AUTHORISATION, REFUND, or CAPTURE events).

Agents operate linearly. An agent expects to call a function and get the final result back immediately to inform its next step. If your tool simply returns "status": "Received", the agent might prematurely tell the user "The refund was successfully processed." You must design your integration architecture to bridge this gap - either by having the agent hand off long-running state to a background process, or by designing workflows that acknowledge the asynchronous nature of the financial network.

sequenceDiagram
    participant Agent as AI Agent
    participant ToolLayer as Tool Layer
    participant AdyenCore as Adyen API
    participant Webhook as Webhook Listener
    Agent->>ToolLayer: Call create_a_adyen_refund
    ToolLayer->>AdyenCore: POST /payments/{id}/refunds
    AdyenCore-->>ToolLayer: 202 Accepted (Received)
    ToolLayer-->>Agent: {"status": "received", "pspReference": "12345"}
    Note right of Agent: Agent notifies user:<br>"Refund initiated." 
    AdyenCore->>Webhook: REFUND webhook (async)

The Rate Limit Reality

Adyen enforces strict rate limits depending on the endpoint and the environment (test vs live). A common architectural mistake is assuming the API gateway or integration layer will magically absorb and queue these limits for the agent.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

This means your agent framework is entirely responsible for retry and backoff logic. If the agent hits a 429, it must be capable of reading the ratelimit-reset header, waiting the appropriate duration, and invoking the tool call again without losing its context window.

High-Leverage Adyen AI Agent Tools

To safely expose Adyen to an LLM, you use Truto's /tools endpoint to fetch Proxy APIs. These are standardized schemas that map directly to Adyen's resources but handle the boilerplate of authentication and pagination.

Here are the highest-leverage Adyen tools to expose to your AI agents for autonomous operations.

create_a_adyen_payment_link

Conversational commerce and collections rely on secure checkout pages. This tool allows the agent to dynamically generate a Pay by Link page where the shopper can pay using localized methods. The agent passes the amount, currency, and reference, and receives a short URL to hand back to the user.

"Generate a payment link for 250 EUR for invoice INV-9982 and set it to expire in 24 hours."

create_a_adyen_payment_refund

Customer support bots frequently need to process partial or full refunds. This tool interacts with Adyen's checkout API to refund a captured payment. The agent must specify the original payment's PSP reference and the exact modification amount in minor units.

"The customer returned one of the shirts. Process a partial refund of 30 GBP against payment reference 881625374."

create_a_adyen_dispute

Chargebacks and disputes require rapid operational response. This tool allows a backend agent to programmatically raise a dispute or update its status. When combined with defense document endpoints, an agent can autonomously gather evidence from your CRM and challenge fraudulent chargebacks.

"We received a chargeback alert for transaction 992837. Raise a new dispute for this transaction citing not-delivered-info, and prepare the shipping manifest."

list_all_adyen_merchant_balances

For treasury and finance ops agents, visibility into liquidity is critical. This tool lists the available balances for an Adyen merchant account, including settled funds, pending balances, the next payout schedule, and reserves.

"Check the available and pending EUR balances for our European merchant account so we can schedule the weekly vendor payouts."

create_a_adyen_transfer

Moving money between accounts, transfer instruments, or third-party bank accounts is a core function for marketplace platforms. This tool orchestrates funds transfers within Adyen's Balance Platform. It requires the agent to specify the category, counterparty, and strict amount schemas.

"Initiate a transfer of 5000 USD from the main platform balance account to vendor VEND-404's transfer instrument."

create_a_adyen_legal_entity

For platforms onboarding sub-merchants, compliance (KYC/AML) is a massive operational bottleneck. This tool allows an agent to create a legal entity in Adyen to begin the verification process, capturing organization details and capabilities required for processing funds.

"Onboard the new marketplace seller 'Acme Corp'. Create a legal entity for them as an organization and flag them for standard verification checks."

To view the complete inventory of available Adyen endpoints, schemas, and parameters, visit the Adyen integration page.

Workflows in Action

Individual tools are useful, but chaining them together creates autonomous revenue and support operations. Here is how specific personas use these tools in production.

Support Agent: Autonomous Refund Processing

Customer support teams spend hours verifying returns and manually clicking "Refund" in the Adyen dashboard. An AI agent can handle the triage and execution safely.

"User ID 40599 says their package never arrived. Verify the tracking, and if it is lost, refund their original payment in full."

1. Agent Context: The agent queries an internal database (or Shopify via another Truto tool) to find the Adyen PSP reference for the user's last order.
2. External Verification: The agent checks the shipping carrier tool. The carrier reports the package as "Lost in Transit."
3. create_a_adyen_payment_refund: The agent formats the payload, ensuring the amount is converted to minor units (e.g., $45.00 becomes 4500), and executes the refund against the Adyen API.
4. Handoff: The agent emails the user confirming the refund has been initiated, noting that banking networks may take 3 - 5 days to clear the funds.

Treasury Agent: Automated Payout Reconciliation

Finance teams need to balance liquidity across regions. An agent can monitor merchant balances and initiate transfers when thresholds are met.

"Check our UK merchant account balance. If the available settled funds exceed 50,000 GBP, transfer 40,000 GBP to our primary corporate treasury account."

1. list_all_adyen_merchant_balances: The agent queries the balance for the specified merchant account ID.
2. Logic evaluation: The agent parses the response. It identifies that availableFund is 55,000 GBP.
3. create_a_adyen_transfer: The agent executes a transfer for 40,000 GBP (4000000 minor units) to the pre-configured corporate counterparty ID.
4. Audit Logging: The agent logs the transfer ID and the remaining balance into the finance team's Slack channel.

Building Multi-Step Workflows

To build these workflows, you need to bind Truto's proxy APIs to your LLM. Because Truto standardizes the schemas, you can pull tools dynamically using the Truto SDK and pass them to frameworks like LangChain, CrewAI, or the Vercel AI SDK.

Below is a TypeScript example using the TrutoToolManager from the truto-langchainjs-toolset.

Crucially, notice the error handling block. Because Truto passes raw 429 rate limit errors from Adyen, your agent execution loop must intercept these errors, read the standard ratelimit-reset header, and implement its own backoff.

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runAdyenAgent(prompt: string, integratedAccountId: string) {
  // 1. Initialize the LLM
  const model = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Fetch Adyen tools dynamically from Truto
  const toolManager = new TrutoToolManager({
    trutoEnvironmentId: process.env.TRUTO_ENV_ID,
    integratedAccountId: integratedAccountId,
  });
 
  // Only load tools related to payments and links for this agent
  const tools = await toolManager.getTools({
    methods: ["create_a_adyen_payment_link", "create_a_adyen_payment_refund"],
  });
 
  // 3. Bind the tools to the LLM
  const modelWithTools = model.bindTools(tools);
 
  // 4. Initialize agent state
  const messages = [
    new SystemMessage("You are a financial operations agent. ALWAYS convert currency to minor units (e.g., multiply by 100 for USD/EUR) before interacting with the API."),
    new HumanMessage(prompt)
  ];
 
  console.log("Executing workflow...");
 
  // 5. The Agent Loop (with Rate Limit Handling)
  while (true) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);
 
    if (!response.tool_calls || response.tool_calls.length === 0) {
      console.log("Final Answer:", response.content);
      break;
    }
 
    // Execute each tool call
    for (const toolCall of response.tool_calls) {
      const tool = tools.find((t) => t.name === toolCall.name);
      if (tool) {
        try {
          const result = await tool.invoke(toolCall.args);
          messages.push({
            role: "tool",
            tool_call_id: toolCall.id,
            content: JSON.stringify(result),
          });
        } catch (error: any) {
          // CRITICAL: Truto passes 429s directly. We must handle backoff.
          if (error.response && error.response.status === 429) {
            const resetTime = error.response.headers['ratelimit-reset'];
            console.warn(`Rate limit hit. Waiting until ${resetTime} before retrying...`);
            // In a production system, implement a sleep/retry queue here
            messages.push({
              role: "tool",
              tool_call_id: toolCall.id,
              content: JSON.stringify({ error: "Rate limit exceeded. System paused." }),
            });
          } else {
            messages.push({
              role: "tool",
              tool_call_id: toolCall.id,
              content: JSON.stringify({ error: error.message }),
            });
          }
        }
      }
    }
  }
}
 
// Example execution
runAdyenAgent(
  "Create a payment link for 500 EUR for reference 'INV-8832'", 
  "your-adyen-account-id"
);

By collapsing Adyen's massive endpoint surface area into discrete, schema-validated tools, the LLM is fenced into safe execution paths. It does not invent payloads, and invalid arguments are rejected by the Tool Manager before they are sent over the network.

Closing the Loop on Financial Automation

Integrating Adyen into an autonomous AI agent is not about raw connectivity - it is about safety, schema adherence, and operational resilience. Direct integration requires you to build heavy translation layers to protect the LLM from API quirks like minor unit conversions, JSON:API structures, and raw rate limit errors.

Using a unified tool layer standardizes the interface. Your agent framework handles the reasoning and the rate-limit backoff, while the infrastructure layer handles the auth tokens, endpoint routing, and schema validation. This separation of concerns is what allows engineering teams to ship production-grade financial AI agents in days rather than quarters.