PayPal

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

PayPal Agent Toolkit

PayPal Agent Toolkit, OpenAI'nin Agent SDK'sı, LangChain, Vercel'in AI SDK'sı ve Model Context Protocol (MCP) dahil olmak üzere popüler ajan çerçevelerinin PayPal API'leriyle fonksiyon çağrıları aracılığıyla entegre olmasını sağlar. TypeScript desteği içerir ve PayPal API'leri ile PayPal SDK'ları üzerine inşa edilmiştir.

Mevcut araçlar

PayPal Agent toolkit aşağıdaki araçları sağlar:

Faturalar

• create_invoice: PayPal sisteminde alıcı fatura bilgileri, satır kalemleri, fatura notu, özel renk teması, isteğe bağlı nakliye ücreti ve PAY_BY_BANK ödeme yöntemi olarak etkinleştirme seçeneği dahil olmak üzere yeni bir fatura oluşturun

• list_invoices: İsteğe bağlı sayfalama ve filtreleme ile faturaları listeleyin

• get_invoice: Belirli bir faturanın ayrıntılarını alın

• send_invoice: Alıcılara bir fatura gönderin

• send_invoice_reminder: Mevcut bir fatura için hatırlatma gönderin

• cancel_sent_invoice: Gönderilmiş bir faturayı iptal edin

• generate_invoice_qr_code: Bir fatura için QR kodu oluşturun

• delete_invoice: Taslak veya zamanlanmış bir faturayı kalıcı olarak silin

• generate_invoice_number: Satıcı için kullanılabilir olan sonraki fatura numarasını oluşturun

• search_invoicing: Faturaları veya yinelenen fatura serilerini arayın

• update_invoicing: Mevcut bir faturayı veya yinelenen fatura serisini güncelleyin (tam değiştirme)

• cancel_invoice_auto_reminder: Bir fatura için zamanlanmış tüm otomatik hatırlatmaları iptal edin

• record_payment_for_invoice: Bir faturaya karşı harici veya manuel ödeme kaydedin

• record_refund_for_invoice: Bir faturaya karşı iade kaydedin

• create_conditional_rules_for_invoice: Bir fatura için erken ödeme indirimi veya otomatik iptal tarihi gibi koşullu kurallar oluşturun

• create_recurring_series: Otomatik olarak fatura oluşturan ve gönderen yinelenen bir fatura serisi oluşturun

• activate_recurring_series: Taslak yinelenen fatura serisini etkinleştirin

• get_recurring_series: Belirli bir yinelenen fatura serisinin ayrıntılarını alın

• cancel_recurring_series: Etkin bir yinelenen fatura serisini iptal edin

• delete_recurring_series: Taslak yinelenen fatura serisini silin

Ödemeler

• create_order: Sağlanan ayrıntılara göre PayPal sisteminde bir sipariş oluşturun
• get_order: Bir siparişin ayrıntılarını alın
• pay_order: Yetkilendirilmiş bir sipariş için ödeme işlemini gerçekleştirin
• create_refund: Yakalanan bir ödeme için iade işlemini gerçekleştirin
• get_refund: Belirli bir iadenin ayrıntılarını alın

Anlaşmazlık Yönetimi

• list_disputes: Tüm açık anlaşmazlıkların özetini alın
• get_dispute: Belirli bir anlaşmazlığın ayrıntılı bilgilerini alın
• accept_dispute_claim: Bir anlaşmazlık talebini kabul edin

Gönderi Takibi

• create_shipment_tracking: Bir gönderi takip kaydı oluşturun
• get_shipment_tracking: Gönderi takip bilgilerini alın
• update_shipment_tracking: Gönderi takip bilgilerini güncelleyin

Katalog Yönetimi

• create_product: PayPal kataloğunda yeni bir ürün oluşturun
• list_products: İsteğe bağlı sayfalama ve filtreleme ile ürünleri listeleyin
• show_product_details: Belirli bir ürünün ayrıntılarını alın

Abonelik Yönetimi

• create_subscription_plan: Yeni bir abonelik planı oluşturun
• list_subscription_plans: Abonelik planlarını listeleyin
• show_subscription_plan_details: Belirli bir abonelik planının ayrıntılarını alın
• create_subscription: Yeni bir abonelik oluşturun
• show_subscription_details: Belirli bir aboneliğin ayrıntılarını alın
• update_subscription: Mevcut bir aboneliği güncelleyin
• cancel_subscription: Etkin bir aboneliği iptal edin

Raporlama ve Analizler

• list_transactions: İsteğe bağlı sayfalama ve filtreleme ile işlemleri listeleyin
• get_merchant_insights: Bir satıcı için iş zekası metriklerini ve analizlerini alın

TypeScript

Kurulum

Paketi değiştirmek istemiyorsanız bu kaynak koda ihtiyacınız yoktur. Paketi kullanmak istiyorsanız şunu çalıştırın:

