PayPal

PayPal Agent Toolkit

Das PayPal Agent Toolkit ermöglicht beliebten Agent-Frameworks, einschließlich OpenAI's Agent SDK, LangChain, Vercel's AI SDK und Model Context Protocol (MCP), die Integration mit PayPal-APIs durch Funktionsaufrufe. Es unterstützt TypeScript und basiert auf den PayPal-APIs und den PayPal-SDKs.

Verfügbare Tools

Das PayPal Agent Toolkit stellt die folgenden Tools bereit:

Rechnungen

• create_invoice: Erstellen Sie eine neue Rechnung im PayPal-System, einschließlich Rechnungsdetails des Empfängers, Positionen, einer Rechnungsnotiz, einem benutzerdefinierten Farbschema, optionalen Versandkosten und einer Option, PAY_BY_BANK als Zahlungsmethode zu aktivieren.
• create_recurring_series: Erstellen Sie eine wiederkehrende Rechnungsserie, die automatisch Rechnungen nach einem Zeitplan erstellt und sendet.
• list_invoices: Rechnungen mit optionaler Paginierung und Filterung auflisten.
• get_invoice: Details einer bestimmten Rechnung abrufen.
• send_invoice: Eine Rechnung an Empfänger senden.
• send_invoice_reminder: Eine Erinnerung für eine bestehende Rechnung senden.
• cancel_sent_invoice: Eine gesendete Rechnung stornieren.
• generate_invoice_qr_code: Einen QR-Code für eine Rechnung generieren.

Zahlungen

• create_order: Eine Bestellung im PayPal-System basierend auf den angegebenen Details erstellen.
• get_order: Die Details einer Bestellung abrufen.
• pay_order: Zahlung für eine autorisierte Bestellung verarbeiten.
• create_refund: Eine Rückerstattung für eine erfasste Zahlung verarbeiten.
• get_refund: Die Details für eine bestimmte Rückerstattung abrufen.

Streitfallverwaltung

• list_disputes: Eine Zusammenfassung aller offenen Streitfälle abrufen.
• get_dispute: Detaillierte Informationen zu einem bestimmten Streitfall abrufen.
• accept_dispute_claim: Einen Streitfallanspruch akzeptieren.

Sendungsverfolgung

• create_shipment_tracking: Einen Sendungsverfolgungsdatensatz erstellen.
• get_shipment_tracking: Sendungsverfolgungsinformationen abrufen.
• update_shipment_tracking: Sendungsverfolgungsinformationen aktualisieren.

Katalogverwaltung

• create_product: Ein neues Produkt im PayPal-Katalog erstellen.
• list_products: Produkte mit optionaler Paginierung und Filterung auflisten.
• show_product_details: Details eines bestimmten Produkts abrufen.

Abonnementverwaltung

• create_subscription_plan: Einen neuen Abonnementplan erstellen.
• list_subscription_plans: Abonnementpläne auflisten.
• show_subscription_plan_details: Details eines bestimmten Abonnementplans abrufen.
• create_subscription: Ein neues Abonnement erstellen.
• show_subscription_details: Details eines bestimmten Abonnements abrufen.
• update_subscription: Ein bestehendes Abonnement aktualisieren.
• cancel_subscription: Ein aktives Abonnement kündigen.

Berichterstattung und Einblicke

• list_transactions: Transaktionen mit optionaler Paginierung und Filterung auflisten.
• get_merchant_insights: Business-Intelligence-Metriken und Analysen für einen Händler abrufen.

TypeScript

Installation

Sie benötigen diesen Quellcode nicht, es sei denn, Sie möchten das Paket ändern. Wenn Sie das Paket nur verwenden möchten, führen Sie aus:

npm install @paypal/agent-toolkit

Voraussetzungen

• Node 18+

Verwendung

Die Bibliothek muss mit der Client-ID und dem Client-Secret Ihres Kontos konfiguriert werden, die in Ihrem PayPal Developer Dashboard verfügbar sind.

Das Toolkit funktioniert mit Vercel's AI SDK und kann als Liste von Tools übergeben werden. Weitere Details finden Sie in unseren Beispielen.

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

Um den Sandbox-Modus zu verwenden, fügen Sie Kontext in Ihrer Konfiguration hinzu.

configuration: {
  context: {
    sandbox: true,
  }
}

Initialisieren der Workflows

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

Verwendung

