silvercloudالرئيسية ↗
عربي

SILVERCLOUD / مقال تقني

تأكيد دفع يمكن الوثوق به: قائمة تحقق من جهة الخادم للتطبيقات والمواقع

مدة القراءة: 8 دقائق

يضغط العميل على «ادفع»، فتظهر علامة صح خضراء، ثم يغلق التطبيق. هل دُفع الطلب؟ على الأرجح. لكن «على الأرجح» لا تكفي حين يتعلق الأمر بالمال. فالعلامة الخضراء لا تعني إلا أن جهازًا واحدًا وصل إلى نهاية مسار من الشاشات. أما هل انتقلت الأموال فعلًا، فهذا ما يعرفه مزوّد الدفع، وعلى خادمك أن يعرفه من المزوّد مباشرة، عبر قناة لا يمكن لأحد تزويرها.

تتناول قائمة التحقق هذه حالات الدفع، والتأكيد من جهة الخادم، وإعادة المحاولة بأمان، والاسترداد، والمطابقة، والاختبار، وتنطبق على البطاقات والمحافظ الإلكترونية والتحويلات البنكية عبر رمز QR على حد سواء.

شاشة النجاح ليست تأكيدًا

بعد الدفع يعود العميل إلى موقعك أو تطبيقك، وغالبًا مع معاملات مثل ?status=success&order=1042. واعتبار ذلك دليلًا يخذلك من ثلاث جهات:

  • يستطيع أي شخص تعديله. تغيير failed إلى success في المتصفح لا يستغرق سوى ثوانٍ.
  • قد لا يُحمَّل أبدًا. يُغلق العميل التبويب، أو تنقطع الشبكة، أو لا يعود تطبيق البنك إلى تطبيقك، فينجح الدفع دون أن يعلم خادمك بذلك.
  • قد يصل قبل المال. بعض وسائل الدفع، وخاصة التحويلات البنكية، تبقى معلّقة بعد أن ينهي العميل خطواته.

ينبغي أن تعرض صفحة العودة عبارة «جارٍ تأكيد الدفع» وأن تستعلم من خادمك أنت، والخادم لا يثق إلا بالمصادر الموثّقة. ولا يقرّر جانب العميل أبدًا أن الطلب مدفوع.

حالات عملية الدفع

صمّم نموذجًا صريحًا لعملية الدفع بدلًا من علَم paid واحد:

  • أُنشئت: سُجّلت لدى المزوّد، ولم يدفع العميل بعد.
  • معلّقة: تصرّف العميل أو التحويل جارٍ، والنتيجة ليست نهائية.
  • ناجحة: أكّد المزوّد وصول الأموال.
  • فاشلة: رُفضت أو أُلغيت أو حُظرت.
  • منتهية الصلاحية: انقضت مهلة الدفع دون نتيجة.
  • مستردّة جزئيًا ومستردّة كليًا: أُعيد المال بعد النجاح، جزئيًا أو كليًا.

قد تضيف البطاقات حالة «مُفوَّضة ولم تُحصَّل بعد»، ولاحقًا النزاعات (الاعتراض على العملية). اكتب الانتقالات المسموح بها في الشيفرة: يمكن للمُنشأة أن تصبح معلّقة، ويمكن للمُنشأة أو المعلّقة أن تصبح ناجحة أو فاشلة أو منتهية الصلاحية، ويمكن للناجحة أن تصبح مستردّة جزئيًا أو كليًا، ويمكن أن يُستردّ مبلغ إضافي من المستردّة جزئيًا، ولا شيء يعود إلى «أُنشئت» أو «معلّقة». وأي تغيير آخر إما خطأ برمجي وإما حالة تستدعي مراجعة بشرية.

أكّد من جهة الخادم ومن مصدر يمكن التحقق منه

هناك مصدران موثوقان، والتكاملات المتينة تستخدم كليهما.

