PayPal

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

Набор инструментов PayPal Agent

Набор инструментов 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 в качестве способа оплаты

• list_invoices: Список счетов с необязательной пагинацией и фильтрацией

• get_invoice: Получить детали конкретного счета

• send_invoice: Отправить счет получателям

• send_invoice_reminder: Отправить напоминание о существующем счете

• cancel_sent_invoice: Отменить отправленный счет

• generate_invoice_qr_code: Сгенерировать QR-код для счета

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

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

Библиотека должна быть настроена с использованием идентификатора клиента и секрета вашей учетной записи, которые доступны в вашей Панели разработчика 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,
        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)

Это руководство объясняет, как сгенерировать токен доступа для интеграции с 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 не дает гарантий относительно точности выходных данных и не несет ответственности за любые решения, действия или последствия, возникающие в результате их использования.