PayPal

PayPal Agent Toolkit

Набор инструментов PayPal Agent позволяет популярным агентским фреймворкам, включая Agent SDK от OpenAI, LangChain, AI SDK от Vercel и Model Context Protocol (MCP), интегрироваться с API PayPal через вызов функций. Он поддерживает TypeScript и построен на основе API PayPal и SDK PayPal.

Доступные инструменты

Набор инструментов PayPal Agent предоставляет следующие инструменты:

Счета

• create_invoice: Создать новый счет в системе PayPal, включая платежные реквизиты получателя, позиции, примечание к счету, пользовательскую цветовую тему, необязательную стоимость доставки и возможность включить PAY_BY_BANK как способ оплаты
• create_recurring_series: Создать серию повторяющихся счетов, которая автоматически генерирует и отправляет счета по расписанию
• list_invoices: Список счетов с необязательной пагинацией и фильтрацией
• get_invoice: Получить детали конкретного счета
• send_invoice: Отправить счет получателям
• send_invoice_reminder: Отправить напоминание о существующем счете
• cancel_sent_invoice: Отменить отправленный счет
• generate_invoice_qr_code: Сгенерировать QR-код для счета

Платежи

• 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+

Использование

Библиотека должна быть настроена с использованием идентификатора клиента и секрета вашей учетной записи, которые доступны в вашей Панели разработчика PayPal.

Набор инструментов работает с AI SDK от Vercel и может быть передан как список инструментов. Для получения дополнительных сведений обратитесь к нашим примерам

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

Чтобы использовать песочницу, добавьте контекст в вашу конфигурацию.

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)

Это руководство объясняет, как сгенерировать токен доступа для интеграции с API PayPal, включая то, как найти ваш идентификатор клиента и секрет клиента.

Предварительные требования

• Учетная запись разработчика PayPal (для песочницы)
• Бизнес-аккаунт PayPal (для продакшена)

Поиск вашего идентификатора клиента и секрета клиента

1. Создайте учетную запись разработчика PayPal:

   • Перейдите в Панель разработчика PayPal
   • Зарегистрируйтесь или войдите, используя свои учетные данные PayPal

2. Получите доступ к своим учетным данным:

   • В панели разработчика нажмите Приложения и учетные данные в меню
   • Переключайтесь между режимами Песочница и Live в зависимости от ваших потребностей

3. Создайте или просмотрите приложение:

   • Чтобы создать новое приложение, нажмите Создать приложение
   • Дайте вашему приложению имя и выберите бизнес-аккаунт для связи с ним
   • Для существующих приложений нажмите на имя приложения, чтобы просмотреть детали

4. Получите учетные данные:

   • После создания или выбора приложения вы увидите экран с вашими:
     • Идентификатор клиента: Публичный идентификатор вашего приложения
     • Секрет клиента: Приватный ключ (отображается после нажатия «Показать»)
   • Сохраните эти учетные данные в безопасном месте, так как они требуются для генерации токенов доступа

Генерация токена доступа

Использование 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 и введите ваш идентификатор клиента и секрет клиента
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

После получения токена доступа обновите значение PAYPAL_ACCESS_TOKEN в конфигурации вашего коннектора Claude Desktop:

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

Лучшие практики

1. Храните идентификатор клиента и секрет клиента в безопасном месте
2. Реализуйте логику обновления токена для обработки истечения срока действия
3. Используйте токены, специфичные для окружения (песочница для тестирования, продакшен для реальных транзакций)
4. Избегайте жесткого кодирования токенов в коде приложения

Отказ от ответственности

Контент, сгенерированный ИИ, может быть неточным или неполным. Пользователи несут ответственность за самостоятельную проверку любой информации перед ее использованием. PayPal не дает гарантий относительно точности выходных данных и не несет ответственности за любые решения, действия или последствия, возникшие в результате их использования.