Paypal

PayPal Agent Toolkit

PayPal Agent Toolkit 支持 OpenAI 的 Agent SDK、LangChain、Vercel 的 AI SDK 和 Model Context Protocol（MCP）等热门 Agent 框架通过函数调用集成 PayPal API。它支持 TypeScript，并基于 PayPal API 和 PayPal SDK 构建。

可用工具

PayPal Agent Toolkit 提供以下工具：

发票

• create_invoice：在 PayPal 系统中创建新发票，包括收件人账单详情、行项目、发票备注、自定义颜色主题、可选运费，以及启用 PAY_BY_BANK 作为付款方式的选项

• list_invoices：列出发票，可选择分页和筛选

• get_invoice：获取特定发票的详情

• send_invoice：向收件人发送发票

• send_invoice_reminder：发送现有发票的提醒

• cancel_sent_invoice：取消已发送的发票

• generate_invoice_qr_code：生成发票二维码

• delete_invoice：永久删除草稿或已安排的发票

• generate_invoice_number：生成商家可用的下一个发票编号

• search_invoicing：搜索发票或定期发票系列

• update_invoicing：更新现有发票或定期发票系列（完全替换）

• cancel_invoice_auto_reminder：取消发票的所有已安排自动提醒

• record_payment_for_invoice：记录针对发票的外部或手动付款

• record_refund_for_invoice：记录针对发票的退款

• create_conditional_rules_for_invoice：为发票创建条件规则，例如提前付款折扣或自动取消日期

• create_recurring_series：创建定期发票系列，按计划自动生成并发送发票

• activate_recurring_series：启用草稿定期发票系列

• get_recurring_series：获取特定定期发票系列的详情

• cancel_recurring_series：取消有效的定期发票系列

• delete_recurring_series：删除草稿定期发票系列

付款

• create_order：根据提供的详情在 PayPal 系统中创建订单
• get_order：获取订单详情
• pay_order：处理已授权订单的付款
• create_refund：处理已捕获付款的退款。
• get_refund：获取特定退款的详情。

争议管理

• list_disputes：获取所有未解决争议的摘要
• get_dispute：获取特定争议的详细信息
• accept_dispute_claim：接受争议索赔

货运跟踪

• create_shipment_tracking：创建货运跟踪记录
• get_shipment_tracking：获取货运跟踪信息
• update_shipment_tracking：更新货运跟踪信息

目录管理

• create_product：在 PayPal 商品目录中创建新商品
• list_products：列出商品，可选择分页和筛选
• show_product_details：获取特定商品的详情

订阅管理

• create_subscription_plan：创建新的订阅计划
• list_subscription_plans：列出订阅计划
• show_subscription_plan_details：获取特定订阅计划的详情
• create_subscription：创建新订阅
• show_subscription_details：获取特定订阅的详情
• update_subscription：更新现有订阅
• cancel_subscription：取消有效订阅

报告与洞察

• list_transactions：列出交易，可选择分页和筛选
• get_merchant_insights：获取商家的商业智能指标和分析数据

TypeScript

安装

除非你想修改此软件包，否则无需获取此源代码。如果只想使用此软件包，请运行：

npm install @paypal/agent-toolkit

要求

• Node 18+

用法

该库需要配置您账户的客户端 ID 和密钥，您可以在 PayPal 开发者控制台 中找到它们。

该工具包可与 Vercel 的 AI SDK 配合使用，并可作为工具列表传入。更多详情请参阅我们的示例

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,
        createRecurringSeries: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        delete: true,
        generateQRC: true,
        generateInvoiceNumber: true,
        search: true,
        update: true,
        cancelReminders: true,
        recordPayment: true,
        recordRefund: true,
        createConditionalRules: 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 },
    },
  },
});

若要使用沙盒模式，请在配置中添加上下文。

configuration: {
  context: {
    sandbox: 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.`,
});

环境变量

可以使用以下环境变量：

• PAYPAL_ACCESS_TOKEN：您的 PayPal 访问令牌
• PAYPAL_ENVIRONMENT：沙盒模式设为 SANDBOX，生产环境设为 PRODUCTION（默认为 SANDBOX 模式）

本指南介绍如何为 PayPal API 集成生成访问令牌，包括如何查找客户端 ID 和客户端密钥。

前提条件

• PayPal 开发者账户（用于沙盒）
• PayPal 企业账户（用于生产环境）

查找客户端 ID 和客户端密钥

1. 创建 PayPal 开发者账户：

   • 前往 PayPal 开发者控制台
   • 使用您的 PayPal 凭据注册或登录

2. 访问您的凭据：

   • 在开发者控制台的菜单中，点击 Apps & Credentials
   • 根据需要在 Sandbox 和 Live 模式之间切换

3. 创建或查看应用：

   • 若要创建新应用，请点击 Create App
   • 为应用命名，并选择要与其关联的企业账户
   • 对于现有应用，点击应用名称即可查看详情

4. 获取凭据：

   • 创建或选定应用后，您会看到一个页面，其中包含：
     • 客户端 ID：应用的公开标识符
     • 客户端密钥：私钥（点击 "Show" 后显示）
   • 请安全保存这些凭据，因为生成访问令牌时需要用到它们

生成访问令牌

使用 cURL

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\"

请将 CLIENT_ID 和 CLIENT_SECRET 替换为您的实际凭据。对于生产环境，请使用 https://api-m.paypal.com，而不是沙盒 URL。

使用 Postman

1. 创建一个新请求，目标为 https://api-m.sandbox.paypal.com/v1/oauth2/token
2. 将方法设为 POST
3. 在 Authorization 下，选择 Basic Auth 并输入您的客户端 ID 和客户端密钥
4. 在 Body 下，选择 x-www-form-urlencoded，并添加键 grant_type，值为 client_credentials
5. 发送请求

响应

成功的响应如下所示：

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

复制 access_token 的值，以便在 Claude Desktop 集成中使用。

令牌详情

• 沙盒令牌：有效期为 3-8 小时
• 生产令牌：有效期为 8 小时
• 建议在令牌过期前实现令牌刷新逻辑

在 Claude Desktop 中使用令牌

获取访问令牌后，请更新 Claude Desktop 连接器配置中的 PAYPAL_ACCESS_TOKEN 值：

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

最佳实践

1. 安全存储客户端 ID 和客户端密钥
2. 实现令牌刷新逻辑以处理令牌过期
3. 使用特定环境的令牌（测试时使用沙盒令牌，实际交易时使用生产令牌）
4. 避免在应用代码中硬编码令牌

免责声明

AI 生成的内容可能不准确或不完整。用户有责任在依赖任何信息之前独立核实。PayPal 不保证输出准确性，也不对因使用输出而导致的任何决定、行为或后果承担责任。