Webhook موقَّع. يستدعي المزوّد نقطة النهاية لديك عند وقوع حدث ما، ويوقّع معظم المزوّدين كل طلب بسرّ مشترك بينك وبينهم: عادةً HMAC-SHA256 على جسم الطلب الخام، وكثيرًا مع طابع زمني. على المعالج لديك أن:

  1. يقرأ جسم الطلب الخام كما وصل تمامًا. فتحليل JSON ثم إعادة تسلسله قد يغيّر المسافات أو رموز الهروب (escaping) أو ترتيب المفاتيح، فلا يعود التوقيع مطابقًا.
  2. يحسب HMAC ويقارنه بالترويسة مقارنةً ثابتة الزمن. فالمقارنة العادية للنصوص تتوقف عند أول حرف مختلف، وقد يكشف فرق التوقيت هذا معلومات عن التوقيع الصحيح.
  3. يرفض الطوابع الزمنية الواقعة خارج نافذة قصيرة، وكثيرًا ما تكون خمس دقائق، كي لا يمكن لاحقًا إعادة إرسال طلب اعتُرض؛ أما إعادة الإرسال داخل النافذة فيكشفها التحقق من معرّف الحدث.
  4. يطابق المبلغ والعملة ومرجع الطلب مع الطلب الذي أنشأته. فالتوقيع الصحيح يثبت مَن أرسل الرسالة، لا أن المبلغ الصحيح دُفع للطلب الصحيح. خزّن المبالغ أعدادًا صحيحة بأصغر وحدة في العملة، لا أعدادًا بفاصلة عائمة.

واجهة API لدى المزوّد. يستعلم خادمك عن عملية الدفع بمعرّفها مستخدمًا مفتاحك السري. وهذا يعوّض أي Webhook متأخر أو مفقود، بل إن بعض الفرق تعامل كل Webhook كمجرد إشارة لجلب الحالة الحالية.

تبقى مفاتيح API وأسرار Webhook على الخادم، خارج التطبيق وخارج المستودع، ويجب أن يمكن تدويرها دون توقف الخدمة.

عدم التأثر بالتكرار (Idempotency): الحدث نفسه مرتين لا يغيّر شيئًا

يسلّم معظم المزوّدين أحداث Webhook «مرة واحدة على الأقل»: إذا انتهت مهلة نقطة النهاية لديك أو أعادت خطأ، يُرسَل الحدث من جديد، وربما مرات عدة. فالتكرار أمر طبيعي، ولذلك يجب أن تكون المعالجة آمنة التكرار (idempotent)، أي أن تعطي النتيجة نفسها مهما تكررت.

  • أزِل التكرار بمعرّف الحدث. خزّن معرّفات الأحداث المعالَجة مع قيد تفرّد (unique constraint)، فلا يغيّر التسليم المكرّر شيئًا.
  • معاملة واحدة وتحديث واحد. سجّل معرّف الحدث وغيّر حالة الطلب في معاملة قاعدة بيانات واحدة؛ فإن فشل أي شيء تراجع الاثنان معًا، وبدأت إعادة المحاولة من حالة نظيفة. واجعل التحديث مشروطًا (WHERE status = 'pending')، حتى إذا وصل Webhook واستعلام API في اللحظة نفسها لا يُعالَج الطلب إلا مرة واحدة.
  • مفاتيح Idempotency عند إنشاء المدفوعات والاستردادات. إن كان المزوّد يدعمها، فاشتقّ المفتاح من معرّف محاولة الدفع لديك، وعندها تحصل إعادة المحاولة بعد انتهاء المهلة على النتيجة الأصلية بدل خصم المبلغ مرتين. وإن لم يدعمها، فاحفظ سجلك أولًا بمرجع فريد، وابحث عنه قبل أي إعادة محاولة.
  • أحداث بترتيب غير متوقع. ترتيب التسليم غير مضمون عمومًا، وقد يصل حدث النجاح بعد حدث الاسترداد. طبّق قواعد الانتقال لديك بدل الاعتماد على آخر حدث وصل، واجلب الحالة الحالية عند الشك.
  • التراجع الأُسّي. أعد المحاولة عند انتهاء المهلة وأخطاء الاتصال والاستجابات 429 و5xx، مع تراجع أُسّي وتذبذب عشوائي (jitter) وحدّ أقصى لعدد المحاولات. ولا تُعد المحاولة عند أخطاء التحقق من صحة البيانات.
  • انتهاء المهلة يعني «غير معروف» لا «فشل». ربما خُصم المبلغ فعلًا؛ احسم الأمر بالاستعلام.
  • انتهاء الصلاحية بجدول زمني. تبحث مهمة مجدولة عن المدفوعات التي ما زالت معلّقة بعد انقضاء مهلتها، وتتحقق لدى المزوّد، وعندئذ فقط تعلّمها منتهية الصلاحية. وأي نجاح يصل بعد انتهاء الصلاحية، وهذا يحدث مع التحويلات البنكية، يُحال إلى المراجعة أو يُسترد وفق قاعدة متفق عليها مسبقًا.

