PayPal

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

PayPal Agent Toolkit

El PayPal Agent Toolkit permite que los frameworks de agentes más populares, incluidos el Agent SDK de OpenAI, LangChain, el AI SDK de Vercel y el Model Context Protocol (MCP), se integren con las APIs de PayPal mediante llamadas a funciones. Incluye soporte para TypeScript y está construido sobre las APIs de PayPal y los SDKs de PayPal.

Herramientas disponibles

El PayPal Agent toolkit proporciona las siguientes herramientas:

Facturas

• create_invoice: Crear una nueva factura en el sistema de PayPal, incluidos los detalles de facturación del destinatario, los artículos de línea, una nota de factura, un tema de color personalizado, un costo de envío opcional y una opción para habilitar PAY_BY_BANK como método de pago

• list_invoices: Listar facturas con paginación y filtrado opcionales

• get_invoice: Recuperar los detalles de una factura específica

• send_invoice: Enviar una factura a los destinatarios

• send_invoice_reminder: Enviar un recordatorio para una factura existente

• cancel_sent_invoice: Cancelar una factura enviada

• generate_invoice_qr_code: Generar un código QR para una factura

• delete_invoice: Eliminar permanentemente una factura borrador o programada

• generate_invoice_number: Generar el siguiente número de factura disponible para el comerciante

• search_invoicing: Buscar facturas o series de facturas recurrentes

• update_invoicing: Actualizar una factura existente o una serie de facturas recurrentes (reemplazo completo)

• cancel_invoice_auto_reminder: Cancelar todos los recordatorios automáticos programados para una factura

• record_payment_for_invoice: Registrar un pago externo o manual contra una factura

• record_refund_for_invoice: Registrar un reembolso contra una factura

• create_conditional_rules_for_invoice: Crear reglas condicionales para una factura, como un descuento por pago anticipado o una fecha de cancelación automática

• create_recurring_series: Crear una serie de facturas recurrentes que genera y envía facturas automáticamente según un cronograma

• activate_recurring_series: Activar una serie de facturas recurrentes borrador

• get_recurring_series: Recuperar los detalles de una serie de facturas recurrentes específica

• cancel_recurring_series: Cancelar una serie de facturas recurrentes activa

• delete_recurring_series: Eliminar una serie de facturas recurrentes borrador

Pagos

• create_order: Crear una orden en el sistema de PayPal según los detalles proporcionados
• get_order: Recuperar los detalles de una orden
• pay_order: Procesar el pago de una orden autorizada
• create_refund: Procesar un reembolso para un pago capturado
• get_refund: Obtener los detalles de un reembolso específico

Gestión de disputas

• list_disputes: Recuperar un resumen de todas las disputas abiertas
• get_dispute: Recuperar información detallada de una disputa específica
• accept_dispute_claim: Aceptar una reclamación de disputa

Seguimiento de envíos

• create_shipment_tracking: Crear un registro de seguimiento de envío
• get_shipment_tracking: Recuperar información de seguimiento de envío
• update_shipment_tracking: Actualizar información de seguimiento de envío

Gestión de catálogo

• create_product: Crear un nuevo producto en el catálogo de PayPal
• list_products: Listar productos con paginación y filtrado opcionales
• show_product_details: Recuperar los detalles de un producto específico

Gestión de suscripciones

• create_subscription_plan: Crear un nuevo plan de suscripción
• list_subscription_plans: Listar planes de suscripción
• show_subscription_plan_details: Recuperar los detalles de un plan de suscripción específico
• create_subscription: Crear una nueva suscripción
• show_subscription_details: Recuperar los detalles de una suscripción específica
• update_subscription: Actualizar una suscripción existente
• cancel_subscription: Cancelar una suscripción activa

Informes y perspectivas

• list_transactions: Listar transacciones con paginación y filtrado opcionales
• get_merchant_insights: Recuperar métricas de inteligencia empresarial y análisis para un comerciante

TypeScript

Instalación

