PayPal

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

PayPal Agent Toolkit

PayPal Agent Toolkit memungkinkan kerangka kerja agen populer termasuk Agent SDK dari OpenAI, LangChain, AI SDK dari Vercel, dan Model Context Protocol (MCP) untuk terintegrasi dengan API PayPal melalui pemanggilan fungsi. Toolkit ini mendukung TypeScript dan dibangun di atas API PayPal dan SDK PayPal.

Alat yang Tersedia

PayPal Agent toolkit menyediakan alat-alat berikut:

Faktur

• create_invoice: Buat faktur baru di sistem PayPal, termasuk detail penagihan penerima, item baris, catatan faktur, tema warna kustom, biaya pengiriman opsional, dan opsi untuk mengaktifkan PAY_BY_BANK sebagai metode pembayaran

• list_invoices: Daftar faktur dengan paginasi dan pemfilteran opsional

• get_invoice: Ambil detail faktur tertentu

• send_invoice: Kirim faktur ke penerima

• send_invoice_reminder: Kirim pengingat untuk faktur yang sudah ada

• cancel_sent_invoice: Batalkan faktur yang telah dikirim

• generate_invoice_qr_code: Buat kode QR untuk faktur

• delete_invoice: Hapus permanen faktur draf atau terjadwal

• generate_invoice_number: Buat nomor faktur berikutnya yang tersedia untuk merchant

• search_invoicing: Cari faktur atau seri faktur berulang

• update_invoicing: Perbarui faktur atau seri faktur berulang yang ada (penggantian penuh)

• cancel_invoice_auto_reminder: Batalkan semua pengingat otomatis terjadwal untuk faktur

• record_payment_for_invoice: Catat pembayaran eksternal atau manual terhadap faktur

• record_refund_for_invoice: Catat pengembalian dana terhadap faktur

• create_conditional_rules_for_invoice: Buat aturan bersyarat untuk faktur, seperti diskon pembayaran awal atau tanggal pembatalan otomatis

• create_recurring_series: Buat seri faktur berulang yang secara otomatis membuat dan mengirim faktur sesuai jadwal

• activate_recurring_series: Aktifkan seri faktur berulang draf

• get_recurring_series: Ambil detail seri faktur berulang tertentu

• cancel_recurring_series: Batalkan seri faktur berulang yang aktif

• delete_recurring_series: Hapus seri faktur berulang draf

Pembayaran

• create_order: Buat pesanan di sistem PayPal berdasarkan detail yang diberikan
• get_order: Ambil detail pesanan
• pay_order: Proses pembayaran untuk pesanan yang telah diotorisasi
• create_refund: Proses pengembalian dana untuk pembayaran yang telah ditangkap
• get_refund: Dapatkan detail untuk pengembalian dana tertentu

Manajemen Sengketa

• list_disputes: Ambil ringkasan semua sengketa yang terbuka
• get_dispute: Ambil informasi detail sengketa tertentu
• accept_dispute_claim: Terima klaim sengketa

Pelacakan Pengiriman

• create_shipment_tracking: Buat catatan pelacakan pengiriman
• get_shipment_tracking: Ambil informasi pelacakan pengiriman
• update_shipment_tracking: Perbarui informasi pelacakan pengiriman

Manajemen Katalog

• create_product: Buat produk baru di katalog PayPal
• list_products: Daftar produk dengan paginasi dan pemfilteran opsional
• show_product_details: Ambil detail produk tertentu

Manajemen Langganan

• create_subscription_plan: Buat rencana langganan baru
• list_subscription_plans: Daftar rencana langganan
• show_subscription_plan_details: Ambil detail rencana langganan tertentu
• create_subscription: Buat langganan baru
• show_subscription_details: Ambil detail langganan tertentu
• update_subscription: Perbarui langganan yang ada
• cancel_subscription: Batalkan langganan yang aktif

Pelaporan dan Wawasan

• list_transactions: Daftar transaksi dengan paginasi dan pemfilteran opsional
• get_merchant_insights: Ambil metrik intelijen bisnis dan analitik untuk merchant

TypeScript

Instalasi

Anda tidak memerlukan kode sumber ini kecuali Anda ingin memodifikasi paket. Jika Anda hanya ingin menggunakan paket, jalankan:

