PayPal

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

Kit d'outils PayPal pour agents

Le kit d'outils PayPal pour agents 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 grâce à l'appel de fonctions. Il prend en charge TypeScript et est construit sur les API PayPal et les SDK PayPal.

Outils disponibles

Le kit d'outils PayPal pour agents fournit les outils suivants :

Factures

• create_invoice : Créer une nouvelle facture dans le système PayPal, y compris les détails de facturation du destinataire, les lignes d'article, une note de facture, un thème de couleur personnalisé, un coût d'expédition facultatif et une option pour activer PAY_BY_BANK comme mode de paiement

• list_invoices : Lister les factures avec pagination et filtrage facultatifs

• 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

• delete_invoice : Supprimer définitivement une facture provisoire ou planifiée

• generate_invoice_number : Générer le prochain numéro de facture disponible pour le marchand

• search_invoicing : Rechercher des factures ou des séries de factures récurrentes

• update_invoicing : Mettre à jour une facture existante ou une série de factures récurrentes (remplacement complet)

• cancel_invoice_auto_reminder : Annuler tous les rappels automatiques planifiés pour une facture

• record_payment_for_invoice : Enregistrer un paiement externe ou manuel sur une facture

• record_refund_for_invoice : Enregistrer un remboursement sur une facture

• create_conditional_rules_for_invoice : Créer des règles conditionnelles pour une facture, telles qu'une remise pour paiement anticipé ou une date d'annulation automatique

• create_recurring_series : Créer une série de factures récurrentes qui génère et envoie automatiquement des factures selon un calendrier

• activate_recurring_series : Activer une série de factures récurrentes provisoire

• get_recurring_series : Récupérer les détails d'une série de factures récurrentes spécifique

• cancel_recurring_series : Annuler une série de factures récurrentes active

• delete_recurring_series : Supprimer une série de factures récurrentes provisoire

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 filtrage facultatifs
• 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

Reporting et analyses

• list_transactions : Lister les transactions avec pagination et filtrage facultatifs
• get_merchant_insights : Récupérer les métriques de veille é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 souhaitez 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 kit d'outils fonctionne avec l'AI SDK de Vercel et peut être transmis 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,
        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 },
    },
  },
});

Pour utiliser le mode bac à sable, 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 kit d'outils

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éfinir sur SANDBOX pour le mode bac à sable, 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 bac à sable)
• 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 Bac à sable et Production 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 vos :
     • 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

Avec 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 du bac à sable.

Avec 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 du bac à sable : 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 l'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 la configuration de votre 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 (bac à sable 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.