Stripe

المكان في لوحة التحكم: Finance › Payment channels › Stripe (/payments/stripe). المفاتيح والرسوم: Finance › Payment channels › Fees & limits (/payments/fees).

الوظيفة

يقبل Stripe مدفوعات البطاقات لشحن المحفظة. وبنفس الحساب يمكنك أيضاً توفير Apple Pay، وGoogle Pay، وLink، وAlipay، والسماح للعملاء بـ حفظ البطاقة لـ الشحن التلقائي. استخدمه القناة الأساسية للعملاء الدوليين.

المتطلبات

العنصر	المتطلب
حساب Stripe	حساب Stripe قادراً على قبول المدفوعات بـ USD. يتم خصم قيمة Alipay بالعملة JPY ويجب تفعيلها من قِبل Stripe لحسابك.
المفاتيح	مفتاح سرّي (sk_live_... أو sk_test_...) ومفتاح قابل للنشر (pk_live_... أو pk_test_...). النموذج يقبل فقط المفاتيح التي تحمل هذه البادئات.
الشبكة	يجب أن تكون لوحتك قابلة للوصول عبر HTTPS من الإنترنت (حيث يستدعي Stripe الـ webhook) ويجب أن تصل إلى api.stripe.com على المنفذ 443.
النطاق (المحافظ فقط)	يجب أن يخدم النطاق المخصص للعملاء /.well-known/apple-developer-merchantid-domain-association — وتقوم NexCMP بذلك نيابة عنك.
الاعتمادات	لا يوجد.

حسابات Stripe المشتركة

تعالج NexCMP فقط أحداث الـ webhook للمدفوعات التي أنشأتها بنفسها، لذا يمكنك استخدام حساب Stripe يخدم تطبيقاً آخر أيضاً.

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

على جانب Stripe:

1. سجّل الدخول إلى Stripe Dashboard. قم بتشغيل أو إيقاف Test mode لتحديد ما إذا كنت تجري تشغيلاً تجريبياً أو تنتقل للإنتاج المباشر. مفاتيح أحد الوضعين لا تعمل أبداً مع الوضع الآخر.
2. افتح Developers › API keys. انسخ Publishable key، واكشف عن Secret key ثم انسخه. حافظ على سرية المفتاح السري.
3. (اختياري) افتح Settings › Payment methods وفعّل Alipay إذا كنت تريد توفيرها.
4. لا تحتاج إلى إنشاء الـ webhook يدوياً — يمكن لـ NexCMP إنشاؤه نيابة عنك (انظر الخطوة 5 أدناه). إذا كنت تفضل القيام بذلك يدوياً، أنشئ نقطة نهاية في Developers › Webhooks باستخدام عنوان URL والأحداث المدرجة في Webhook.

الربط في NexCMP

1. افتح Finance › Payment channels › Stripe (/payments/stripe).
2. في بطاقة API keys، اختر Mode (live أو test)، والصق Secret key وPublishable key.
3. انقر على Save. تُكتب المفاتيح في ملف تكوين على الخادم لا يمكن قراءته إلا بواسطة حساب خدمة NexCMP. ولا تُرسل أبداً مرة أخرى إلى المتصفح؛ وبعد ذلك تعرض الصفحة آخر 4 أحرف فقط.
4. انقر على Check. يعرض مربع الحوار الاتصال، والوضع، والرصيد المتاح والمعلق، ومعرف الحساب، وما إذا كانت عمليات الشخص مفعلة، وما إذا كان الـ webhook موجوداً وما إذا كانت Alipay متاحة. الخط الأحمر يعني أن هذا الجزء بحاجة إلى اهتمام.
5. في بطاقة Webhook، انقر على Create webhook وأكّد ذلك. تطلب NexCMP من Stripe إنشاء نقطة النهاية مع كل حدث مطلوب وتملأ حقل Webhook signing secret (whsec_...) تلقائياً. عنوان URL المملوء مسبقاً في الحقل هو https://<your-domain>/v1/billing/stripe/webhook، على سبيل المثال https://cloud.example.com/v1/billing/stripe/webhook.
6. افتح Fees & limits (/payments/fees)، واجعل Card (Stripe) مفعلاً، واضبط Stripe fee % وStripe fixed fee (cents) على تعريفتك الحقيقية وانقر على Save channels & fees. راجع Payment channels.

