PayPal

PayPal Agent Toolkit

Bộ công cụ PayPal Agent cho phép các framework tác tử 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 PayPal APIs thông qua function calling. Nó bao gồm hỗ trợ cho TypeScript và được xây dựng trên nền tảng PayPal APIs 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 người nhận, các dòng mục, ghi chú hóa đơn, chủ đề màu tùy chỉnh, 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
• 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
• 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 một hóa đơn hiện có
• cancel_sent_invoice: Hủy một hóa đơn đã gửi
• generate_invoice_qr_code: Tạo mã QR cho một hóa đơn

Thanh toán

• create_order: Tạo một đơn hàng trong hệ thống PayPal dựa trên thông tin đượ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 một đơn hàng đã được ủy quyền
• create_refund: Xử lý hoàn tiền cho một 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ý khiếu nại

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

Theo dõi vận chuyển

• create_shipment_tracking: Tạo một bản ghi theo dõi vận chuyển
• get_shipment_tracking: Truy xuất 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 một 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 một 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 một đă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 một đăng ký hiện có
• cancel_subscription: Hủy một đă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 các chỉ số thông minh kinh doanh và phân tích cho một thương nhâ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+

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 các 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,
        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 các quy trình làm việc

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

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 sản xuất (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 PayPal API, 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 sản xuất)

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

1. Tạo tài khoản nhà phát triển PayPal:

   • Truy cập Bảng điều khiển nhà phát triển PayPal
   • Đăng ký hoặc đăng nhập bằng thông tin xác thực PayPal của bạn

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 một ứ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 ứ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 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 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 sản xuất, hãy sử dụng https://api-m.paypal.com thay vì URL sandbox.

Sử dụng Postman

1. Tạo một 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 phần Authorization, chọn Basic Auth và nhập Client ID và Client Secret của bạn
4. Trong phần 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ã truy cập

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

Sử dụng mã truy cập 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 trì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 mã truy cập để xử lý hết hạn mã truy cập
3. Sử dụng mã truy cập cụ thể cho từng môi trường (sandbox để kiểm tra, sản xuất cho giao dịch thực)
4. Tránh mã hóa cứng mã truy cập 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 tự xác minh mọi thông tin trước khi dựa vào nó. PayPal không đảm bảo về độ chính xác của đầu ra và không chịu trách nhiệm về 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ó.