استجب لأحداث Webhook بسرعة: خزّن، ثم ثبّت المعاملة (commit)، ثم أعد 2xx، وضع الأعمال البطيئة مثل رسائل البريد الإلكتروني والشحن في طابور. فالمعالج البطيء يسبّب انتهاء المهلة، وانتهاء المهلة يسبّب مزيدًا من التكرار.

كيف يبدو ذلك في الشيفرة

معالج مصغّر بلغة TypeScript يعمل على Node.js وPostgreSQL. تختلف أسماء الترويسات وترميز التوقيع والنص المُوقَّع من مزوّد إلى آخر، لكن البنية تبقى نفسها.

TypeScript
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";

const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app

export async function handlePaymentWebhook(req: Request): Promise<Response> {
  const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
  const timestamp = req.headers.get("x-signature-timestamp") ?? "";
  const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
  const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
  if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
    return new Response("invalid signature", { status: 400 });
  }
  const event = JSON.parse(raw.toString("utf8"));
  const db = await pool.connect();
  try {
    await db.query("BEGIN");
    // event_id is the primary key: a repeated delivery inserts nothing.
    const inserted = await db.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
    if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
      // Only pending -> paid, and only if amount and currency match the order.
      const paid = await db.query(
        `UPDATE orders SET status = 'paid', paid_at = now()
          WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
        [event.data.order_id, event.data.amount, event.data.currency]);
      if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
    }
    await db.query("COMMIT");
    return new Response("ok");
  } catch {
    await db.query("ROLLBACK");
    return new Response("retry later", { status: 500 }); // the provider retries
  } finally {
    db.release();
  }
}

إذا لم يطابق أي طلب معلّق (لأنه دُفع بالفعل، أو انتهت صلاحيته، أو اختلف المبلغ)، يذهب الحدث إلى جدول المراجعة بدل أن يختفي.

الاسترداد والمطابقة وسجل التدقيق

الاستردادات سجلات مستقلة مرتبطة بعملية الدفع ولها حالاتها الخاصة، فالاسترداد أيضًا قد يكون معلّقًا أو يفشل. ويجب ألا يتجاوز مجموع الاستردادات الجزئية المبلغ المُحصَّل. أرسل طلبات الاسترداد بمفاتيح Idempotency، ولا تغيّر حالة الطلب إلا بعد تأكيد المزوّد.

المطابقة اليومية تلتقط ما يفوت كل ما سبق. حمّل تقرير المعاملات أو التسويات من المزوّد عن اليوم السابق، وطابق كل سطر مع سجلاتك بمعرّف المعاملة لدى المزوّد، ثم قارن المبلغ والعملة والحالة. أكثر الفروق شيوعًا:

  • مدفوع لدى المزوّد ومعلّق في نظامك: Webhook ضاع، وعميل دفع وما زال ينتظر.
  • مدفوع في نظامك ومجهول لدى المزوّد: خطأ برمجي أو إساءة استخدام، وهو النوع الأكثر إلحاحًا.
  • مبلغ أو حالة مختلفة: استرداد جزئي لم يُسجَّل، أو خلط بين المبالغ الإجمالية والرسوم وصافي التسوية.

تذهب الفروق إلى طابور للفروقات له مسؤول وملاحظة حل، ولا يُصلَح شيء بصمت. وانتبه إلى وقت إقفال التقرير: فالدفعة التي تتم قرب منتصف الليل قد تُسجَّل في يومين مختلفين لدى الطرفين.

سجل التدقيق. احتفظ بكل Webhook خام كما وصل، مع ترويساته ونتيجة التحقق، لتتمكن من إعادة تشغيله، واحتفظ بسجل لتغييرات الحالة يُضاف إليه فقط ولا يُعدَّل (append-only): من أي حالة، وإلى أي حالة، ومتى، وبسبب أي حدث أو مهمة أو شخص. لا تسجّل الأسرار أو أرقام البطاقات كاملة أبدًا؛ ومع صفحة دفع يستضيفها المزوّد أو حقول دفع مضمّنة منه، لا تصل أرقام البطاقات إلى خوادمك أصلًا.

التنبيهات يجب أن تنطلق عند ارتفاع مفاجئ في إخفاقات التحقق من التوقيع، وأخطاء المعالجة، والمدفوعات العالقة في حالة «معلّقة»، وفشل الاستردادات، وفروق المطابقة، وانخفاض معدل النجاح.

اختبر حالات الفشل، لا المسار السعيد وحده

استخدم بيئة الاختبار (sandbox) أو وضع الاختبار لدى المزوّد مع مفاتيح اختبار، ثم:

  • أعد تشغيل أحداث Webhook. احفظ أحداثًا حقيقية من بيئة الاختبار كبيانات اختبار ثابتة؛ أرسل الحدث نفسه مرتين، واعكس الترتيب، وغيّر بايتًا واحدًا في الجسم، واستخدم طابعًا زمنيًا قديمًا.
  • احقن الأعطال. أوقف العملية بعد تثبيت المعاملة وقبل استجابة 2xx: سيعيد المزوّد الإرسال، ولا يجوز أن يحدث أي شيء مرتين. افصل قاعدة البيانات دقيقة واحدة. أضف تأخيرًا إلى الاستدعاءات الموجّهة إلى المزوّد حتى تنطلق مهلات الانتظار لديك.
  • أسئ استخدام جانب العميل. اضغط «ادفع» مرتين متتاليتين، وأغلق المتصفح قبل إعادة التوجيه، وافتح رابط العودة بمعاملات مزوّرة.

قائمة التحقق قبل الإطلاق

  1. لا تصبح حالة الطلب «مدفوع» إلا عبر Webhook موثَّق أو استعلام API من جهة الخادم.
  2. يُتحقق من التواقيع على جسم الطلب الخام بمقارنة ثابتة الزمن، وتُرفض الطوابع الزمنية القديمة.
  3. يُطابَق المبلغ والعملة ومرجع الطلب مع الطلب.
  4. معرّفات الأحداث فريدة، والتسليمات المكرّرة تُعيد 2xx دون آثار جانبية.
  5. يُثبَّت سجل الحدث وتغيير الحالة في معاملة واحدة، مع تحديث مشروط.
  6. يستخدم إنشاء المدفوعات والاستردادات مفاتيح Idempotency أو بحثًا بمرجعك الخاص.
  7. الانتقالات معرّفة في الشيفرة، والأحداث المتأخرة لا تعيد الطلب إلى الوراء.
  8. تستجيب نقطة نهاية Webhook ضمن مهلة المزوّد، والأعمال البطيئة تمر عبر طابور.
  9. للاستدعاءات الخارجية مهلات انتظار وإعادة محاولات محدودة مع تراجع وتذبذب عشوائي.
  10. تنتهي صلاحية المدفوعات المعلّقة بجدول زمني بعد التحقق من حالتها، وللنجاح المتأخر مسار محدد.
  11. لا يمكن أن تتجاوز الاستردادات الجزئية المبلغ المُحصَّل.
  12. تعمل المطابقة يوميًا، ولكل فرق مسؤول.
  13. تُحفظ أحداث Webhook الخام وسجل الحالات، ولا تحتوي سجلات التشغيل (logs) على أسرار أو أرقام بطاقات كاملة.
  14. تغطي التنبيهات إخفاقات التوقيع، وأخطاء المعالجة، والمدفوعات العالقة، وفروق المطابقة.

تعمل silvercloud كفريق تطوير خارجي. نبني هذه الطبقة في تطبيقات الشركات الشريكة ومواقعها، من صفحة إتمام الشراء وأحداث Webhook إلى الاسترداد والمطابقة، ونبني أنظمة بوابات الدفع وفق متطلبات كل شريك، ثم نسلّم العمل ليتولى فريقه تشغيله. إذا كنت تخطط لتكامل دفع، فأرسل إلينا موجزًا عبر silvercloud.city.

أرسل موجزًا عن تكامل الدفع