Webhook

تبقى الراية الحمراء "Missing webhook_secret" ظاهرة حتى يتم حفظ سر التوقيع. وبدونها لا يتم تسجيل عمليات شحن المحفظة عبر Stripe، حتى لو تلقى Stripe الأموال.

العنصر	القيمة
URL	https://<your-domain>/v1/billing/stripe/webhook
الأحداث	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
التوقيع	Stripe Stripe-Signature رأس الصفحة، HMAC-SHA256، سماحية 300 ثانية. الطلبات ذات التوقيع غير الصحيح تتلقى HTTP 400.
منع التكرار	يتم تخزين كل معرّف حدث مرة واحدة؛ ولن يؤدي التسليم المتكرر أبداً إلى إضافة رصيد مرتين.

إذا قمت بالتحديث من إصدار قام بتسجيل عدد أقل من الأحداث، فانقر فوق Create webhook مرة أخرى — يتم الاحتفاظ نقطة النهاية القديمة، لذا احذفها يدوياً في لوحة تحكم Stripe لاحقاً.

يوضح صفوف 24h events وLatest event في بطاقة Webhook ما إذا كانت Stripe تتصل باللوحة أم لا. يتم سرد الأحداث الفردية في Payment channels › Gateway events (/payments/events، علامة التبويب Stripe)، حيث يمكن عرض كل حدث (Payload) أو إعادة إرساله (Replay).

Apple Pay وGoogle Pay وLink

1. في بطاقة Wallets (Apple Pay · Google Pay · Link) & Alipay، يتم ملء حقل Customer app Domain registered with Stripe مسبقاً باسم مضيف موقعك (على سبيل المثال cloud.example.com).
2. انقر على Register / verify domain وأكد. تقوم NexCMP بتسجيل النطاق في نطاقات طرق الدفع الخاصة بـ Stripe وتطلب من Stripe التحقق منه.
3. تظهر النتيجة حالة Apple Pay وGoogle Pay وLink. يظهر Apple Pay فقط عندما تكون الحالة active.
4. في Fees & limits أبقِ خيار Apple Pay · Google Pay · Link مفعلاً.

بقاء Apple Pay غير نشط

يتطلب Apple Pay أن يستجيب ملف ارتباط النطاق برمز HTTP 200 على نطاقك العام. إذا وضعت Cloudflare أو وكيل آخر في المقدمة، فلا تقم بحظر /.well-known/.

Alipay

خدمة Alipay اختيارية. قم بتفعيلها في Stripe Dashboard › Settings › Payment methods، وانقر على Check وانتظر حتى يظهر الحوار أن Alipay متاحة، ثم قم بتشغيل Alipay (Stripe, JPY display) في Fees & limits. اضبط Alipay fee %، وAlipay fixed fee، و**¥/USD rate** (50–500)، وFX spread % (0–20). قم بتحديث سعر الصرف ¥/USD بانتظام؛ حيث تحذر الصفحة عندما يكون أقدم من 7 أيام.

التحقق

1. في وضع الاختبار، سجّل الدخول إلى البوابة كعميل اختبار، وافتح Billing، وانقر على Deposit، واختر Card وقم بدفع الحد الأدنى باستخدام بطاقة اختبار Stripe 4242 4242 4242 4242 (أي تاريخ مستقبلي، وأي رمز CVC).
2. يرتفع الرصيد في غضون ثوانٍ ويظهر الدفع ضمن Finance › Billing › Top-ups بالحالة Completed.
3. افتح Payment channels › Gateway events › Stripe: يجب أن ترى checkout.session.completed أو payment_intent.succeeded مع وقت تمت معالجته.
4. بالعودة إلى صفحة Stripe، يكون حقل 24h events أعلى من 0.

قبل الإطلاق الفعلي، قم بتحويل Mode إلى live، والصق مفاتيح التشغيل الفعلي وانقر على Create webhook مرة أخرى (فإن ويب هوك وضعي الاختبار والتشغيل الفعلي منفصلان).

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

