PayPal

PayPal Agent Toolkit

Toolkit Agen PayPal memungkinkan kerangka kerja agen populer termasuk OpenAI's Agent SDK, LangChain, Vercel's AI SDK, dan Model Context Protocol (MCP) untuk berintegrasi dengan API PayPal melalui pemanggilan fungsi. Ini mencakup dukungan untuk TypeScript dan dibangun di atas API PayPal dan SDK PayPal.

Alat yang Tersedia

Toolkit agen PayPal 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
• create_recurring_series: Buat seri faktur berulang yang secara otomatis menghasilkan dan mengirim faktur sesuai jadwal
• list_invoices: Daftar faktur dengan paginasi dan penyaringan 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: Hasilkan kode QR untuk faktur

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 terperinci dari 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 penyaringan 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 penyaringan opsional
• get_merchant_insights: Ambil metrik intelijen bisnis dan analitik untuk pedagang

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 Dasbor Pengembang PayPal.

Toolkit ini bekerja dengan Vercel's AI SDK 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,
        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 },
    },
  },
});

Untuk menggunakan mode sandbox, tambahkan konteks dalam konfigurasi Anda.

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

Menginisialisasi Alur Kerja

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: Access Token PayPal Anda
• PAYPAL_ENVIRONMENT: Setel ke SANDBOX untuk mode sandbox, PRODUCTION untuk produksi (default ke mode SANDBOX)

Panduan ini menjelaskan cara menghasilkan access token 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 Dasbor Pengembang PayPal
   • Daftar atau masuk dengan kredensial PayPal Anda

2. Akses Kredensial Anda:

   • Di Dasbor Pengembang, 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 mengaitkannya
   • 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 menghasilkan access token

Menghasilkan Access Token

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. Atur 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 penyegaran token sebelum kedaluwarsa

Menggunakan Token dengan Claude Desktop

Setelah Anda memiliki access token, 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 penyegaran 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.