المحفظة الموحدة مقابل محفظة التحويل

نظرة سريعة

المحفظة الموحدة (Seamless)

في نموذج المحفظة الموحدة (Seamless) يكون نظامك هو المحفظة. عندما يضع اللاعب رهانًا تستدعي SSG API نقطة الاستدعاء لديك، فتغيّر الرصيد في دفترك وتجيب بالرصيد الجديد. لا تغادر الأموال قاعدة بياناتك أبدًا.

مسار الطلبات

1. الإطلاق: تطلب الخلفية لديك من SSG رابط لعبة مع معرّف اللاعب ورمز الجلسة.
2. الرهان: لكل جولة تستدعي SSG طلب debit بمعرّف txId فريد. تتحقّق من الرصيد، وتكتب سجل الدفتر، وتعيد الرصيد الجديد.
3. الربح: تستدعي SSG طلب credit بمبلغ الدفع (قد يكون صفرًا) للجولة نفسها.
4. الفشل: إذا انتهت مهلة طلب تعيد SSG المحاولة بمعرّف txId نفسه، وبعد حد إعادة المحاولة ترسل rollback.

طرق الاستدعاء (توضيحية)

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

قواعد يجب أن تتبعها خدمة المحفظة

تكرار الطلبات الآمن

طلب debit أو credit مكرّر بمعرّف txId نفسه يجب أن يعيد النتيجة الأصلية دون تحريك المال مجددًا. افرض ذلك بفهرس فريد على txId.

كتابة ذرّية في الدفتر

تحقّق من الرصيد، وأدرج سجل الدفتر، وحدّث الرصيد في معاملة قاعدة بيانات واحدة، فلا يمكن لرهانين متزامنين أن يتجاوزا الرصيد.

تراجع قبل الخصم

قد يصل rollback لمعرّف txId لم تره قط لأن طلب الخصم الأصلي انتهت مهلته. خزّن علامة حذف ليُرفض أي debit متأخر بذلك المعرّف.

ميزانية زمن الاستجابة

استهدف p99 أقل من 500 ملّي ثانية شاملًا الشبكة. اجعل مسار الاستدعاء قراءة مفهرسة واحدة وكتابة واحدة، وأبعد استعلامات التقارير عنه.

صيغة المبالغ

تعامل مع المبالغ كنصوص عشرية أو وحدات صغرى صحيحة. لا تستخدم الفاصلة العائمة أبدًا، وتحقّق من العملة مقابل حساب اللاعب.

المكافآت واللفات المجانية

اللفة المجانية خصم بقيمة 0 يتبعه إضافة بقيمة الربح. افصل أرصدة العروض الترويجية عن الرصيد النقدي في دفترك.

الأمان

تحقّق من توقيع HMAC-SHA256 على الطلب القانوني، وارفض الطوابع الزمنية القديمة، واسمح فقط بعناوين IP المصدر الخاصة بـ SSG، واشترط TLS 1.2 أو أعلى.

المطابقة

قارن تقارير الجولات اليومية من SSG بدفترك حسب roundId. تشير الفروق إلى استدعاءات أو تراجعات فائتة.

محفظة التحويل

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

مسار الطلبات

1. التحويل للداخل: تستدعي الخلفية لديك transferIn بمعرّف txId فريد والمبلغ. النتيجة PENDING أو SUCCESS.
2. اللعب: أطلق اللعبة. كل الرهانات والأرباح تغيّر الرصيد لدى المزوّد دون استدعاءات إليك.
3. التحويل للخارج: عندما يغادر اللاعب، استدعِ transferOut لكامل الرصيد وأضفه إلى دفترك عند SUCCESS.
4. نتيجة غير معروفة: إذا انتهت مهلة طلب تحويل، استعلم عبر getTransferStatus بمعرّف txId نفسه قبل أي إجراء آخر.

طرق API (توضيحية)

قواعد يجب أن تتبعها الخلفية لديك

معرّف txId واحد لكل عملية

أنشئ معرّف txId قبل الطلب الأول وأعد استخدامه في كل إعادة محاولة. لا تُنشئ معرّفًا جديدًا حتى تُعرف حالة السابق.

اخصم من دفترك أولًا

عند التحويل للداخل، احجز المبلغ في دفترك قبل استدعاء SSG، ثم أكّده أو حرّره عندما تصبح الحالة نهائية.

استرجع الأرصدة العالقة

شغّل مهمة تبحث عن اللاعبين الذين لديهم رصيد لعب دون جلسة نشطة، ثم تحوّله للخارج. يغطي ذلك اللاعبين الذين يغلقون المتصفح في منتصف الجلسة.

متطلبات الرهان والتقارير

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

المطابقة

طابق كل تحويل للداخل والخارج مع سجلات SSG حسب txId، ونبّه عند وجود أي PENDING أقدم من مهلتك.

الأمان

وقّع الطلبات بـ HMAC-SHA256، واتصل فقط عبر TLS 1.2 أو أعلى، واحفظ مفاتيح API في مخزن أسرار، وقيّد خوادمك المسموح لها بالاتصال بـ SSG.

سيناريوهات الأعطال

أيهما تختار

يبدأ كثير من المشغّلين بمحفظة التحويل للتشغيل، ثم ينتقلون إلى المحفظة الموحدة عندما تجهز خدمة محفظتهم. اسألنا كيف يتم الانتقال على مراحل.

قائمة تحقّق التكامل

• فهرس فريد على txId ومعالجات متكرّرة النتيجة لكل طلب يحرّك المال
• فحص توقيع HMAC وهامش للطابع الزمني وقائمة IP مسموح بها
• مبالغ آمنة عشريًا والتحقق من العملة
• اختبارات انتهاء المهلة وإعادة المحاولة والتراجع في بيئة الاختبار، بما فيها إعادة محاولة متأخرة
• مهمة مطابقة يومية حسب roundId (الموحدة) أو txId (التحويل)
• المراقبة والتنبيهات: زمن استجابة الاستدعاءات، ومعدل الأخطاء، والتحويلات المعلّقة، والأرصدة العالقة