---
title: PayPal
description: ربط PayPal بـ NexCMP لشحن المحفظة — بيانات اعتماد تطبيق REST، وWebhook، واختبار البيئة التجريبية (Sandbox)، وحسابات PayPal المحفوظة.
url: https://nexcmp.com/ar/docs/billing/paypal/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# PayPal

> **المكان في لوحة التحكم:** Finance › Payment channels › PayPal (`/payments/paypal`). مفتاح التشغيل/الإيقاف والرسوم موجودة في Finance › Payment channels › Fees & limits (`/payments/fees`).

## الوظيفة {#what-it-does}

يسمح للعملاء بشحن محفظتهم بالدولار الأمريكي باستخدام رصيد PayPal الخاص بهم أو حسابهم البنكي أو البطاقة المخزنة في PayPal. يمكن للعملاء أيضًا السماح لـ NexCMP بتذكر حساب PayPal الخاص بهم من أجل [automatic top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/). استخدامه جنباً إلى جنب مع [Stripe](https://nexcmp.com/ar/docs/billing/stripe/) للعملاء الذين يفضلون PayPal.

## المتطلبات {#requirements}

| العنصر | المتطلب |
|---|---|
| حساب PayPal | حساب **تجاري (Business)** على PayPal يمكنه استقبال الدولار الأمريكي. |
| تطبيق REST | تطبيق REST واحد في لوحة تحكم مطوري PayPal (**Apps & Credentials**) يوفّر **Client ID** و **Client secret**. استخدم علامة التبويب **Sandbox** للاختبار، و **Live** للإنتاج. |
| الشبكة | HTTPS يمكن الوصول إليه من الإنترنت (يستدعي PayPal خدمة webhook) ووصول صادر إلى `api-m.paypal.com` (مباشر) أو `api-m.sandbox.paypal.com` (تجريبي)، المنفذ 443. |
| الأذونات | يحتاج تطبيق REST إلى صلاحيات استرداد الأموال و webhooks. يُظهر مربع حوار **Check** ما إذا كان كلا النطاقين موجودين. |
| الاعتمادات | لا يوجد. |

## تجهيز البنية التحتية {#prepare-the-infrastructure}

1. قم بتسجيل الدخول إلى [developer.paypal.com](https://developer.paypal.com) باستخدام حساب الأعمال الخاص بك وافتح **Apps & Credentials**.
2. اختر **Sandbox** (للاختبار) أو **Live**، ثم **Create App**. قم بتسميته على سبيل المثال "NexCMP".
3. انسخ **Client ID** و **Secret** الخاصين بالتطبيق.
4. للاختبار، استخدم **Testing Tools › Sandbox Accounts** للعثور على حساب تجريبي *Personal* (مشتري) أو إنشاء حساب جديد.
5. لا تحتاج إلى إنشاء الويب هوك بنفسك؛ حيث ينشئه NexCMP باستخدام الزر **Create webhook**.

## الربط في NexCMP {#connect-in-nexcmp}

1. افتح **Finance › Payment channels › PayPal** (`/payments/paypal`).
2. في **API keys**، اختر **Mode**: `live` (أموال حقيقية، `api-m.paypal.com`) أو `sandbox` (`api-m.sandbox.paypal.com`).
3. الصق **Client ID** (ما لا يقل عن 20 حرفاً) و **Client secret**.
4. انقر فوق **Check**. تختبر هذه الوظيفة بيانات الاعتماد التي أدخلتها (الحفظ غير مطلوب) وتُبلغ عن الاتصال، ومعرف التطبيق، والوضع، وما إذا كانت نطاقات الاسترداد وويب هوك موجودة، ومدة صلاحية الرمز المميز.
5. انقر فوق **Save**.
6. في بطاقة **Webhook**، تأكد من أن عنوان URL هو `https://<your-domain>/v1/billing/paypal/webhook` (يجب أن يكون `https`)، ثم انقر فوق **Create webhook** وقم التأكيد. يطلب NexCMP من PayPal إنشاء أو تحديث الويب هوك بـ 11 حدثاً ويخزن **Webhook ID** المُعاد. يستخدم الزر المفاتيح **المحفوظة** — احفظ أولاً إذا قمت بتعديلها للتو.
7. انقر فوق **Check** مرة أخرى: يجب أن يُظهر صف **Webhook** "موجود، 11 حدثاً".
8. افتح **Fees & limits**، وقم بتفعيل **PayPal**، واضبط **PayPal fee %** (الافتراضي 4.4) و **PayPal fixed fee (cents)** (الافتراضي 30) لتعرفة الخاصة بك وانقر فوق **Save channels & fees**.

![صفحة PayPal مع وضع الحماية وبيانات الاعتماد التجريبية المُدخلة](https://nexcmp.com/ar/docs/images/billing/paypal-01-keys.webp)


### أحداث ويب هوك {#webhook-events}

يسجل NexCMP هذه الأحداث الـ 11: `CHECKOUT.ORDER.APPROVED`، `PAYMENT.CAPTURE.COMPLETED`، `PAYMENT.CAPTURE.PENDING`، `PAYMENT.CAPTURE.DECLINED`، `PAYMENT.CAPTURE.REFUNDED`، `PAYMENT.CAPTURE.REVERSED`، `CUSTOMER.DISPUTE.CREATED`، `CUSTOMER.DISPUTE.UPDATED`، `CUSTOMER.DISPUTE.RESOLVED`، `RISK.DISPUTE.CREATED`، `CHECKOUT.PAYMENT-APPROVAL.REVERSED`.

يتم التحقق من كل Webhook عن طريق استدعاء واجهة برمجة التطبيقات (API) الخاصة بالتحقق من التوقيع في PayPal، وتخزينها مرة واحدة ومعالجتها بشكل آمن. لا تثق NexCMP أبدًا في المبلغ الوارد في جسم Webhook: قبل تقييد أي عملية استلام، تقوم بجلب تفاصيلها مباشرة من PayPal.

## التحقق {#verify}

1. أبقِ **Mode** على `sandbox`. في البوابة، افتح **Billing › Deposit**، واختر **PayPal**، وانقر على **Continue on PayPal** (أو زر PayPal) وسجّل الدخول باستخدام حساب المشتري في sandbox.
2. وافق على الدفعة. ستعود إلى البوابة، ويزداد الرصيد وتظهر الدفعة ضمن **Finance › Billing › Top-ups** بالحالة *Completed*.
3. افتح **Payment channels › Gateway events › PayPal & USDT**: يتم سرد الحدث `PAYMENT.CAPTURE.COMPLETED`.
4. عندما يعمل كل شيء، قم بتحويل **Mode** إلى `live`، وأدخل بيانات الاعتماد الحية، و **Save**، ثم **Create webhook** مرة أخرى (ويب هوك وضع الحماية والوضع الحي منفصلان).

## الحدود والملاحظات {#limits-notes}

- **كيف تتم الدفعة.** يتم إنشاء الطلب بالدولار الأمريكي؛ وبعد موافقة العميل عليه، يقوم **الخادم** بتحصيله (طلب بمعرف فريد لتجنب التكرار) وإضافة رصيد المحفظة مرة واحدة بالضبط. يُعد الويب هوك وظيفة مطابقة التسوية التي تعمل كل 10 دقائق شبكات أمان في حال أقام العميل بإغلاق المتصفح.
- **الطلبات المعلقة والمهملة.** يمكن أن يظل الطلب مفتوحاً لمدة 12 ساعة. يمكن أن يكون لدى العميل 5 طلبات معلقة كحد أقصى (يستجيب الخادم بـ `too_many_pending`، HTTP 429). الطلب الذي لم يتم تحصيله بعد 24 ساعة يُعلم بأنه فاشل.
- **لم يتم تكوين ويب هوك.** تُرجع لوحة التحكم HTTP 503 لكل ويب هوك خاص بـ PayPal حتى يتم حفظ معرف Webhook ID. التحصيلات التي تتم عبر البوابة وتسوية ال10 دقائق لا تزال تضيف رصيداً للمحفظة، ولكن لا يتم تطبيق أي شيء يبلغ عنه PayPal عبر الويب هوك (النزاعات، الاستردادات، التحصيلات المتأخرة) — انقر فوق **Create webhook**.
- **حساب PayPal المحفوظ.** عندما يختار العميل حفظ PayPal (أو يُكمل أول إيداع، مما يؤدي إلى تفعيل [automatic top-up](https://nexcmp.com/ar/docs/billing/auto-top-up/)) يقوم PayPal بتخزين رمز الدفع في خزينة الأمان الخاصة به. يحتفظ NexCMP بمعرف فقط و بريد PayPal الإلكتروني. راجع [Saved payment methods](https://nexcmp.com/ar/docs/billing/saved-payment-methods/).
- **Refunds and disputes** يتم التعامل معها مثل Stripe: يتم الموافقة على طلبات الاسترداد ضمن **Finance › Payouts › Card refunds**؛ النزاع يؤدي إلى حظر حساب العميل وإيقاف خدماته المدفوعة مسبقاً حتى تقوم بحله.
- **Fees.** لا يتم قراءة رسوم PayPal تلقائياً؛ النسبة المئوية والرسوم الثابتة التي تقوم بإعدادها تحدد ما يراه العميل وما يتم إضافته لرصيده. التعريفة الحقيقية تعتمد على دولتك (النموذج يوضح 4.4 % لفيتنام و 3.49 % للولايات المتحدة).

## استكشاف الأخطاء وإصلاحها {#troubleshooting}

| العَرَض | السبب | الحل |
|---|---|---|
| "معرف العميل قصير جداً" | تم لصق أقل من 20 حرفاً | انسخ معرف العميل (Client ID) بالكامل. |
| "يجب أن تبدأ رابط Webhook بـ https" | تم كتابة الرابط بـ `http://` | استخدم نطاقك العام `https://`. |
| الفحص يُبلغ عن خطأ في الاتصال | وضع خاطئ (مفاتيح حية في بيئة التجربة أو العكس)، كلمة سر خاطئة، لا يوجد وصول للخارج | طابق **Mode** مع نوع المفتاح؛ اختبر `curl -I https://api-m.paypal.com` من الخادم. |
| نطاق الاسترداد / الـ webhooks يُظهر "no" | تفتقر تطبيقات REST إلى هذه الميزات | قم بتفعيل الميزات على التطبيق في لوحة تحكم مطوري PayPal. |
| لافتة "PayPal key set, NO webhook" | معرف الـ Webhook مفقود | انقر على **Create webhook**. |
| "Webhook not found" في الفحص | تم حذف الـ Webhook في PayPal أو أنه ينتمي لتطبيق آخر | انقر على **Create webhook** مرة أخرى. |
| يُقال للعميل أن PayPal رفض الدفع | رفض PayPal مصدر التمويل هذا | اطلب من العميل اختيار مصدر دفع آخر. |
| العميل يرى "Too many pending requests" | 5 طلبات مفتوحة | انتظر حتى تنتهي صلاحيتها أو قم بإتمامها. |
| زر PayPal مفقود | PayPal معطل في **Fees & limits** أو غير مُعَد | قم بتفعيله واحفظ بيانات الاعتماد. |