npm install @paypal/agent-toolkit

Persyaratan

• Node 18+

Penggunaan

Pustaka ini perlu dikonfigurasi dengan client id dan secret akun Anda yang tersedia di PayPal Developer Dashboard.

Toolkit ini berfungsi dengan AI SDK dari Vercel dan dapat diteruskan sebagai daftar alat. Untuk detail lebih lanjut, lihat contoh kami.

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

Untuk menggunakan mode sandbox, tambahkan konteks dalam konfigurasi Anda.

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

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

Penggunaan

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

Variabel Lingkungan

Variabel lingkungan berikut dapat digunakan:

• PAYPAL_ACCESS_TOKEN: Token Akses PayPal Anda
• PAYPAL_ENVIRONMENT: Setel ke SANDBOX untuk mode sandbox, PRODUCTION untuk produksi (default ke mode SANDBOX)

Panduan ini menjelaskan cara membuat token akses untuk integrasi API PayPal, termasuk cara menemukan client ID dan client secret Anda.

Prasyarat

• Akun Pengembang PayPal (untuk Sandbox)
• Akun Bisnis PayPal (untuk produksi)

Menemukan Client ID dan Client Secret Anda

1. Buat Akun Pengembang PayPal:

   • Buka PayPal Developer Dashboard
   • Daftar atau masuk dengan kredensial PayPal Anda

2. Akses Kredensial Anda:

   • Di Developer Dashboard, klik Apps & Credentials di menu
   • Beralih antara mode Sandbox dan Live sesuai kebutuhan Anda

3. Buat atau Lihat Aplikasi:

   • Untuk membuat aplikasi baru, klik Create App
   • Beri nama aplikasi Anda dan pilih akun Bisnis untuk dikaitkan dengannya
   • Untuk aplikasi yang sudah ada, klik nama aplikasi untuk melihat detail

4. Ambil Kredensial:

   • Setelah aplikasi Anda dibuat atau dipilih, Anda akan melihat layar dengan:
     • Client ID: Pengidentifikasi publik untuk aplikasi Anda
     • Client Secret: Kunci pribadi (ditampilkan setelah mengklik "Show")
   • Simpan kredensial ini dengan aman karena diperlukan untuk membuat token akses

Membuat Token Akses

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

Ganti CLIENT_ID dan CLIENT_SECRET dengan kredensial Anda yang sebenarnya. Untuk produksi, gunakan https://api-m.paypal.com alih-alih URL sandbox.

Menggunakan Postman

1. Buat permintaan baru ke https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Setel metode ke POST
3. Di bawah Authorization, pilih Basic Auth dan masukkan Client ID dan Client Secret Anda
4. Di bawah Body, pilih x-www-form-urlencoded dan tambahkan kunci grant_type dengan nilai client_credentials
5. Kirim permintaan

Respons

Respons yang berhasil akan terlihat seperti:

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

Salin nilai access_token untuk digunakan dalam integrasi Claude Desktop Anda.

Detail Token

• Token Sandbox: Berlaku selama 3-8 jam
• Token Produksi: Berlaku selama 8 jam
• Disarankan untuk menerapkan logika pembaruan token sebelum kedaluwarsa

Menggunakan Token dengan Claude Desktop

Setelah Anda memiliki token akses, perbarui nilai PAYPAL_ACCESS_TOKEN dalam konfigurasi konektor Claude Desktop Anda:

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

Praktik Terbaik

1. Simpan client ID dan client secret dengan aman
2. Terapkan logika pembaruan token untuk menangani kedaluwarsa token
3. Gunakan token khusus lingkungan (sandbox untuk pengujian, produksi untuk transaksi nyata)
4. Hindari hardcoding token dalam kode aplikasi

Penyangkalan

Konten yang dihasilkan AI mungkin tidak akurat atau tidak lengkap. Pengguna bertanggung jawab untuk memverifikasi informasi secara independen sebelum mengandalkannya. PayPal tidak memberikan jaminan mengenai keakuratan keluaran dan tidak bertanggung jawab atas keputusan, tindakan, atau konsekuensi apa pun yang timbul dari penggunaannya.