@yuno-payments/agent-toolkit

AI framework integrations for the Yuno payment orchestrator

The Yuno Agent Toolkit connects AI agents to Yuno's payment APIs through function calling. Yuno is a payment orchestrator — it routes transactions across multiple providers (Stripe, Adyen, PayPal, dLocal, MercadoPago, and others) and intelligently selects the best path for each payment.

Features

• 🚀 6 Framework Integrations — Vercel AI SDK, Google Genkit, LangChain, OpenAI Chat, OpenAI Agents SDK, MCP Server
• 🔒 Type-Safe — Full TypeScript with comprehensive types
• 📦 Modular — Import only what you need (customers, payments, etc.)
• 🌎 LatAm First — Built for PIX, PSE, OXXO, Boleto, SPEI, and more
• 📚 Prompt Guide — See PROMPTS.md for 300+ example prompts

Installation

npm install @yuno-payments/agent-toolkit

Requirements: Node.js 18+ • A Yuno account with API credentials

Quick Start

Prerequisites

Set your Yuno credentials:

YUNO_ACCOUNT_CODE=your_account_code
YUNO_PUBLIC_API_KEY=your_public_api_key
YUNO_PRIVATE_SECRET_KEY=your_private_secret_key

Get these from the Yuno Dashboard.

Available Integrations

| Framework | Import Path | Creation | |-----------|------------|---------| | Vercel AI SDK | @yuno-payments/agent-toolkit/ai-sdk | createYunoAgentToolkit() | | Google Genkit | @yuno-payments/agent-toolkit/genkit | createYunoGenkitToolkit() | | LangChain | @yuno-payments/agent-toolkit/langchain | YunoLangChainToolkit.create() | | OpenAI Chat | @yuno-payments/agent-toolkit/openai | createYunoOpenAIToolkit() | | OpenAI Agents SDK | @yuno-payments/agent-toolkit/openai-agents | createYunoOpenAIAgentsToolkit() | | MCP Server | @yuno-payments/agent-toolkit/modelcontextprotocol | createYunoMcpServer() |

Vercel AI SDK

import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { createYunoAgentToolkit } from "@yuno-payments/agent-toolkit/ai-sdk";

const toolkit = await createYunoAgentToolkit({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
});

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools: toolkit.getTools(),
  stopWhen: stepCountIs(10),
  prompt: "Create a customer named Maria Garcia with email [email protected]",
});

await toolkit.close();

Google Genkit

Note: Genkit requires passing an ai instance at creation time or to each method call.

import { genkit, z } from "genkit";
import { googleAI, gemini15Pro } from "@genkit-ai/googleai";
import { createYunoGenkitToolkit } from "@yuno-payments/agent-toolkit/genkit";

const ai = genkit({ plugins: [googleAI()] });

const toolkit = await createYunoGenkitToolkit({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
  ai,
});

const agent = ai.definePrompt({
  name: "paymentAgent",
  model: gemini15Pro,
  tools: toolkit.getToolsArray(),
  input: { schema: z.object({ query: z.string() }) },
});

const result = await agent({ query: "Create a customer named Jane Smith" });
await toolkit.close();

LangChain

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { YunoLangChainToolkit } from "@yuno-payments/agent-toolkit/langchain";

const toolkit = await YunoLangChainToolkit.create({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
  actions: {
    customers: { create: true, retrieve: true },
    payments: { retrieve: true },
  },
});

const tools = toolkit.getTools();
// Use with LangChain agents...

await toolkit.close();

OpenAI Chat

Note: The OpenAI Chat integration requires a manual tool call loop. Use handleToolCall() to execute tool calls from the LLM response.

import OpenAI from "openai";
import { createYunoOpenAIToolkit } from "@yuno-payments/agent-toolkit/openai";

const toolkit = await createYunoOpenAIToolkit({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
});

const client = new OpenAI();
const response = await client.chat.completions.create({
  model: "gpt-4o",
  tools: toolkit.getTools(),
  messages: [{ role: "user", content: "List my customers" }],
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await toolkit.handleToolCall(
    toolCall.function.name,
    toolCall.function.arguments,
  );
  console.log(result);
}

await toolkit.close();

OpenAI Agents SDK

import { Agent, run } from "@openai/agents";
import { createYunoOpenAIAgentsToolkit } from "@yuno-payments/agent-toolkit/openai-agents";

const toolkit = await createYunoOpenAIAgentsToolkit({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
});

const agent = new Agent({
  name: "Yuno Payment Agent",
  instructions: "You are a payment assistant powered by Yuno.",
  tools: toolkit.getTools(),
});

const result = await run(agent, "Create a customer named Maria Garcia");
await toolkit.close();

MCP Server

Use as a local MCP server for Claude Desktop, Cursor, or any MCP client:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createYunoMcpServer } from "@yuno-payments/agent-toolkit/modelcontextprotocol";

