PayPal MCP Server

PayPal Agent Toolkit

O PayPal Agent Toolkit permite que frameworks de agentes populares, incluindo o Agent SDK da OpenAI, LangChain, AI SDK da Vercel e Model Context Protocol (MCP), integrem-se às APIs do PayPal por meio de chamadas de função. Ele inclui suporte para TypeScript e é construído sobre as APIs do PayPal e os SDKs do PayPal.

Ferramentas disponíveis

O PayPal Agent Toolkit fornece as seguintes ferramentas:

Faturas

• create_invoice: Criar uma nova fatura no sistema PayPal
• list_invoices: Listar faturas com paginação e filtragem opcionais
• get_invoice: Recuperar detalhes de uma fatura específica
• send_invoice: Enviar uma fatura para os destinatários
• send_invoice_reminder: Enviar um lembrete para uma fatura existente
• cancel_sent_invoice: Cancelar uma fatura enviada
• generate_invoice_qr_code: Gerar um código QR para uma fatura

Pagamentos

• create_order: Criar um pedido no sistema PayPal com base nos detalhes fornecidos
• get_order: Recuperar os detalhes de um pedido
• pay_order: Processar o pagamento de um pedido autorizado
• create_refund: Processar um reembolso para um pagamento capturado.
• get_refund: Obter os detalhes de um reembolso específico.

Gerenciamento de Disputas

• list_disputes: Recuperar um resumo de todas as disputas abertas
• get_dispute: Recuperar informações detalhadas de uma disputa específica
• accept_dispute_claim: Aceitar uma reivindicação de disputa

Rastreamento de Envios

• create_shipment_tracking: Criar um registro de rastreamento de envio
• get_shipment_tracking: Recuperar informações de rastreamento de envio
• update_shipment_tracking: Atualizar informações de rastreamento de envio

Gerenciamento de Catálogo

• create_product: Criar um novo produto no catálogo do PayPal
• list_products: Listar produtos com paginação e filtragem opcionais
• show_product_details: Recuperar detalhes de um produto específico

Gerenciamento de Assinaturas

• create_subscription_plan: Criar um novo plano de assinatura
• list_subscription_plans: Listar planos de assinatura
• show_subscription_plan_details: Recuperar detalhes de um plano de assinatura específico
• create_subscription: Criar uma nova assinatura
• show_subscription_details: Recuperar detalhes de uma assinatura específica
• update_subscription: Atualizar uma assinatura existente
• cancel_subscription: Cancelar uma assinatura ativa

Relatórios e Insights

• list_transactions: Listar transações com paginação e filtragem opcionais
• get_merchant_insights: Recuperar métricas de inteligência de negócios e análises para um comerciante

TypeScript

Instalação

Você não precisa deste código-fonte, a menos que queira modificar o pacote. Se você apenas quiser usar o pacote, execute:

npm install @paypal/agent-toolkit

Requisitos

• Node 18+

Uso

A biblioteca precisa ser configurada com o ID do cliente e o segredo da sua conta, disponíveis no seu Painel do Desenvolvedor PayPal.

O toolkit funciona com o AI SDK da Vercel e pode ser passado como uma lista de ferramentas. Para mais detalhes, consulte nossos exemplos.

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

Para usar o modo sandbox, adicione contexto na sua configuração.

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

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

Uso

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

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas:

• PAYPAL_ACCESS_TOKEN: Seu Token de Acesso do PayPal
• PAYPAL_ENVIRONMENT: Defina como SANDBOX para o modo sandbox, PRODUCTION para produção (padrão é o modo SANDBOX)

Este guia explica como gerar um token de acesso para integração com a API do PayPal, incluindo como encontrar seu ID do cliente e segredo do cliente.

Pré-requisitos

• Conta de Desenvolvedor PayPal (para Sandbox)
• Conta Business PayPal (para produção)

Encontrando Seu ID do Cliente e Segredo do Cliente

1. Crie uma Conta de Desenvolvedor PayPal:

   • Acesse o Painel do Desenvolvedor PayPal
   • Cadastre-se ou faça login com suas credenciais do PayPal

2. Acesse Suas Credenciais:

   • No Painel do Desenvolvedor, clique em Apps e Credenciais no menu
   • Alterne entre os modos Sandbox e Produção conforme suas necessidades

3. Crie ou Visualize um App:

   • Para criar um novo app, clique em Criar App
   • Dê um nome ao seu app e selecione uma conta Business para associá-lo
   • Para apps existentes, clique no nome do app para ver os detalhes

4. Recupere as Credenciais:

   • Após criar ou selecionar seu app, você verá uma tela com:
     • ID do Cliente: Um identificador público para seu app
     • Segredo do Cliente: Uma chave privada (exibida após clicar em "Mostrar")
   • Salve essas credenciais com segurança, pois são necessárias para gerar tokens de acesso

Gerando um Token de Acesso

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

Substitua CLIENT_ID e CLIENT_SECRET pelas suas credenciais reais. Para produção, use https://api-m.paypal.com em vez da URL do sandbox.

Usando Postman

1. Crie uma nova requisição para https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Defina o método como POST
3. Em Autorização, selecione Autenticação Básica e insira seu ID do Cliente e Segredo do Cliente
4. Em Corpo, selecione x-www-form-urlencoded e adicione uma chave grant_type com o valor client_credentials
5. Envie a requisição

Resposta

Uma resposta bem-sucedida terá a seguinte aparência:

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

Copie o valor de access_token para usar na integração com o Claude Desktop.

Detalhes do Token

• Tokens Sandbox: Válidos por 3 a 8 horas
• Tokens de Produção: Válidos por 8 horas
• Recomenda-se implementar lógica de renovação de token antes da expiração

Usando o Token com o Claude Desktop

Depois de obter seu token de acesso, atualize o valor de PAYPAL_ACCESS_TOKEN na configuração do conector do Claude Desktop:

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

Melhores Práticas

1. Armazene o ID do cliente e o segredo do cliente com segurança
2. Implemente lógica de renovação de token para lidar com a expiração
3. Use tokens específicos do ambiente (sandbox para testes, produção para transações reais)
4. Evite codificar tokens diretamente no código da aplicação

Aviso Legal

Conteúdo gerado por IA pode ser impreciso ou incompleto. Os usuários são responsáveis por verificar independentemente qualquer informação antes de confiar nela. O PayPal não oferece garantias quanto à precisão dos resultados e não se responsabiliza por quaisquer decisões, ações ou consequências resultantes de seu uso.