No necesitas este código fuente a menos que quieras modificar el paquete. Si solo quieres usar el paquete, ejecuta:

npm install @paypal/agent-toolkit

Requisitos

• Node 18+

Uso

La biblioteca debe configurarse con el ID de cliente y el secreto de tu cuenta, disponibles en tu PayPal Developer Dashboard.

El toolkit funciona con el AI SDK de Vercel y se puede pasar como una lista de herramientas. Para más detalles, consulta nuestros ejemplos

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

Para usar el modo sandbox, agrega contexto dentro de tu configuración.

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

Inicialización de los flujos de trabajo

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

Uso

Uso del 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 de entorno

Se pueden utilizar las siguientes variables de entorno:

• PAYPAL_ACCESS_TOKEN: Tu token de acceso de PayPal
• PAYPAL_ENVIRONMENT: Configúralo en SANDBOX para el modo sandbox, PRODUCTION para producción (el valor predeterminado es el modo SANDBOX)

Esta guía explica cómo generar un token de acceso para la integración con la API de PayPal, incluido cómo encontrar tu ID de cliente y tu secreto de cliente.

Requisitos previos

• Cuenta de desarrollador de PayPal (para Sandbox)
• Cuenta comercial de PayPal (para producción)

Cómo encontrar tu ID de cliente y tu secreto de cliente

1. Crea una cuenta de desarrollador de PayPal:

   • Ve al PayPal Developer Dashboard
   • Regístrate o inicia sesión con tus credenciales de PayPal

2. Accede a tus credenciales:

   • En el Developer Dashboard, haz clic en Apps & Credentials en el menú
   • Cambia entre los modos Sandbox y Live según tus necesidades

3. Crea o visualiza una aplicación:

   • Para crear una nueva aplicación, haz clic en Create App
   • Asigna un nombre a tu aplicación y selecciona una cuenta comercial para asociarla
   • Para aplicaciones existentes, haz clic en el nombre de la aplicación para ver los detalles

4. Recupera las credenciales:

   • Una vez que tu aplicación esté creada o seleccionada, verás una pantalla con tu:
     • Client ID: Un identificador público para tu aplicación
     • Client Secret: Una clave privada (se muestra después de hacer clic en "Show")
   • Guarda estas credenciales de forma segura, ya que son necesarias para generar tokens de acceso

Generación de un token de acceso

Usando 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\"

Reemplaza CLIENT_ID y CLIENT_SECRET con tus credenciales reales. Para producción, usa https://api-m.paypal.com en lugar de la URL de sandbox.

Usando Postman

1. Crea una nueva solicitud a https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Configura el método como POST
3. En Authorization, selecciona Basic Auth e ingresa tu Client ID y Client Secret
4. En Body, selecciona x-www-form-urlencoded y agrega una clave grant_type con el valor client_credentials
5. Envía la solicitud

Respuesta

Una respuesta exitosa tendrá este aspecto:

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

Copia el valor de access_token para usarlo en tu integración con Claude Desktop.

Detalles del token

• Tokens de Sandbox: Válidos por 3-8 horas
• Tokens de producción: Válidos por 8 horas
• Se recomienda implementar lógica de renovación de tokens antes de la expiración

Uso del token con Claude Desktop

Una vez que tengas tu token de acceso, actualiza el valor de PAYPAL_ACCESS_TOKEN en la configuración de tu conector de Claude Desktop:

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

Mejores prácticas

1. Almacena el ID de cliente y el secreto de cliente de forma segura
2. Implementa lógica de renovación de tokens para manejar la expiración
3. Usa tokens específicos del entorno (sandbox para pruebas, producción para transacciones reales)
4. Evita codificar tokens en el código de la aplicación

Aviso legal

El contenido generado por IA puede ser inexacto o incompleto. Los usuarios son responsables de verificar de forma independiente cualquier información antes de confiar en ella. PayPal no garantiza la precisión de los resultados y no es responsable de ninguna decisión, acción o consecuencia derivada de su uso.