PayPal

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

PayPal Agent Toolkit

O PayPal Agent Toolkit permite que frameworks populares de agentes, 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: Crie uma nova fatura no sistema PayPal, incluindo detalhes de cobrança do destinatário, itens de linha, uma nota na fatura, um tema de cor personalizado, um custo de envio opcional e uma opção para habilitar PAY_BY_BANK como método de pagamento

• list_invoices: Liste faturas com paginação e filtragem opcionais

• get_invoice: Recupere detalhes de uma fatura específica

• send_invoice: Envie uma fatura aos destinatários

• send_invoice_reminder: Envie um lembrete para uma fatura existente

• cancel_sent_invoice: Cancele uma fatura enviada

• generate_invoice_qr_code: Gere um código QR para uma fatura

• delete_invoice: Exclua permanentemente uma fatura em rascunho ou agendada

• generate_invoice_number: Gere o próximo número de fatura disponível para o comerciante

• search_invoicing: Pesquise faturas ou séries de faturas recorrentes

• update_invoicing: Atualize uma fatura existente ou série de faturas recorrentes (substituição completa)

• cancel_invoice_auto_reminder: Cancele todos os lembretes automáticos agendados para uma fatura

• record_payment_for_invoice: Registre um pagamento externo ou manual contra uma fatura

• record_refund_for_invoice: Registre um reembolso contra uma fatura

• create_conditional_rules_for_invoice: Crie regras condicionais para uma fatura, como desconto por pagamento antecipado ou data de cancelamento automático

• create_recurring_series: Crie uma série de faturas recorrentes que gera e envia faturas automaticamente em um cronograma

• activate_recurring_series: Ative uma série de faturas recorrentes em rascunho

• get_recurring_series: Recupere detalhes de uma série específica de faturas recorrentes

• cancel_recurring_series: Cancele uma série de faturas recorrentes ativa

• delete_recurring_series: Exclua uma série de faturas recorrentes em rascunho

Pagamentos

• create_order: Crie um pedido no sistema PayPal com base nos detalhes fornecidos
• get_order: Recupere os detalhes de um pedido
• pay_order: Processe o pagamento de um pedido autorizado
• create_refund: Processe um reembolso para um pagamento capturado
• get_refund: Obtenha os detalhes de um reembolso específico

Gerenciamento de Disputas

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

Rastreamento de Envios

• create_shipment_tracking: Crie um registro de rastreamento de envio
• get_shipment_tracking: Recupere informações de rastreamento de envio
• update_shipment_tracking: Atualize informações de rastreamento de envio

Gerenciamento de Catálogo

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

Gerenciamento de Assinaturas

• create_subscription_plan: Crie um novo plano de assinatura
• list_subscription_plans: Liste planos de assinatura
• show_subscription_plan_details: Recupere detalhes de um plano de assinatura específico
• create_subscription: Crie uma nova assinatura
• show_subscription_details: Recupere detalhes de uma assinatura específica
• update_subscription: Atualize uma assinatura existente
• cancel_subscription: Cancele uma assinatura ativa

Relatórios e Insights

• list_transactions: Liste transações com paginação e filtragem opcionais
• get_merchant_insights: Recupere 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 client id e o secret da sua conta, que estão disponíveis no seu PayPal Developer Dashboard.

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,
        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 o modo sandbox, adicione contexto dentro da 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 PayPal Access Token
• PAYPAL_ENVIRONMENT: Defina como SANDBOX para modo sandbox, PRODUCTION para produção (o padrão é o modo SANDBOX)

Este guia explica como gerar um access token para integração com a API do PayPal, incluindo como encontrar seu client ID e client secret.

Pré-requisitos

• Conta de desenvolvedor PayPal (para Sandbox)
• Conta comercial PayPal (para produção)

Encontrando Seu Client ID e Client Secret

1. Crie uma Conta de Desenvolvedor PayPal:

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

2. Acesse Suas Credenciais:

   • No Developer Dashboard, clique em Apps & Credentials no menu
   • Alterne entre os modos Sandbox e Live conforme sua necessidade

3. Crie ou Visualize um App:

   • Para criar um novo app, clique em Create App
   • Dê um nome ao seu app e selecione uma conta comercial para associar a ele
   • Para apps existentes, clique no nome do app para visualizar os detalhes

4. Recupere as Credenciais:

   • Depois que seu app for criado ou selecionado, você verá uma tela com:
     • Client ID: Um identificador público para seu app
     • Client Secret: Uma chave privada (exibida após clicar em "Show")
   • Salve essas credenciais com segurança, pois elas são necessárias para gerar access tokens

Gerando um Access Token

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 solicitação para https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Defina o método como POST
3. Em Authorization, selecione Basic Auth e insira seu Client ID e Client Secret
4. Em Body, selecione x-www-form-urlencoded e adicione uma chave grant_type com valor client_credentials
5. Envie a solicitaçã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 uso na sua integração com o Claude Desktop.

Detalhes do Token

• Tokens de Sandbox: Válidos por 3-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 access token, 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 client ID e o client secret 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 no código do aplicativo

Aviso Legal

Conteúdo gerado por IA pode ser impreciso ou incompleto. Os usuários são responsáveis por verificar de forma independente qualquer informação antes de confiar nela. O PayPal não garante a precisão da saída e não é responsável por quaisquer decisões, ações ou consequências resultantes do seu uso.