npm install @paypal/agent-toolkit

Gereksinimler

• Node 18+

Kullanım

Kütüphanenin, PayPal Developer Dashboard adresinde bulunan hesabınızın istemci kimliği ve gizli anahtarı ile yapılandırılması gerekir.

Toolkit, Vercel'in AI SDK'sı ile çalışır ve bir araç listesi olarak aktarılabilir. Daha fazla ayrıntı için örneklerimize bakın.

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

Sandbox modunu kullanmak için yapılandırmanıza bağlam ekleyin.

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

İş Akışlarını Başlatma

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

Kullanım

Toolkit'i kullanma

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

Ortam Değişkenleri

Aşağıdaki ortam değişkenleri kullanılabilir:

• PAYPAL_ACCESS_TOKEN: PayPal Erişim Belirteciniz
• PAYPAL_ENVIRONMENT: Sandbox modu için SANDBOX olarak ayarlayın, üretim için PRODUCTION (varsayılan SANDBOX modudur)

Bu kılavuz, PayPal API entegrasyonu için erişim belirtecinin nasıl oluşturulacağını ve istemci kimliğinizi ile gizli anahtarınızı nasıl bulacağınızı açıklar.

Ön koşullar

• PayPal Developer hesabı (Sandbox için)
• PayPal Business hesabı (üretim için)

İstemci Kimliğinizi ve Gizli Anahtarınızı Bulma

1. PayPal Developer Hesabı Oluşturun:

   • PayPal Developer Dashboard adresine gidin
   • PayPal kimlik bilgilerinizle kaydolun veya oturum açın

2. Kimlik Bilgilerinize Erişin:

   • Developer Dashboard'da menüden Apps & Credentials seçeneğine tıklayın
   • İhtiyaçlarınıza göre Sandbox ve Live modları arasında geçiş yapın

3. Uygulama Oluşturun veya Görüntüleyin:

   • Yeni bir uygulama oluşturmak için Create App seçeneğine tıklayın
   • Uygulamanıza bir ad verin ve ilişkilendirmek için bir Business hesabı seçin
   • Mevcut uygulamalar için ayrıntıları görüntülemek üzere uygulama adına tıklayın

4. Kimlik Bilgilerini Alın:

   • Uygulamanız oluşturulduğunda veya seçildiğinde, aşağıdakileri içeren bir ekran görürsünüz:
     • Client ID: Uygulamanız için genel bir tanımlayıcı
     • Client Secret: Özel bir anahtar ("Show" seçeneğine tıkladıktan sonra gösterilir)
   • Bu kimlik bilgilerini güvenli bir şekilde kaydedin çünkü erişim belirteçleri oluşturmak için gereklidirler

Erişim Belirteci Oluşturma

cURL kullanarak

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

CLIENT_ID ve CLIENT_SECRET değerlerini gerçek kimlik bilgilerinizle değiştirin. Üretim için sandbox URL'si yerine https://api-m.paypal.com kullanın.

Postman kullanarak

1. https://api-m.sandbox.paypal.com/v1/oauth2/token adresine yeni bir istek oluşturun
2. Yöntemi POST olarak ayarlayın
3. Authorization altında Basic Auth seçeneğini seçin ve İstemci Kimliğinizi ile Gizli Anahtarınızı girin
4. Body altında x-www-form-urlencoded seçeneğini seçin ve grant_type anahtarını client_credentials değeriyle ekleyin
5. İsteği gönderin

Yanıt

Başarılı bir yanıt şu şekilde görünecektir:

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

Claude Desktop entegrasyonunuzda kullanmak için access_token değerini kopyalayın.

Belirteç Ayrıntıları

• Sandbox Belirteçleri: 3-8 saat geçerlidir
• Üretim Belirteçleri: 8 saat geçerlidir
• Sona ermeden önce belirteç yenileme mantığı uygulanması önerilir

Belirteci Claude Desktop ile Kullanma

Erişim belirtecinizi aldıktan sonra, Claude Desktop bağlayıcı yapılandırmanızdaki PAYPAL_ACCESS_TOKEN değerini güncelleyin:

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

En İyi Uygulamalar

1. İstemci kimliğini ve gizli anahtarı güvenli bir şekilde saklayın
2. Belirteç sona ermesini yönetmek için belirteç yenileme mantığı uygulayın
3. Ortama özel belirteçler kullanın (test için sandbox, gerçek işlemler için üretim)
4. Uygulama kodunda belirteçleri sabit kodlamaktan kaçının

Sorumluluk Reddi

Yapay zeka tarafından oluşturulan içerik yanlış veya eksik olabilir. Kullanıcılar, herhangi bir bilgiye güvenmeden önce bağımsız olarak doğrulamaktan sorumludur. PayPal, çıktı doğruluğu konusunda garanti vermez ve kullanımından kaynaklanan kararlar, eylemler veya sonuçlardan sorumlu değildir.