پی‌پل

نود PayPal چیست؟

نود PayPal امکان خودکارسازی فرآیندهای مالی و پرداخت را در n8n فراهم می‌کند.

قابلیت‌های کلیدی:

• ایجاد و مدیریت پرداخت‌ها (Payments)
• مدیریت سفارشات (Orders) با Capture و Authorize
• فاکتورسازی خودکار (Invoices)
• مدیریت اشتراک‌ها (Subscriptions)
• پرداخت‌های گروهی (Payouts)
• بازپرداخت (Refunds)
• رسیدگی به اختلافات (Disputes)

PayPal REST API:

از PayPal REST API v2 استفاده می‌شود که امکانات کامل‌تری نسبت به Classic API دارد.

⚠️ نکته مهم برای کاربران ایرانی:

PayPal به دلیل تحریم‌ها مستقیماً در ایران در دسترس نیست. این نود برای:

• کسب‌وکارهایی که مشتریان بین‌المللی دارند
• فریلنسرهایی که از طریق واسطه با PayPal کار می‌کنند
• درگاه‌های پرداخت جایگزین: ZarinPal و IDPay برای پرداخت‌های داخلی
• الگوی مشابه PayPal را می‌توان با HTTP Request نود برای درگاه‌های ایرانی پیاده‌سازی کرد

موارد استفاده رایج نود PayPal

۱. پردازش سفارش فروشگاهی

دریافت سفارش از WooCommerce/Shopify > ایجاد Order در PayPal > Capture پس از تأیید > بروزرسانی وضعیت سفارش.

۲. فاکتورسازی خودکار

ایجاد و ارسال فاکتور برای مشتریان B2B. پس از انجام پروژه، فاکتور خودکار ارسال و وضعیت پرداخت ردیابی شود.

۳. سیستم اشتراک SaaS

مدیریت اشتراک‌های ماهانه/سالانه. ایجاد حساب پس از پرداخت. تعلیق پس از عدم پرداخت. ارسال یادآور تمدید.

۴. پرداخت پورسانت

پرداخت دوره‌ای پورسانت به همکاران فروش با Payouts. جمع‌آوری فروش‌ها و محاسبه خودکار پورسانت.

۵. بازپرداخت خودکار

بررسی درخواست‌های بازپرداخت و اجرای خودکار بر اساس شرایط (مثلاً تا 30 روز پس از خرید).

۶. همگام‌سازی حسابداری

ارسال خودکار تراکنش‌های PayPal به سیستم حسابداری. طبقه‌بندی درآمد و هزینه. گزارش مالی ماهانه.

۷. اعلان پرداخت

ارسال اعلان پرداخت موفق به Slack/Telegram/ایمیل. شامل جزئیات مبلغ، مشتری و محصول.

۸. مدیریت Disputes

ردیابی اختلافات و Claims. ایجاد تیکت پشتیبانی خودکار. اعلان فوری به تیم مالی.

۹. گزارش مالی هفتگی

جمع‌آوری تراکنش‌های هفته و تولید گزارش شامل: درآمد کل، تعداد تراکنش، میانگین مبلغ، بازپرداخت‌ها.

۱۰. تأیید پرداخت برای دسترسی دیجیتال

پس از پرداخت موفق، دسترسی به فایل/دوره آموزشی فعال شود. ارسال لینک دانلود یا اطلاعات دسترسی.

نکات و ترفندهای نود PayPal

تست با Sandbox

• همیشه ابتدا با Sandbox تست کنید
• از حساب‌های تستی PayPal استفاده کنید
• Sandbox و Live credentials جدا نگه دارید
• Webhook events در Sandbox هم کار می‌کنند

امنیت پرداخت

• Client Secret را هرگز در Frontend قرار ندهید
• Webhook Signature را Verify کنید
• مبلغ را Server-side تأیید کنید (نه فقط Client)
• از Idempotency Key برای جلوگیری از پرداخت تکراری استفاده کنید

مدیریت خطا

• Error handling قوی برای هر مرحله پرداخت
• Retry logic برای خطاهای موقتی
• لاگ همه تراکنش‌ها (موفق و ناموفق)
• اعلان فوری برای خطاهای بحرانی

بهینه‌سازی

• از Webhook به جای Polling برای وضعیت پرداخت
• Batch Payouts برای پرداخت‌های گروهی
• Cache Token (توکن OAuth2 برای 8 ساعت معتبر است)
• Pagination برای لیست تراکنش‌های بزرگ

جایگزین‌های ایرانی

• ZarinPal: مشابه PayPal برای تومان، API مشابه
• IDPay: درگاه پرداخت ایرانی با Webhook
• الگوی پیاده‌سازی مشابه: Create > Redirect > Verify
• از HTTP Request node برای درگاه‌های ایرانی استفاده کنید

Webhook Events مهم

• PAYMENT.CAPTURE.COMPLETED: پرداخت موفق
• PAYMENT.CAPTURE.DENIED: پرداخت رد شده
• BILLING.SUBSCRIPTION.CREATED: اشتراک جدید
• BILLING.SUBSCRIPTION.CANCELLED: لغو اشتراک
• CUSTOMER.DISPUTE.CREATED: اختلاف جدید

ادغام با سایر نودها

• WooCommerce/Shopify: پردازش سفارش
• Google Sheets: ثبت تراکنش‌ها
• Slack/Telegram: اعلان پرداخت
• QuickBooks: همگام‌سازی حسابداری
• Zendesk: ایجاد تیکت برای Disputes

عیب‌یابی نود PayPal

۱. خطای AUTHENTICATION_FAILURE

مشکل: Client ID یا Secret نادرست راه‌حل: از صحت Credentials اطمینان حاصل کنید. Sandbox و Live credentials متفاوتند. Environment صحیح انتخاب شود.

۲. خطای INVALID_RESOURCE_ID

مشکل: شناسه پرداخت/سفارش نامعتبر راه‌حل: شناسه باید از محیط مطابق باشد (Sandbox ID در Live کار نمی‌کند). فرمت صحیح بررسی شود.

۳. خطای ORDER_NOT_APPROVED

مشکل: Capture قبل از تأیید مشتری راه‌حل: مشتری باید ابتدا در PayPal پرداخت را تأیید کند. Redirect URL صحیح تنظیم شود.

۴. خطای CURRENCY_NOT_SUPPORTED

مشکل: ارز پشتیبانی نمی‌شود راه‌حل: لیست ارزهای مجاز PayPal را بررسی کنید. IRR/IRT پشتیبانی نمی‌شود.

۵. Webhook رویداد نمی‌رسد

مشکل: Webhook events دریافت نمی‌شود راه‌حل: URL باید HTTPS باشد. Event types صحیح انتخاب شوند. Webhook ID را Verify کنید.

۶. خطای INSUFFICIENT_FUNDS

مشکل: موجودی ناکافی برای Payout راه‌حل: موجودی PayPal را بررسی کنید. مبلغ Payout + کارمزد باید کافی باشد.

۷. Rate Limit

مشکل: تعداد درخواست‌ها زیاد راه‌حل: PayPal Rate Limit متغیر است. Wait node بین درخواست‌ها. از Batch API برای عملیات گروهی.

۸. فاکتور ارسال نمی‌شود

مشکل: Invoice در وضعیت DRAFT می‌ماند راه‌حل: پس از Create Invoice، باید Send Invoice را جداگانه فراخوانی کنید. ایمیل مشتری معتبر باشد.