Enterprises need autonomous systems to manage payment balances, account monitoring, and transaction settlement at scale without manual intervention. Adyen provides a unified fintech platform with APIs for payment processing, balance management, and account data that agents can safely orchestrate. Agent workflows must enforce narrow task boundaries and explicit decision points when accessing financial APIs, ensuring compliance and auditability. Adyen's account, balance, and transaction endpoints enable agents to build deterministic loops for reconciliation, transfer approval, and settlement monitoring.
What this tutorial covers
- •Outcome: You will build a production-grade TypeScript agent that fetches merchant balances, monitors transaction flows, and initiates authenticated balance transfers with structured decision logic.
- •Endpoints used: `GET /balanceOverview/companies/{companyAccountCode}/balances`, `GET /obeu/aisp/v1/accounts`, `GET /obeu/aisp/v1/accounts/{resourceId}/balances`, `GET /obeu/v1/accounts/{resourceId}/transactions`, `POST /balance-control/api/v2/balanceTransfers`
- •Language: typescript
- •Auth: API key (X-API-Key header) or Bearer token
- •Estimated implementation time: ~20 minutes
Step 1: Define agent responsibilities and decision points for Adyen balance workflows
Production agents require explicit task scoping. Define three narrow responsibilities: fetch merchant balances, retrieve account transactions, and execute balance transfers with approval rules. This ensures Adyen API calls stay within governance boundaries and each agent decision is testable and auditable.
Agent task definitions
Agent responsibilities are now scoped to single, testable functions. Each task has an explicit decision boundary and optional approval threshold to enforce compliance controls.
Step 2: Fetch merchant balances from Adyen for portfolio monitoring
Query Adyen's balance overview endpoint to retrieve available funds, pending balances, and reserve amounts across all merchant accounts under a company account. The agent uses this data to establish baseline portfolio health before initiating transfers or transactions.
Retrieve balance overview
Response:
1{
2 "merchantBalancesOverview": [
3 {
4 "merchantAccount": "MERCHANT_ACCOUNT_1",
5 "availableFund": {
6 "value": 3191,
7 "currency": "USD"
8 },
9 "nextPayout": {
10 "value": 3191,
11 "currency": "USD"
12 },
13 "reserve": {
14 "value": 0,
15 "currency": "USD"
16 }
17 },
18 {
19 "merchantAccount": "MERCHANT_ACCOUNT_2",
20 "availableFund": {
21 "value": 0,
22 "currency": "EUR"
23 },
24 "reserve": {
25 "value": 0,
26 "currency": "EUR"
27 }
28 }
29 ]
30}Step 3: Retrieve Adyen account transactions for settlement verification
Fetch booked transactions for a specific account resource to verify settlement accuracy and detect anomalies in payment flows. Agents use transaction data to audit compliance and trigger alerts when thresholds are exceeded.
Get account transactions
Response:
1{
2 "account": {
3 "iban": "NL91ABNA0417164300",
4 "currency": "EUR"
5 },
6 "balances": [
7 {
8 "balanceType": "expected",
9 "balanceAmount": {
10 "amount": "24.24",
11 "currency": "EUR"
12 }
13 },
14 {
15 "balanceType": "authorised",
16 "balanceAmount": {
17 "amount": "23.49",
18 "currency": "EUR"
19 }
20 }
21 ],
22 "transactions": {
23 "booked": [
24 {
25 "transactionId": "EVJN4227K22322295J23J33BN52T4MEUR",
26 "bookingDate": "2023-06-13T11:37:01",
27 "valueDate": "2023-06-13T11:37:01",
28 "transactionAmount": {
29 "amount": "-10.01",
30 "currency": "EUR"
31 },
32 "creditorName": "Joe Doe",
33 "creditorAccount": {
34 "iban": "NL57INGB4654188101",
35 "currency": "EUR"
36 }
37 }
38 ]
39 }
40}Step 4: Execute balance transfers through Adyen with agent approval gates
Implement a structured transfer workflow where agents can initiate balance transfers between merchant accounts only after approval thresholds are met. Adyen returns a pspReference for every transfer, enabling audit trails and reconciliation with your agent log.
Transfer balance with approval
Response:
1{
2 "merchantAccount": "YOUR_COMPANY_ACCOUNT",
3 "availableFund": {
4 "value": 9889873,
5 "currency": "USD"
6 },
7 "pendingBalance": {
8 "value": -112845,
9 "currency": "USD"
10 },
11 "nextPayout": {
12 "value": 719,
13 "currency": "USD"
14 },
15 "reserve": {
16 "value": 2000,
17 "currency": "USD"
18 },
19 "deposit": {
20 "value": 50000,
21 "currency": "USD"
22 }
23}Step 5: Monitor Adyen account health with continuous agent loops
Build a continuous agent loop that monitors account balances, fetches transactions on a schedule, and triggers alerts when anomalies are detected. This implements the workflow-first orchestration pattern required for production fintech agents.
Production monitoring loop
1import { setInterval } from 'timers';
2
3const monitorAccountHealth = async () => {
4 const accountThreshold = 1000;
5 const checkInterval = 60000;
6
7 setInterval(async () => {
8 const merchantBalancesOverview = [
9 {
10 merchantAccount: "MERCHANT_ACCOUNT_1",
11 availableFund: { value: 3191, currency: "USD" },
12 nextPayout: { value: 3191, currency: "USD" },
13 reserve: { value: 0, currency: "USD" }
14 }
15 ];
16
17 for (const balance of merchantBalancesOverview) {
18 if (balance.availableFund.value < accountThreshold) {
19 console.error(`ALERT: Low balance on ${balance.merchantAccount}: ${balance.availableFund.value} ${balance.availableFund.currency}`);
20 }
21 }
22
23 const transactions = {
24 booked: [
25 {
26 transactionId: "EVJN4227K22322295J23J33BN52T4MEUR",
27 bookingDate: "2023-06-13T11:37:01",
28 transactionAmount: { amount: "-10.01", currency: "EUR" },
29 creditorName: "Joe Doe"
30 }
31 ]
32 };
33
34 console.log(`Fetched ${transactions.booked.length} transactions for anomaly detection`);
35 }, checkInterval);
36};
37
38monitorAccountHealth().catch(err => console.error(err));The agent now runs a structured, observable loop that fetches data, makes decisions based on thresholds, and logs every action for audit. This is the production pattern for agentic fintech workflows.
Common pitfalls when using Adyen
- •Approval thresholds without rate limiting. Agents without rate-limiting safeguards can trigger many transfers in rapid succession, overwhelming Adyen's API. Implement a per-agent request queue with backpressure and maximum transfers per time window before allowing autonomous execution.
- •No observability on decision logic. Production agents must log every decision: which balance threshold triggered an action, why a transfer was approved or rejected, and the pspReference returned by Adyen. Without detailed logs, you cannot audit or debug agent behavior in a regulated environment.
- •Task scope creep and role ambiguity. Avoid assigning an agent to 'manage all payments.' Instead, scope each agent to fetch balances OR verify transactions OR execute transfers—never all three. Narrow task boundaries make agents testable and compliant with governance.
- •Missing fallback for API failures. If an Adyen API call fails, agents must not retry indefinitely or escalate transfers without human oversight. Implement circuit breakers, exponential backoff, and explicit escalation rules so Adyen outages do not cause agent loops to fail silently.
Ready to deploy agent-driven payment operations? Get started with Adyen's balance, account, and transaction APIs to build compliant, auditable workflows at enterprise scale.
Documentation references
The code examples in this tutorial are grounded in the following docs pages:
- •
- •
- •
Transform enterprise payments with Adyen’s platform
Join industry leaders using Adyen to process payments securely, gain actionable insights, and expand globally with ease.