const server = await createYunoMcpServer({
  accountCode: process.env.YUNO_ACCOUNT_CODE!,
  publicApiKey: process.env.YUNO_PUBLIC_API_KEY!,
  privateSecretKey: process.env.YUNO_PRIVATE_SECRET_KEY!,
});

const transport = new StdioServerTransport();
await server.connect(transport);

Configuration

Action Filtering

Control which tools are available to the agent:

const toolkit = await createYunoAgentToolkit({
  // ...credentials
  actions: {
    customers: { create: true, retrieve: true },
    payments: { retrieve: true, refund: true },
    // Only specified actions are enabled
  },
});

⚠️ Note: Action filtering is a client-side convenience, not a security boundary. For production security, use scoped API keys.

To enable all tools:

import { ALL_TOOLS_ENABLED } from "@yuno-payments/agent-toolkit/ai-sdk";

const toolkit = await createYunoAgentToolkit({
  // ...credentials
  actions: ALL_TOOLS_ENABLED,
});

Context

Set environment and merchant context:

const toolkit = await createYunoAgentToolkit({
  // ...credentials
  context: {
    sandbox: true,       // Use sandbox environment
    merchantId: "m_123", // Merchant context
    countryCode: "CO",   // Country context
  },
});

Billing / Usage Tracking

Track tool call usage with a callback:

const toolkit = await createYunoAgentToolkit({
  // ...credentials
  billing: {
    onToolCall: (event) => {
      console.log(`${event.toolName} took ${event.durationMs}ms (${event.success ? "ok" : "fail"})`);
    },
  },
});

Category Methods

All toolkits expose category methods for selective tool loading:

toolkit.getTools()          // All tools
toolkit.customers()         // Customer management
toolkit.payments()          // Payment processing
toolkit.checkoutSessions()  // Checkout sessions
toolkit.paymentMethods()    // Payment methods
toolkit.subscriptions()     // Subscriptions
toolkit.paymentLinks()      // Payment links
toolkit.recipients()        // Recipients (payouts)
toolkit.installmentPlans()  // Installment plans
toolkit.routing()           // Routing configuration

Available Tools

Customer Management

• customerCreate — Create a new customer
• customerRetrieve — Retrieve customer by ID
• customerRetrieveByExternalId — Retrieve by external ID
• customerUpdate — Update customer information

Payment Processing

• paymentCreate — Create a payment
• paymentRetrieve — Retrieve payment details
• paymentRetrieveByMerchantOrderId — Retrieve by order ID
• paymentRefund — Refund a payment
• paymentCancel — Cancel a pending payment
• paymentCancelOrRefund — Smart cancel/refund based on payment state
• paymentCancelOrRefundWithTransaction — Cancel/refund a specific transaction
• paymentAuthorize — Authorize without capture
• paymentCaptureAuthorization — Capture an authorized payment

Checkout Sessions

• checkoutSessionCreate — Create a checkout session
• checkoutSessionCreateOtt — Generate a one-time token
• checkoutSessionRetrievePaymentMethods — Get available payment methods

Payment Methods

• paymentMethodEnroll — Save a payment method
• paymentMethodRetrieve — Get payment method details
• paymentMethodRetrieveEnrolled — List saved methods
• paymentMethodUnenroll — Remove a saved method

Subscriptions

• subscriptionCreate / Retrieve / Update / Pause / Resume / Cancel

Payment Links

• paymentLinkCreate / Retrieve / Cancel

Recipients, Installment Plans, Routing

• Full CRUD operations — see PROMPTS.md for details

Documentation

• documentationRead — Search Yuno's docs from within the agent

Prompt Guide

See PROMPTS.md for 300+ example prompts covering every tool, multi-tool orchestration scenarios, and LatAm-specific payment flows (PIX, PSE, OXXO, Boleto, SPEI, installments).

Architecture

AI Agent / LLM
    ↓
Framework Adapter (AI SDK / Genkit / LangChain / OpenAI / MCP)
    ↓
@yuno-payments/agent-toolkit (tool definitions + filtering)
    ↓  MCP Protocol (StreamableHTTP)
Remote MCP Server (mcp.prod.y.uno)
    ↓
Yuno Payment Orchestrator → Multiple Providers

The toolkit is a thin client that connects to Yuno's remote MCP server. Tool definitions, validation, and API routing all happen server-side — new tools and fixes ship without SDK updates.

Development

npm install
npm run build
npm run typecheck
npm run lint
npm run test

License

MIT © Yuno Payments

Links

• 📖 Yuno Documentation
• 🔑 Yuno Dashboard
• 🐛 Report Issues

Made with ❤️ by Yuno Payments