Verwenden des Toolkits

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

Umgebungsvariablen

Die folgenden Umgebungsvariablen können verwendet werden:

• PAYPAL_ACCESS_TOKEN: Ihr PayPal-Zugriffstoken
• PAYPAL_ENVIRONMENT: Setzen Sie auf SANDBOX für den Sandbox-Modus, PRODUCTION für die Produktion (Standard ist der SANDBOX-Modus).

Dieser Leitfaden erklärt, wie Sie ein Zugriffstoken für die PayPal-API-Integration generieren, einschließlich der Suche nach Ihrer Client-ID und Ihrem Client-Secret.

Voraussetzungen

• PayPal-Entwicklerkonto (für Sandbox)
• PayPal-Geschäftskonto (für die Produktion)

Finden Ihrer Client-ID und Ihres Client-Secrets

1. Erstellen Sie ein PayPal-Entwicklerkonto:

   • Gehen Sie zum PayPal Developer Dashboard
   • Melden Sie sich mit Ihren PayPal-Anmeldedaten an oder registrieren Sie sich

2. Greifen Sie auf Ihre Anmeldedaten zu:

   • Klicken Sie im Developer Dashboard im Menü auf Apps & Credentials
   • Wechseln Sie je nach Bedarf zwischen Sandbox- und Live-Modus

3. Erstellen oder Anzeigen einer App:

   • Um eine neue App zu erstellen, klicken Sie auf Create App
   • Geben Sie Ihrer App einen Namen und wählen Sie ein Geschäftskonto aus, das Sie damit verknüpfen möchten
   • Für bestehende Apps klicken Sie auf den App-Namen, um Details anzuzeigen

4. Anmeldedaten abrufen:

   • Sobald Ihre App erstellt oder ausgewählt ist, sehen Sie einen Bildschirm mit Ihren:
     • Client-ID: Ein öffentlicher Bezeichner für Ihre App
     • Client-Secret: Ein privater Schlüssel (wird nach Klicken auf "Show" angezeigt)
   • Speichern Sie diese Anmeldedaten sicher, da sie zum Generieren von Zugriffstokens erforderlich sind

Generieren eines Zugriffstokens

Verwenden von 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\"

Ersetzen Sie CLIENT_ID und CLIENT_SECRET durch Ihre tatsächlichen Anmeldedaten. Verwenden Sie für die Produktion https://api-m.paypal.com anstelle der Sandbox-URL.

Verwenden von Postman

1. Erstellen Sie eine neue Anfrage an https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Setzen Sie die Methode auf POST
3. Wählen Sie unter Authorization die Option Basic Auth und geben Sie Ihre Client-ID und Ihr Client-Secret ein
4. Wählen Sie unter Body die Option x-www-form-urlencoded und fügen Sie einen Schlüssel grant_type mit dem Wert client_credentials hinzu
5. Senden Sie die Anfrage

Antwort

Eine erfolgreiche Antwort sieht wie folgt aus:

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

Kopieren Sie den Wert von access_token für die Verwendung in Ihrer Claude-Desktop-Integration.

Token-Details

• Sandbox-Tokens: Gültig für 3-8 Stunden
• Produktionstokens: Gültig für 8 Stunden
• Es wird empfohlen, eine Token-Aktualisierungslogik vor Ablauf zu implementieren

Verwenden des Tokens mit Claude Desktop

Sobald Sie Ihr Zugriffstoken haben, aktualisieren Sie den Wert von PAYPAL_ACCESS_TOKEN in Ihrer Claude-Desktop-Connector-Konfiguration:

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

Bewährte Methoden

1. Speichern Sie Client-ID und Client-Secret sicher
2. Implementieren Sie eine Token-Aktualisierungslogik, um den Token-Ablauf zu behandeln
3. Verwenden Sie umgebungsspezifische Tokens (Sandbox für Tests, Produktion für echte Transaktionen)
4. Vermeiden Sie das Hartcodieren von Tokens im Anwendungscode

Haftungsausschluss

KI-generierte Inhalte können ungenau oder unvollständig sein. Benutzer sind dafür verantwortlich, Informationen vor der Verwendung unabhängig zu überprüfen. PayPal übernimmt keine Garantie für die Genauigkeit der Ausgabe und haftet nicht für Entscheidungen, Handlungen oder Konsequenzen, die sich aus deren Verwendung ergeben.