PayPal

PayPal Agent Toolkit

PayPal Agent Toolkit は、OpenAI の Agent SDK、LangChain、Vercel の AI SDK、Model Context Protocol (MCP) などの一般的なエージェントフレームワークが、関数呼び出しを通じて PayPal API と統合できるようにします。TypeScript をサポートしており、PayPal API と PayPal SDK の上に構築されています。

利用可能なツール

PayPal Agent Toolkit は以下のツールを提供します：

請求書

• create_invoice: 受取人の請求先詳細、明細項目、請求書メモ、カスタムカラーテーマ、任意の送料、および PAY_BY_BANK を支払い方法として有効にするオプションを含む、PayPal システムに新しい請求書を作成します
• 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 Developer Dashboard で入手できるアカウントのクライアント ID とシークレットで設定する必要があります。

このツールキットは Vercel の AI SDK と連携し、ツールのリストとして渡すことができます。詳細については、examples を参照してください。

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 モード）

このガイドでは、PayPal API 統合用のアクセストークンを生成する方法と、クライアント ID とクライアントシークレットの見つけ方について説明します。

前提条件

• PayPal Developer アカウント（サンドボックス用）
• PayPal Business アカウント（本番環境用）

クライアント ID とクライアントシークレットの確認

1. PayPal Developer アカウントを作成：

   • PayPal Developer Dashboard にアクセスします
   • PayPal の認証情報でサインアップまたはログインします

2. 認証情報にアクセス：

   • Developer Dashboard で、メニューの Apps & Credentials をクリックします
   • 必要に応じて Sandbox モードと Live モードを切り替えます

3. アプリを作成または表示：

   • 新しいアプリを作成するには、Create App をクリックします
   • アプリに名前を付け、関連付ける Business アカウントを選択します
   • 既存のアプリの場合は、アプリ名をクリックして詳細を表示します

4. 認証情報を取得：

   • アプリが作成または選択されると、以下の情報が表示された画面が表示されます：
     • Client ID: アプリの公開識別子
     • Client Secret: 秘密鍵（「Show」をクリックすると表示されます）
   • アクセストークンの生成に必要となるため、これらの認証情報を安全に保存してください

アクセストークンの生成

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 を実際の認証情報に置き換えてください。本番環境では、サンドボックス URL の代わりに https://api-m.paypal.com を使用してください。

Postman を使用する場合

1. https://api-m.sandbox.paypal.com/v1/oauth2/token への新しいリクエストを作成します
2. メソッドを POST に設定します
3. Authorization で Basic Auth を選択し、Client ID と Client Secret を入力します
4. Body で x-www-form-urlencoded を選択し、値 client_credentials を持つキー grant_type を追加します
5. リクエストを送信します

レスポンス

成功したレスポンスは次のようになります：

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

Claude Desktop 統合で使用するために access_token の値をコピーします。

トークンの詳細

• サンドボックストークン: 3〜8 時間有効
• 本番環境トークン: 8 時間有効
• 有効期限前にトークン更新ロジックを実装することをお勧めします

Claude Desktop でのトークンの使用

アクセストークンを取得したら、Claude Desktop コネクタ設定の PAYPAL_ACCESS_TOKEN 値を更新します：

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

ベストプラクティス

1. クライアント ID とクライアントシークレットを安全に保管する
2. トークンの有効期限に対応するためのトークン更新ロジックを実装する
3. 環境固有のトークンを使用する（テスト用はサンドボックス、実際の取引は本番環境）
4. アプリケーションコードにトークンをハードコードしない

免責事項

AI が生成したコンテンツは不正確または不完全な場合があります。ユーザーは、情報に依存する前に独立して検証する責任があります。PayPal は出力の正確性について保証せず、その使用によって生じたいかなる決定、行動、結果についても責任を負いません。