@paypal/agent-toolkit
Advanced tools
The PayPal Agent Toolkit enables popular agent frameworks including OpenAI's Agent SDK, LangChain, Vercel's AI SDK, Model Context Protocol (MCP), and Amazon Bedrock to integrate with PayPal APIs through function calling. It includes support for TypeScript and is built on top of PayPal APIs and the PayPal SDKs.
The PayPal Agent toolkit provides the following tools:
Invoices
create_invoice: Create a new invoice in the PayPal systemlist_invoices: List invoices with optional pagination and filteringget_invoice: Retrieve details of a specific invoicesend_invoice: Send an invoice to recipientssend_invoice_reminder: Send a reminder for an existing invoicecancel_sent_invoice: Cancel a sent invoicegenerate_invoice_qr_code: Generate a QR code for an invoicePayments
create_order: Create an order in PayPal system based on provided detailsget_order: Retrieve the details of an orderpay_order: Process payment for an authorized ordercreate_refund: Process a refund for a captured payment.get_refund: Get the details for a specific refund.Dispute Management
list_disputes: Retrieve a summary of all open disputesget_dispute: Retrieve detailed information of a specific disputeaccept_dispute_claim: Accept a dispute claimShipment Tracking
create_shipment_tracking: Create a shipment tracking record
get_shipment_tracking: Retrieve shipment tracking information
update_shipment_tracking: Update shipment tracking information
Catalog Management
create_product: Create a new product in the PayPal catalog
list_products: List products with optional pagination and filtering
show_product_details: Retrieve details of a specific product
Subscription Management
create_subscription_plan: Create a new subscription planupdate_plan: Update an existing planlist_subscription_plans: List subscription plansshow_subscription_plan_details: Retrieve details of a specific subscription plancreate_subscription: Create a new subscriptionshow_subscription_details: Retrieve details of a specific subscriptionupdate_subscription: update an existing subscriptioncancel_subscription: Cancel an active subscriptionReporting and Insights
list_transactions: List transactions with optional pagination and filteringget_merchant_insights: Retrieve business intelligence metrics and analytics for a merchantYou don't need this source code unless you want to modify the package. If you just want to use the package run:
npm install @paypal/agent-toolkit
The library needs to be configured with your account's client id and secret which is available in your PayPal Developer Dashboard. Use configuration to add context as well as to specify which actions should be allowed.
import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
clientId: process.env.PAYPAL_CLIENT_ID,
clientSecret: process.env.PAYPAL_CLIENT_SECRET,
configuration: {
actions: {
invoices: {
create: true,
list: true,
send: true,
sendReminder: true,
cancel: true,
generateQRC: true,
},
products: { create: true, list: true, update: true },
subscriptionPlans: { create: true, list: true, show: true },
shipment: { create: true, show: true, cancel: true },
orders: { create: true, get: true },
disputes: { list: true, get: true },
},
},
});
import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
clientId: process.env.PAYPAL_CLIENT_ID,
clientSecret: process.env.PAYPAL_CLIENT_SECRET,
configuration: {
actions: ALL_TOOLS_ENABLED,
},
});
const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
model: llm,
tools: paypalToolkit.getTools(),
maxSteps: 10,
prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});
let messages: ChatCompletionMessageParam[] = [
{
role: "user",
content: "Create an PayPal order for $50 for Premium News service.",
},
];
const completion = await llm.chat.completions.create({
model: "gpt-4o",
messages,
tools: paypalToolkit.getTools(),
});
const agent = createReactAgent({
llm: llm,
tools: tools,
});
const result = await agent.invoke(
{
messages: [{
role: "user",
content: "Create an PayPal order for $50 for Premium News service."
}]
}
);
const userMessage = "Create one PayPal order for $50 for Premium News service with 10% tax.";
let messages: Message[] = [
{
role: "user",
content: [{ text: userMessage }],
}
]
const response = await client.send(
new ConverseCommand({
modelId: modelId,
messages: messages,
toolConfig: {
tools: tools
}
}),
);
The PayPal Model Context Protocol server allows you to integrate with PayPal APIs through function calling. This protocol supports various tools to interact with different PayPal services.
To run the PayPal MCP server using npx, use the following command:
npx -y @paypal/mcp --tools=all PAYPAL_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PAYPAL_ENVIRONMENT="SANDBOX"
Replace YOUR_ACCESS_TOKEN with active access token generated using these steps: PayPal access token. Alternatively, you could set the PAYPAL_ACCESS_TOKEN in your environment variables.
You can set up your own MCP server. For example:
import { PayPalAgentToolkit } from “@paypal/agent-toolkit/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const orderSummary = await paypalWorkflows.generateOrder(
llm,
transactionInfo,
merchantInfo,
);
const server = new PayPalAgentToolkit({
accessToken: process.env.PAYPAL_ACCESS_TOKEN
});
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("PayPal MCP Server running on stdio");
}
main().catch((error) => {
console.error("Fatal error in main():", error);
process.exit(1);
});
This guide explains how to integrate the PayPal connector with Claude Desktop.
Node.js is required for the PayPal connector to function:
We will show the integration with Claude desktop. You can use your favorite MCP host.
{
"mcpServers": {
"paypal": {
"command": "npx",
"args": [
"-y",
"@paypal/mcp",
"--tools=all"
],
"env": {
"PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
"PAYPAL_ENVIRONMENT": "SANDBOX"
}
}
}
}
Make sure to replace YOUR_PAYPAL_ACCESS_TOKEN with your actual PayPal Access Token. Alternatively, you could set the PAYPAL_ACCESS_TOKEN as an environment variable. You can also pass it as an argument using --access-token in "args"
Set PAYPAL_ENVIRONMENT value as either SANDBOX for stage testing and PRODUCTION for production environment.
The following environment variables can be used:
PAYPAL_ACCESS_TOKEN: Your PayPal Access TokenPAYPAL_ENVIRONMENT: Set to SANDBOX for sandbox mode, PRODUCTION for production (defaults to SANDBOX mode)This guide explains how to generate an access token for PayPal API integration, including how to find your client ID and client secret.
Create a PayPal Developer Account:
Access Your Credentials:
Create or View an App:
Retrieve Credentials:
curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
-H \"Accept: application/json\" \\
-H \"Accept-Language: en_US\" \\
-u \"CLIENT_ID:CLIENT_SECRET\" \\
-d \"grant_type=client_credentials\"
Replace CLIENT_ID and CLIENT_SECRET with your actual credentials. For production, use https://api-m.paypal.com instead of the sandbox URL.
https://api-m.sandbox.paypal.com/v1/oauth2/tokengrant_type with value client_credentialsA successful response will look like:
{
"scope": "...",
"access_token": "Your Access Token",
"token_type": "Bearer",
"app_id": "APP-80W284485P519543T",
"expires_in": 32400,
"nonce": "..."
}
Copy the access_token value for use in your Claude Desktop integration.
Once you have your access token, update the PAYPAL_ACCESS_TOKEN value in your Claude Desktop connector configuration:
{
"env": {
"PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
"PAYPAL_ENVIRONMENT": "SANDBOX"
}
}
AI-generated content may be inaccurate or incomplete. Users are responsible for independently verifying any information before relying on it. PayPal makes no guarantees regarding output accuracy and is not liable for any decisions, actions, or consequences resulting from its use.
FAQs
PayPal toolkit for AI agent workflows in typescript
We found that @paypal/agent-toolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 26 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.