PayPal

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

الوظيفة

يسمح للعملاء بشحن محفظتهم بالدولار الأمريكي باستخدام رصيد PayPal الخاص بهم أو حسابهم البنكي أو البطاقة المخزنة في PayPal. يمكن للعملاء أيضًا السماح لـ NexCMP بتذكر حساب PayPal الخاص بهم من أجل automatic top-up. استخدامه جنباً إلى جنب مع Stripe للعملاء الذين يفضلون PayPal.

المتطلبات

العنصر	المتطلب
حساب 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 ما إذا كان كلا النطاقين موجودين.
الاعتمادات	لا يوجد.

تجهيز البنية التحتية

1. قم بتسجيل الدخول إلى 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

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.

أحداث ويب هوك

يسجل 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.

التحقق

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 مرة أخرى (ويب هوك وضع الحماية والوضع الحي منفصلان).

الحدود والملاحظات

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

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

العَرَض	السبب	الحل
"معرف العميل قصير جداً"	تم لصق أقل من 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 أو غير مُعَد	قم بتفعيله واحفظ بيانات الاعتماد.