PayPal MCP Server

chính thức

Máy chủ Giao thức Ngữ cảnh Mô hình PayPal cho phép bạn tích hợp với các API PayPal thông qua tính năng gọi hàm. Giao thức này hỗ trợ nhiều công cụ khác nhau để tương tác với các dịch vụ PayPal khác nhau.

GitHub
187

Tài liệu

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 các API PayPal thông qua việc gọi hàm. Nó bao gồm hỗ trợ cho TypeScript và được xây dựng dựa trên các API PayPal và SDK PayPal.

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
  • list_invoices: Liệt kê hóa đơn với phân trang và lọc tùy chọn
  • get_invoice: Lấy chi tiết của một hóa đơn cụ thể
  • send_invoice: Gửi hóa đơn cho 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

Thanh toán

  • create_order: Tạo đơn hàng trong hệ thống PayPal dựa trên chi tiết được cung cấp
  • get_order: Lấy 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: Lấy tóm tắt tất cả các tranh chấp đang mở
  • get_dispute: Lấy thông tin chi tiết của một tranh chấp cụ thể
  • accept_dispute_claim: Chấp nhận khiếu nại tranh chấp

Theo dõi vận chuyển

  • create_shipment_tracking: Tạo bản ghi theo dõi vận chuyển
  • get_shipment_tracking: Lấy thông tin theo dõi vận chuyển
  • update_shipment_tracking: Cập nhật thông tin theo dõi vận chuyển

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: Lấy chi tiết của một sản phẩm cụ thể

Quản lý đăng ký

  • create_subscription_plan: Tạo kế hoạch đăng ký mới
  • list_subscription_plans: Liệt kê các kế hoạch đăng ký
  • show_subscription_plan_details: Lấy chi tiết của một kế hoạch đăng ký cụ thể
  • create_subscription: Tạo đăng ký mới
  • show_subscription_details: Lấy 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: Lấy các chỉ số và phân tích thông minh kinh doanh 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 của bạn, có sẵn trong Bảng Điều Khiển Nhà Phát Triển PayPal.

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

Để sử dụng chế độ sandbox, hãy thêm ngữ cảnh 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: Mã Truy Cập PayPal của bạn
  • PAYPAL_ENVIRONMENT: Đặt thành SANDBOX cho chế độ sandbox, PRODUCTION cho production (mặc định là chế độ SANDBOX)

Hướng dẫn này giải thích cách tạo mã truy cập để 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 Nhà Phát Triển PayPal (cho Sandbox)
  • Tài khoản Doanh Nghiệp PayPal (cho production)

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

  1. Tạo Tài Khoản Nhà Phát Triển PayPal:

  2. Truy Cập Thông Tin Xác Thực của Bạn:

    • Trong Bảng Điều Khiển Nhà Phát Triển, 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 Ứng Dụng:

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

  4. Lấy Thông Tin Xác Thực:

    • Khi ứng dụng 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 ứng dụng của bạn
      • Client Secret: Khóa riêng tư (hiển thị sau khi nhấp "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 mã truy cập

Tạo Mã Truy Cập

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

Một 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 Mã

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

Sử Dụng Mã với Claude Desktop

Khi bạn đã có mã truy cập, 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"
  }
}

Thực Hành 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 mã để xử lý việc hết hạn mã
  3. Sử dụng mã cụ thể cho môi trường (sandbox để kiểm thử, production cho giao dịch thực)
  4. Tránh nhúng cứng mã trong mã ứng dụng

Tuyên Bố Từ Chối Trách Nhiệm

Nội dung do AI tạo ra 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 dựa vào đó. 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ó.