• المبالغ والعملات. المحافظ بالدولار الأمريكي. تُخصم مدفوعات البطاقات والمحافظ والروابط بالدولار الأمريكي؛ بينما يُعرض Alipay للعميل بالين الياباني ويُحوَّل حسب سعرك.
• الرسوم. لا يتم قراءة رسوم Stripe الفعلية تلقائياً؛ نسبة الرسوم التي تعينها تحدد ما يراه العميل وما يُضاف إلى المحافظ. اختر Customer pays top-up fee ضمن Fees & limits لتحميل الرسوم إضافياً.
• المرتجعات البطاقة. عند تحديد العميل خيار Save card for auto top-up، تُحفظ البطاقة في Stripe وليس على خادرك. راجع Saved payment methods.
• الاستردادات. الاسترداد إلى البطاقة هو عملية من خطوتين: ينشئ المسؤول طلب استرداد لدفعة مكتملة (Finance › Billing › Top-ups، إجراء الاسترداد على الدفعة) ثم يوافق عليه ضمن Finance › Payouts › Card refunds (/billing/payouts). استردادات Alipay غير متزامنة؛ والفاشلة منها (refund.failed) تعيد المبلغ المحتجز إلى المحافظ.
• النزاعات. في حالة charge.dispute.created NexCMP، يقوم النظام بحظر حساب العميل، وإيقاف خدماته مدفوعة الأتاوة مسبقاً (دون حذف أي شيء) وإرسال تنبيه للمسؤول. إذا فزت بالنزاع (charge.dispute.closed)، يُعاد اعتماد المبلغ في المحافظ.
• المدفوعات المعلقة. إذا لم يصل طلب Webhook أبدًا، يتحقق NexCMP من المدفوعات التي ظلت معلقة لأكثر من 10 دقائق مقابل Stripe من تلقاء نفسه ويقوم بإتمامها. يتم تجاهل المدفوعات الأقدم من 7 أيام.
• يمكن لـ Resellers ربط حساب Stripe الخاص بهم (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>)؛ انظر Resellers.

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

العَرَض	السبب	الحل
"يجب أن تبدأ المفتاح السري بـ sk_live_/sk_test_"	تم لصق مفتاح خاطئ	الصق المفتاح السري من Developers › API keys.
"المفتاح السري لا يتطابق مع وضع البث المباشر/الاختبار"	وضع التشغيل والمفتاح غير متطابقين	اجعل Mode يطابق بادئة المفتاح.
"يجب أن يبدأ المفتاح القابل للنشر بـ pk_"	مفتاح خاطئ	استخدم المفتاح القابل للنشر.
يقول الفحص إن الاتصال فشل	مفتاح خاطئ، أو تم إلغاء المفتاح، أو لا يمكن للخادم الوصول إلى api.stripe.com	أعد لصق المفتاح؛ واختبره باستخدام curl -I https://api.stripe.com من الخادم.
لافتة حمراء "Missing webhook_secret"	لم يتم حفظ سر التوقيع	انقر فوق Create webhook أو الصق سر whsec_... من لوحة تحكم Stripe وانقر فوق Save.
تم خصم الأموال ولكن الرصيد لم يتغير	لم يتم تسليم Webhook أو فشل التوقيع	تحقق من أن عنوان URL ينتهي بـ /v1/billing/stripe/webhook، وأن السر يطابق نقطة النهاية، وأعد تشغيل الحدث في Gateway events. في Stripe، افتح نقطة النهاية وانظر في محاولات التسليم (HTTP 400 يعني وجود سر توقيع خاطئ).
فشل "Create webhook"	عنوان URL ليس HTTPS أو لا يمكن الوصول إليه	استخدم نطاقك العام https://.
حالة Apple Pay غير نشطة	النطاق غير مصادق عليه	انقر فوق Register / verify domain مرة أخرى بعد أن يستجيب ملف ربط النطاق برمز 200.
Alipay غير متوفر في مربع حوار التحقق	غير مفعل في Stripe	قم بتفعيله في لوحة تحكم Stripe، ثم انقر فوق Check.
لا يرى العميل نموذج البطاقة	Card (Stripe) معطل أو لا يوجد مفتاح سري	قم بتفعيله في Fees & limits واحفظ المفاتيح.