لماذا تفشل مدفوعات Stripe لدى أعضائي؟
التحقق من مفتاح BYOK، تسجيل نقطة نهاية Webhook، عدم التطابق بين وضع الاختبار والوضع الحقيقي، وإعداد بوابة العميل — أصلح أخطاء مدفوعات Stripe في عضوية VeloCMS.
الدفعة الفاشلة هي أسوأ ما يمكن أن يحدث لعضوية مدفوعة — إذ يعني ذلك أن مشتركًا يحاول دفع المال لا يستطيع ذلك. وإذا كان يحدث بصمت — يعرض نموذج الدفع خطأ دون أن تعلم كصاحب المدونة — فقد تخسر إيرادات دون أن تدري. إليك كيفية تحديد المشكلة وإصلاحها.
الخطوة 1 — التحقق من مفتاح Stripe BYOK
تعتمد VeloCMS على نظام Bring Your Own Keys (BYOK) لـ Stripe — أي أنك تربط حساب Stripe الخاص بك. انتقل إلى الإعدادات ← الإدارة ← العضوية ← اتصال Stripe وتحقق من حالة الاتصال. إذا ظهر "متصل" مع مؤشر أخضر، فمفتاحك صحيح. إذا ظهر "مفتاح غير صالح" أو "غير متصل"، فالمفتاح السري الذي أدخلته ربما كان خاطئًا أو منتهي الصلاحية أو من حساب Stripe خاطئ.
- في لوحة تحكم Stripe، انتقل إلى المطورون ← مفاتيح API.
- للإنتاج، استخدم المفتاح السري الحقيقي (يبدأ بـ sk_live_). للاختبار، استخدم المفتاح السري التجريبي (يبدأ بـ sk_test_).
- لا تستخدم مطلقًا المفتاح القابل للنشر (يبدأ بـ pk_) كمفتاح سري — فلن يعمل في عمليات جانب الخادم.
- إذا أنشأت مفتاحًا مقيدًا، تأكد من أنه يمتلك صلاحيات القراءة والكتابة لـ: جلسات Checkout، وبوابة العميل، والعملاء، ونوايا الدفع، والأسعار، والمنتجات، والاشتراكات، ونقاط نهاية Webhook.
- في إعدادات VeloCMS ← الإدارة ← العضوية ← اتصال Stripe، الصق المفتاح الصحيح وانقر حفظ. ستتحقق الصفحة فورًا من المفتاح عبر طلب API اختباري.
الخطوة 2 — التحقق من تسجيل نقطة نهاية Webhook
تستخدم Stripe نقاط نهاية Webhook لإخبار VeloCMS عند نجاح الدفعة أو فشلها أو تغيير حالة الاشتراك. بدون Webhook يعمل بشكل سليم، لا تستطيع VeloCMS تفعيل وصول العضو بعد الدفع الناجح — أي يدفع العضو لكن حسابه يبقى مقفلًا.
- في لوحة تحكم Stripe، انتقل إلى المطورون ← Webhooks.
- ابحث عن نقطة نهاية بتنسيق URL: https://yourslug.velocms.org/api/member-webhook/yourslug.
- إذا لم توجد نقطة نهاية مماثلة، انتقل إلى إعدادات VeloCMS ← الإدارة ← العضوية ← إعداد Webhook وانقر على تسجيل Webhook — سينشئها VeloCMS تلقائيًا.
- إذا كانت نقطة النهاية موجودة لكنها تعرض أخطاء حديثة في Stripe، انقر عليها وراجع تفاصيل الحدث الفاشل. الأخطاء الشائعة: 401 (سر Webhook خاطئ)، 500 (خطأ في الخادم — راجع سجلات Railway)، 404 (خدمة VeloCMS معطلة).
- انسخ سر توقيع Webhook من Stripe والصقه في إعدادات VeloCMS ← الإدارة ← العضوية ← سر Webhook. بدونه، سترفض VeloCMS جميع أحداث Webhook الواردة.
عدم التطابق بين وضع الاختبار والوضع الحقيقي
تمتلك Stripe بيئتين منفصلتين تمامًا: وضع الاختبار ووضع الإنتاج الحقيقي. مفاتيح API والعملاء والمنتجات والأسعار ونقاط نهاية Webhook في وضع الاختبار غير موجودة في الوضع الحقيقي والعكس صحيح. خطأ شائع هو إعداد المنتجات والأسعار في وضع الاختبار ثم التبديل إلى مفتاح سري حقيقي — فتحاول VeloCMS البحث عن المنتج في الوضع الحقيقي ولا تجده.
يجب إنشاء أسعار عضوية Stripe في الوضع ذاته الذي يستخدمه مفتاحك. إذا كنت تستخدم مفتاحًا حقيقيًا (sk_live_)، فيجب أن تكون أسعارك قد أُنشئت في وضع Stripe الحقيقي. تحقق من لوحة تحكم Stripe مع إيقاف تبديل وضع الاختبار لرؤية بيانات الوضع الحقيقي.
إعداد بوابة العميل
إذا كان الدفع يعمل لكن الأعضاء لا يستطيعون إدارة اشتراكاتهم (الإلغاء، أو تحديث البطاقة، أو عرض الفواتير)، فقد لا تكون بوابة عميل Stripe مهيأة. في لوحة تحكم Stripe، انتقل إلى الإعدادات ← الفوترة ← بوابة العميل. فعّل البوابة وتأكد على الأقل من تمكين: سجل الفواتير، وإلغاء الاشتراك، وتحديث طريقة الدفع. بدون هذه الإعدادات، يعرض رابط البوابة في إعدادات VeloCMS ← الإدارة ← الفوترة صفحة خطأ عامة من Stripe.
يصل الأعضاء إلى إدارة اشتراكاتهم عبر صفحة /member/account في مدونتك. إذا أظهرت البوابة خطأ، فتحقق من إعداد بوابة عميل Stripe أولًا قبل البحث في إعدادات VeloCMS.