PayPal

npx add-mcp 'https://mcp.paypal.com/mcp'

Bộ công cụ PayPal Agent

Bộ công cụ PayPal Agent cho phép các framework agent phổ biến bao gồm OpenAI's Agent SDK, LangChain, Vercel's AI SDK và Model Context Protocol (MCP) tích hợp với API PayPal thông qua function calling. Bộ công cụ này hỗ trợ TypeScript và được xây dựng trên nền tảng API PayPal và PayPal SDKs.

Các công cụ có sẵn

Bộ công cụ PayPal Agent cung cấp các công cụ sau:

Hóa đơn

• create_invoice: Tạo hóa đơn mới trong hệ thống PayPal, bao gồm thông tin thanh toán của người nhận, chi tiết dòng sản phẩm, ghi chú hóa đơn, chủ đề màu tùy chỉnh, chi phí vận chuyển tùy chọn và tùy chọn bật PAY_BY_BANK làm phương thức thanh toán

• list_invoices: Liệt kê hóa đơn với phân trang và lọc tùy chọn

• get_invoice: Truy xuất chi tiết của một hóa đơn cụ thể

• send_invoice: Gửi hóa đơn đến người nhận

• send_invoice_reminder: Gửi lời nhắc cho hóa đơn hiện có

• cancel_sent_invoice: Hủy hóa đơn đã gửi

• generate_invoice_qr_code: Tạo mã QR cho hóa đơn

• delete_invoice: Xóa vĩnh viễn hóa đơn nháp hoặc hóa đơn đã lên lịch

• generate_invoice_number: Tạo số hóa đơn tiếp theo có sẵn cho người bán

• search_invoicing: Tìm kiếm hóa đơn hoặc chuỗi hóa đơn định kỳ

• update_invoicing: Cập nhật hóa đơn hiện có hoặc chuỗi hóa đơn định kỳ (thay thế toàn bộ)

• cancel_invoice_auto_reminder: Hủy tất cả lời nhắc tự động đã lên lịch cho một hóa đơn

• record_payment_for_invoice: Ghi nhận thanh toán bên ngoài hoặc thanh toán thủ công cho một hóa đơn

• record_refund_for_invoice: Ghi nhận hoàn tiền cho một hóa đơn

• create_conditional_rules_for_invoice: Tạo quy tắc có điều kiện cho hóa đơn, chẳng hạn như chiết khấu thanh toán sớm hoặc ngày tự động hủy

• create_recurring_series: Tạo chuỗi hóa đơn định kỳ tự động tạo và gửi hóa đơn theo lịch trình

• activate_recurring_series: Kích hoạt chuỗi hóa đơn định kỳ ở dạng nháp

• get_recurring_series: Truy xuất chi tiết của một chuỗi hóa đơn định kỳ cụ thể

• cancel_recurring_series: Hủy chuỗi hóa đơn định kỳ đang hoạt động

• delete_recurring_series: Xóa chuỗi hóa đơn định kỳ ở dạng nháp

Thanh toán

• create_order: Tạo đơn hàng trong hệ thống PayPal dựa trên thông tin chi tiết được cung cấp
• get_order: Truy xuất chi tiết của một đơn hàng
• pay_order: Xử lý thanh toán cho đơn hàng đã được ủy quyền
• create_refund: Xử lý hoàn tiền cho khoản thanh toán đã thu
• get_refund: Lấy chi tiết cho một khoản hoàn tiền cụ thể

Quản lý tranh chấp

• list_disputes: Truy xuất tóm tắt tất cả các tranh chấp đang mở
• get_dispute: Truy xuất thông tin chi tiết của một tranh chấp cụ thể
• accept_dispute_claim: Chấp nhận yêu cầu tranh chấp

Theo dõi lô hàng

• create_shipment_tracking: Tạo bản ghi theo dõi lô hàng
• get_shipment_tracking: Truy xuất thông tin theo dõi lô hàng
• update_shipment_tracking: Cập nhật thông tin theo dõi lô hàng

Quản lý danh mục

• create_product: Tạo sản phẩm mới trong danh mục PayPal
• list_products: Liệt kê sản phẩm với phân trang và lọc tùy chọn
• show_product_details: Truy xuất chi tiết của một sản phẩm cụ thể

Quản lý đăng ký

• create_subscription_plan: Tạo gói đăng ký mới
• list_subscription_plans: Liệt kê các gói đăng ký
• show_subscription_plan_details: Truy xuất chi tiết của một gói đăng ký cụ thể
• create_subscription: Tạo đăng ký mới
• show_subscription_details: Truy xuất chi tiết của một đăng ký cụ thể
• update_subscription: Cập nhật đăng ký hiện có
• cancel_subscription: Hủy đăng ký đang hoạt động

Báo cáo và Thông tin chi tiết

