Paypal

PayPal エージェントツールキット

PayPal エージェントツールキットを使用すると、OpenAI の Agent SDK、LangChain、Vercel の AI SDK、Model Context Protocol（MCP）などの一般的なエージェントフレームワークを、関数呼び出しを通じて PayPal API と連携できます。TypeScript に対応しており、PayPal API と PayPal SDK を基盤として構築されています。

利用可能なツール

PayPal エージェントツールキットでは、次のツールを利用できます。

請求書

• create_invoice：受取人の請求先情報、明細項目、請求書のメモ、カスタムカラーテーマ、任意の送料、支払い方法として PAY_BY_BANK を有効にするオプションを含む、新しい請求書を PayPal システムで作成します

• 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 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,
        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 モードです）

このガイドでは、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 を選択し、クライアント ID とクライアントシークレットを入力します
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": "..."
}

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 は、出力の正確性を保証せず、その利用に起因する判断、行動、または結果について責任を負いません。