PayPal

PayPal Agent Toolkit

Le PayPal Agent Toolkit permet aux frameworks d'agents populaires, notamment l'Agent SDK d'OpenAI, LangChain, l'AI SDK de Vercel et le Model Context Protocol (MCP), de s'intégrer aux API PayPal via l'appel de fonctions. Il prend en charge TypeScript et est construit sur les API PayPal et les SDK PayPal.

Outils disponibles

Le PayPal Agent Toolkit fournit les outils suivants :

Factures

• create_invoice : Créer une nouvelle facture dans le système PayPal, y compris les coordonnées de facturation du destinataire, les lignes d'articles, une note de facture, un thème de couleur personnalisé, un coût d'expédition optionnel et une option pour activer PAY_BY_BANK comme méthode de paiement
• create_recurring_series : Créer une série de factures récurrentes qui génère et envoie automatiquement des factures selon un calendrier
• list_invoices : Lister les factures avec pagination et filtres optionnels
• get_invoice : Récupérer les détails d'une facture spécifique
• send_invoice : Envoyer une facture aux destinataires
• send_invoice_reminder : Envoyer un rappel pour une facture existante
• cancel_sent_invoice : Annuler une facture envoyée
• generate_invoice_qr_code : Générer un code QR pour une facture

Paiements

• create_order : Créer une commande dans le système PayPal en fonction des détails fournis
• get_order : Récupérer les détails d'une commande
• pay_order : Traiter le paiement d'une commande autorisée
• create_refund : Traiter un remboursement pour un paiement capturé
• get_refund : Obtenir les détails d'un remboursement spécifique

Gestion des litiges

• list_disputes : Récupérer un résumé de tous les litiges ouverts
• get_dispute : Récupérer des informations détaillées sur un litige spécifique
• accept_dispute_claim : Accepter une réclamation de litige

Suivi des expéditions

• create_shipment_tracking : Créer un enregistrement de suivi d'expédition
• get_shipment_tracking : Récupérer les informations de suivi d'expédition
• update_shipment_tracking : Mettre à jour les informations de suivi d'expédition

Gestion du catalogue

• create_product : Créer un nouveau produit dans le catalogue PayPal
• list_products : Lister les produits avec pagination et filtres optionnels
• show_product_details : Récupérer les détails d'un produit spécifique

Gestion des abonnements

• create_subscription_plan : Créer un nouveau plan d'abonnement
• list_subscription_plans : Lister les plans d'abonnement
• show_subscription_plan_details : Récupérer les détails d'un plan d'abonnement spécifique
• create_subscription : Créer un nouvel abonnement
• show_subscription_details : Récupérer les détails d'un abonnement spécifique
• update_subscription : Mettre à jour un abonnement existant
• cancel_subscription : Annuler un abonnement actif

Rapports et analyses

• list_transactions : Lister les transactions avec pagination et filtres optionnels
• get_merchant_insights : Récupérer les métriques d'intelligence économique et les analyses pour un marchand

TypeScript

Installation

Vous n'avez pas besoin de ce code source sauf si vous souhaitez modifier le package. Si vous voulez simplement utiliser le package, exécutez :

npm install @paypal/agent-toolkit

Prérequis

• Node 18+

Utilisation

La bibliothèque doit être configurée avec l'identifiant client et le secret de votre compte, disponibles dans votre tableau de bord développeur PayPal.

Le toolkit fonctionne avec l'AI SDK de Vercel et peut être passé comme une liste d'outils. Pour plus de détails, consultez nos exemples

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

Pour utiliser le mode sandbox, ajoutez le contexte dans votre configuration.

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

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

Utilisation

Utilisation du toolkit

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

Variables d'environnement

Les variables d'environnement suivantes peuvent être utilisées :

• PAYPAL_ACCESS_TOKEN : Votre jeton d'accès PayPal
• PAYPAL_ENVIRONMENT : Définissez sur SANDBOX pour le mode sandbox, PRODUCTION pour la production (par défaut, mode SANDBOX)

Ce guide explique comment générer un jeton d'accès pour l'intégration de l'API PayPal, y compris comment trouver votre identifiant client et votre secret client.

Prérequis

• Compte développeur PayPal (pour le sandbox)
• Compte professionnel PayPal (pour la production)

Trouver votre identifiant client et votre secret client

1. Créer un compte développeur PayPal :

   • Allez sur le tableau de bord développeur PayPal
   • Inscrivez-vous ou connectez-vous avec vos identifiants PayPal

2. Accéder à vos identifiants :

   • Dans le tableau de bord développeur, cliquez sur Applications et identifiants dans le menu
   • Basculez entre les modes Sandbox et Live selon vos besoins

3. Créer ou consulter une application :

   • Pour créer une nouvelle application, cliquez sur Créer une application
   • Donnez un nom à votre application et sélectionnez un compte professionnel à associer
   • Pour les applications existantes, cliquez sur le nom de l'application pour afficher les détails

4. Récupérer les identifiants :

   • Une fois votre application créée ou sélectionnée, vous verrez un écran avec :
     • Identifiant client : Un identifiant public pour votre application
     • Secret client : Une clé privée (affichée après avoir cliqué sur « Afficher »)
   • Enregistrez ces identifiants en toute sécurité car ils sont nécessaires pour générer des jetons d'accès

Génération d'un jeton d'accès

Utilisation de 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\"

Remplacez CLIENT_ID et CLIENT_SECRET par vos identifiants réels. Pour la production, utilisez https://api-m.paypal.com au lieu de l'URL sandbox.

Utilisation de Postman

1. Créez une nouvelle requête vers https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Définissez la méthode sur POST
3. Sous Autorisation, sélectionnez Authentification de base et saisissez votre identifiant client et votre secret client
4. Sous Corps, sélectionnez x-www-form-urlencoded et ajoutez une clé grant_type avec la valeur client_credentials
5. Envoyez la requête

Réponse

Une réponse réussie ressemblera à :

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

Copiez la valeur access_token pour l'utiliser dans votre intégration Claude Desktop.

Détails du jeton

• Jetons sandbox : Valides pendant 3 à 8 heures
• Jetons de production : Valides pendant 8 heures
• Il est recommandé d'implémenter une logique de renouvellement du jeton avant son expiration

Utilisation du jeton avec Claude Desktop

Une fois que vous avez votre jeton d'accès, mettez à jour la valeur PAYPAL_ACCESS_TOKEN dans votre configuration du connecteur Claude Desktop :

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

Bonnes pratiques

1. Stockez l'identifiant client et le secret client en toute sécurité
2. Implémentez une logique de renouvellement du jeton pour gérer l'expiration
3. Utilisez des jetons spécifiques à l'environnement (sandbox pour les tests, production pour les transactions réelles)
4. Évitez de coder en dur les jetons dans le code de l'application

Avertissement

Le contenu généré par l'IA peut être inexact ou incomplet. Les utilisateurs sont responsables de vérifier indépendamment toute information avant de s'y fier. PayPal ne garantit pas l'exactitude des résultats et n'est pas responsable des décisions, actions ou conséquences résultant de leur utilisation.