ابدأ بعقد بين الطلب والدفع
اجعل لدى المتجر مرجعًا داخليًا ثابتًا لكل طلب، ومبلغًا وعملة وحالة واضحة. اربط محاولة الدفع بذلك المرجع بدل الاعتماد على بريد العميل أو رابط عائد في المتصفح فقط. حدد كذلك متى ينتهي الطلب، وكيف تتعامل مع محاولة دفع جديدة إذا انتهت السابقة، وما الذي يمنع تكرار تسليم الخدمة للطلب نفسه.
هذا تصميم لتطبيق التاجر، ولا يفترض أن كل تفاصيله تنفذها الواجهة نيابة عنه. اقرأ الحقول والحالات المعلنة في التوثيق الحالي، ثم طابقها مع نموذجك. عندما تختلف تسمية حالة داخل المنصة عن حالتك الداخلية، اكتب التحويل بينهما صراحة حتى يفهمه فريق التطوير وخدمة العملاء والمحاسبة، لا شخص واحد يعرف التكامل من ذاكرته.
المفاتيح تبقى في الخادم
راجع قسم المصادقة والصلاحيات قبل بناء الطلبات. المفاتيح السرية ليست مادة توضع في JavaScript يصل إلى المتصفح أو في مستودع عام أو صورة شرح. حدد بيئة تشغيل آمنة لإدارتها ومن يملك صلاحية استخدامها وتدويرها، ولا تمنح التطبيق أكثر مما يحتاجه من قدرات إذا كانت الخدمة تتيح تحديد النطاق أو الصلاحيات.
في السجلات، احتفظ بالمراجع والنتائج اللازمة للتشخيص دون طباعة الأسرار أو كامل بيانات العملاء. وإذا شاركت خطأ مع فريق دعم، احجب الحقول غير المطلوبة. فصل إدارة الاعتماد عن كتابة صفحة الدفع يقلل احتمال تسربه أثناء تطوير ميزة واجهة أو تصوير تجربة، ويساعد على إيقاف مفتاح محدد عند الحاجة دون إعادة بناء جميع المسارات.
عودة العميل ليست تأكيدًا ماليًا
قد يفتح العميل صفحة العودة أو يغلق النافذة أو يصل إليها مرتين. لذلك لا تعتمد على مجرد وصول المتصفح إلى رابط نجاح لتسليم سلعة مدفوعة. استخدم آلية التحقق التي توثقها الخدمة، وطابق المبلغ والعملة ومرجع الطلب والحالة المعتمدة قبل نقل الطلب إلى حالة تسمح بالتسليم. كل تحقق يجب أن يكون من جهة الخادم.
هذا الفصل يخدم العميل أيضًا: إذا انقطع اتصاله بعد الدفع، تستطيع المنظومة متابعة الحالة دون أن يتوقف حقه على بقاء المتصفح مفتوحًا. صمم صفحة عودة مفهومة تعرض حالة الطلب الحالية، مع مرجع دعم وخطوة تالية. لا تعرض خطأ تقنيًا خامًا أو تطلب منه الدفع ثانية قبل معرفة حالة المحاولة الأصلية بدقة.
عالج Webhooks كأحداث قابلة للتكرار
راجع التوثيق الرسمي للتوقيع والتحقق والأحداث المتاحة. لا تقبل إشعارًا لمجرد أنه يحمل اسم خدمة أو مرجعًا معروفًا. استخدم أسلوب التحقق المحدد، ثم اجعل المعالجة تتحمل وصول الحدث أكثر من مرة أو تأخره. قيد واحد موثوق لتسليم الطلب أفضل من تنفيذ إجراء تسليم جديد عند كل إشعار يصل إلى endpoint.
ضع أيضًا طريقة لمراجعة الحالة عندما لا يصل حدث في الوقت المتوقع. وجود Webhooks لا يعني استحالة انقطاع أو تأخير، كما أن التوقيع لا يغني عن فحص بيانات الحدث ومنطق الطلب. احتفظ بسجل محدود يبين متى استُقبل الحدث وكيف عولج، دون تحويل سجل التشخيص إلى مخزن دائم لمعلومات حساسة لا تحتاجها العملية.
اختبر مسارات الإخفاق قبل الإطلاق
اكتب حالات الاختبار قبل الشيفرة النهائية: مبلغ غير مطابق، عملة مختلفة، طلب منتهٍ، إشعار مكرر، توقيع غير صالح، واستجابة متأخرة. ثم اختبر السيناريوهات المسموح بها في البيئة التي توفرها الخدمة. لا تستخدم أموال العملاء الحقيقية كوسيلة لاكتشاف السلوك الأولي، ولا تفترض وجود بيئة تجريبية أو خاصية لم توثقها الجهة رسميًا.
اربط الاختبار بقرار واضح: متى يبقى الطلب قيد المراجعة؟ متى يُرفض؟ ومن يستطيع تعديل حالته يدويًا مع أثر مراجعة؟ يجب ألا تسمح معالجة الدعم بتجاوز ضوابط الدفع دون توثيق. هذا التصميم يمنع تحول حادث صغير في التكامل إلى تسليم مزدوج أو اختلاف محاسبي يصعب تفسيره بعد نمو حجم الطلبات.
التسوية والخدمة جزء من التكامل
قارن تقارير المدفوعات بسجل طلباتك، واحتفظ بمرجع يربط الاسترداد أو الإلغاء بالعملية الأصلية. حدد المسؤول عن متابعة الفروق وما المعلومات التي يراها. ولا تخلط بين إصدار بطاقات عبر API وقبول مدفوعات البطاقات من عملاء المتجر؛ كل وظيفة تحتاج إلى وصف وتفعيل وتوثيق يخصها، حتى إذا ظهرتا تحت العلامة التجارية نفسها.
ابدأ من توثيق وتد كاش الرسمي، ثم راجع أهلية حسابك وشروط التحصيل والتكلفة قبل الإطلاق. التكامل الناجح يجعل كل مبلغ قابلًا للتفسير وكل حالة قابلة للمتابعة، ويمنح العميل رسالة واضحة بدل تخمين. الوثائق هي المرجع للتفاصيل الحالية، أما هذه الخريطة فتعينك على طرح الأسئلة الصحيحة وتصميم دورة دفع يمكن لفريقك إدارتها بثقة.
أسئلة شائعة
هل رابط العودة دليل كافٍ لنجاح الدفع؟
لا. يجب التحقق من الحالة والمبلغ والعملة والمرجع عبر آلية الخادم الموثقة قبل تسليم الطلب.
لماذا أعالج تكرار Webhook؟
لأن تصميم المستهلك يجب أن يتحمل إعادة وصول حدث أو تأخره دون تكرار التسليم أو الأثر المحاسبي للطلب نفسه.
هل أضع مفتاح API في صفحة المتجر؟
لا تضع اعتمادًا سريًا في شفرة تصل للمتصفح أو مستودع عام. راجع التوثيق لإدارة المصادقة والصلاحيات من الخادم.
المصادر والتحقق
- وتد كاش: توثيق المطورينمراجعة 2026-10-18
- وتد كاش: توثيق المدفوعاتمراجعة 2026-10-18
- وتد كاش: توثيق Webhooksمراجعة 2026-10-18
- وتد كاش: توثيق المصادقةمراجعة 2026-10-18
- وتد كاش: بوابة الدفعمراجعة 2026-10-18