• list_transactions: Liệt kê giao dịch với phân trang và lọc tùy chọn
• get_merchant_insights: Truy xuất số liệu thông minh kinh doanh và phân tích cho người bán

TypeScript

Cài đặt

Bạn không cần mã nguồn này trừ khi bạn muốn sửa đổi gói. Nếu bạn chỉ muốn sử dụng gói, hãy chạy:

npm install @paypal/agent-toolkit

Yêu cầu

• Node 18+

Cách sử dụng

Thư viện cần được cấu hình với client id và secret của tài khoản bạn, có sẵn trong PayPal Developer Dashboard.

Bộ công cụ hoạt động với Vercel's AI SDK và có thể được truyền dưới dạng danh sách các công cụ. Để biết thêm chi tiết, hãy tham khảo ví dụ của chúng tôi.

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 },
    },
  },
});

Để sử dụng chế độ sandbox, hãy thêm context trong cấu hình của bạn.

configuration: {
  context: {
    sandbox: true,
  }
}

Khởi tạo Workflows

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,
  },
});

Cách sử dụng

Sử dụng bộ công cụ

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.`,
});

Biến môi trường

Các biến môi trường sau có thể được sử dụng:

• PAYPAL_ACCESS_TOKEN: PayPal Access Token của bạn
• PAYPAL_ENVIRONMENT: Đặt thành SANDBOX cho chế độ sandbox, PRODUCTION cho môi trường production (mặc định là chế độ SANDBOX)

Hướng dẫn này giải thích cách tạo access token cho tích hợp API PayPal, bao gồm cách tìm client ID và client secret của bạn.

Điều kiện tiên quyết

• Tài khoản PayPal Developer (cho Sandbox)
• Tài khoản PayPal Business (cho production)

Tìm Client ID và Client Secret của bạn

1. Tạo tài khoản PayPal Developer:

   • Truy cập PayPal Developer Dashboard
   • Đăng ký hoặc đăng nhập bằng thông tin PayPal của bạn

2. Truy cập thông tin xác thực của bạn:

   • Trong Developer Dashboard, nhấp vào Apps & Credentials trong menu
   • Chuyển đổi giữa chế độ Sandbox và Live tùy theo nhu cầu của bạn

3. Tạo hoặc xem một App:

   • Để tạo app mới, nhấp vào Create App
   • Đặt tên cho app của bạn và chọn tài khoản Business để liên kết
   • Đối với app hiện có, nhấp vào tên app để xem chi tiết

4. Truy xuất thông tin xác thực:

   • Sau khi app của bạn được tạo hoặc chọn, bạn sẽ thấy màn hình với:
     • Client ID: Mã định danh công khai cho app của bạn
     • Client Secret: Khóa riêng tư (hiển thị sau khi nhấp vào "Show")
   • Lưu các thông tin xác thực này một cách an toàn vì chúng cần thiết để tạo access token

Tạo Access Token

Sử dụng 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\"

Thay thế CLIENT_ID và CLIENT_SECRET bằng thông tin xác thực thực tế của bạn. Đối với production, sử dụng https://api-m.paypal.com thay vì URL sandbox.

Sử dụng Postman

1. Tạo yêu cầu mới đến https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Đặt phương thức thành POST
3. Trong Authorization, chọn Basic Auth và nhập Client ID và Client Secret của bạn
4. Trong Body, chọn x-www-form-urlencoded và thêm khóa grant_type với giá trị client_credentials
5. Gửi yêu cầu

Phản hồi

Phản hồi thành công sẽ trông như sau:

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

Sao chép giá trị access_token để sử dụng trong tích hợp Claude Desktop của bạn.

Chi tiết Token

• Sandbox Tokens: Có hiệu lực trong 3-8 giờ
• Production Tokens: Có hiệu lực trong 8 giờ
• Nên triển khai logic làm mới token trước khi hết hạn

Sử dụng Token với Claude Desktop

Khi bạn đã có access token, hãy cập nhật giá trị PAYPAL_ACCESS_TOKEN trong cấu hình kết nối Claude Desktop của bạn:

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

Các phương pháp tốt nhất

1. Lưu trữ client ID và client secret một cách an toàn
2. Triển khai logic làm mới token để xử lý token hết hạn
3. Sử dụng token theo môi trường cụ thể (sandbox để kiểm thử, production cho giao dịch thực)
4. Tránh mã hóa cứng token trong mã ứng dụng

Tuyên bố miễn trừ trách nhiệm

Nội dung do AI tạo có thể không chính xác hoặc không đầy đủ. Người dùng có trách nhiệm xác minh độc lập mọi thông tin trước khi sử dụng. PayPal không đảm bảo về độ chính xác của đầu ra và không chịu trách nhiệm cho bất kỳ quyết định, hành động hoặc hậu quả nào phát sinh từ việc sử dụng nội dung này.