Single wallet กับ Transfer wallet

ดูภาพรวม

Single wallet (seamless)

ในโมเดล single wallet (seamless) ระบบของคุณคือ wallet เมื่อผู้เล่นวางเดิมพัน SSG API จะเรียก callback endpoint ของคุณ คุณเปลี่ยนยอดคงเหลือใน ledger ของคุณเอง แล้วตอบกลับด้วยยอดคงเหลือใหม่ เงินไม่เคยออกจากฐานข้อมูลของคุณ

ลำดับการเรียก

1. เปิดเกม: backend ของคุณขอ URL เกมจาก SSG พร้อม player ID และ session token
2. เดิมพัน: ในแต่ละรอบ SSG เรียก debit พร้อม txId ที่ไม่ซ้ำ คุณตรวจสอบยอดเงิน บันทึกแถวใน ledger และส่งยอดคงเหลือใหม่กลับ
3. รางวัล: SSG เรียก credit พร้อมเงินรางวัล (อาจเป็นศูนย์) สำหรับรอบเดียวกัน
4. ข้อผิดพลาด: หากการเรียก timeout SSG จะลองใหม่ด้วย txId เดิม และเมื่อเกินจำนวนครั้งที่กำหนดจะส่ง rollback

เมธอด callback (ตัวอย่าง)

{
  "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

กฎที่บริการ wallet ของคุณต้องปฏิบัติตาม

Idempotency

หาก debit หรือ credit ที่มี txId เดียวกันถูกส่งซ้ำ ต้องส่งผลลัพธ์เดิมกลับและห้ามเคลื่อนไหวเงินซ้ำ บังคับใช้ด้วย unique index บน txId

การบันทึก ledger แบบ atomic

ตรวจสอบยอดเงิน เพิ่มแถวใน ledger และอัปเดตยอดคงเหลือภายในธุรกรรมฐานข้อมูลเดียว เพื่อไม่ให้เดิมพันที่เกิดพร้อมกันสองรายการทำให้ยอดติดลบได้

Rollback มาก่อน debit

อาจมี rollback มาถึงสำหรับ txId ที่คุณไม่เคยเห็น เพราะ debit ต้นฉบับ timeout ให้เก็บ tombstone ไว้ เพื่อปฏิเสธ debit ที่มาช้าซึ่งใช้ txId เดียวกัน

เป้าหมาย latency

ตั้งเป้า p99 ต่ำกว่า 500 ms รวมเวลาเครือข่าย โดยให้เส้นทาง callback ใช้ indexed read เพียง 1 ครั้งและ write 1 ครั้ง และแยก query สำหรับรายงานออกจากเส้นทางนี้

รูปแบบจำนวนเงิน

จัดการจำนวนเงินเป็น decimal string หรือเลขจำนวนเต็มในหน่วยย่อยสุด ห้ามใช้ floating point และต้องตรวจสอบสกุลเงินให้ตรงกับบัญชีผู้เล่น

โบนัสและฟรีสปิน

ฟรีสปินคือ debit จำนวน 0 ตามด้วย credit ของเงินรางวัล ควรแยกยอดโบนัสออกจากยอดเงินสดใน ledger ของคุณ

ความปลอดภัย

ตรวจสอบลายเซ็น HMAC-SHA256 ของ canonical request, ปฏิเสธ timestamp ที่หมดอายุ, อนุญาตเฉพาะ IP ต้นทางของ SSG (allowlist) และกำหนดให้ใช้ TLS 1.2 ขึ้นไป

การกระทบยอด

เปรียบเทียบรายงานรอบเกมรายวันจาก SSG กับ ledger ของคุณตาม roundId ความต่างมักเกิดจาก callback หรือ rollback ที่ตกหล่น

Transfer wallet

ในโมเดล transfer wallet ผู้ให้บริการเกมจะเก็บยอดเงินในเกมของผู้เล่นแต่ละราย ระบบหลังบ้านของคุณโอนเงินเข้าก่อนเล่นและโอนออกหลังเล่นเสร็จ ระหว่างเล่นจะไม่มี callback มายังระบบของคุณ จึงต้องใช้เพียงการเรียก REST ขาออกเท่านั้น

ลำดับการเรียก

1. โอนเข้า: ระบบหลังบ้านของคุณเรียก transferIn พร้อม txId ที่ไม่ซ้ำและจำนวนเงิน ผลลัพธ์คือ PENDING หรือ SUCCESS
2. เล่นเกม: เปิดเกม การเดิมพันและเงินรางวัลทั้งหมดจะเปลี่ยนแปลงเฉพาะยอดเงินฝั่งผู้ให้บริการเกม โดยไม่มี callback มาที่คุณ
3. โอนออก: เมื่อผู้เล่นออกจากเกม ให้เรียก transferOut สำหรับยอดคงเหลือทั้งหมด แล้วบันทึกคืนเข้า ledger ของคุณเมื่อได้ SUCCESS
4. ผลลัพธ์ไม่แน่ชัด: หากการเรียกโอนเงินเกิด timeout ให้ query getTransferStatus ด้วย txId เดิมก่อนทำอย่างอื่น

เมธอด API (ตัวอย่าง)

กฎที่ระบบหลังบ้านของคุณต้องปฏิบัติตาม

หนึ่ง txId ต่อหนึ่งรายการ

สร้าง txId ก่อนการเรียกครั้งแรกและใช้ซ้ำในทุกการ retry ห้ามสร้าง txId ใหม่จนกว่าจะทราบสถานะของรายการก่อนหน้า

หักยอดใน ledger ของคุณก่อน

สำหรับการโอนเข้า ให้กันยอดเงินใน ledger ของคุณก่อนเรียก SSG จากนั้นยืนยันหรือปล่อยยอดคืนเมื่อสถานะสิ้นสุด

เก็บกวาดยอดเงินตกค้าง

รันงานที่ค้นหาผู้เล่นซึ่งมียอดเงินในเกมแต่ไม่มี session ที่ใช้งานอยู่ แล้วโอนออก เพื่อรองรับผู้เล่นที่ปิดเบราว์เซอร์กลางคัน

เทิร์นโอเวอร์และรายงาน

เนื่องจากคุณไม่เห็นการเดิมพันแบบเรียลไทม์ ให้คำนวณเทิร์นโอเวอร์ เงื่อนไขการเดิมพันโบนัส และวงเงินความเสี่ยงจากรายงานรอบเกมที่ดึงจาก SSG ไม่ใช่จาก callback

การกระทบยอด

จับคู่ทุกรายการโอนเข้าและโอนออกกับบันทึกของ SSG ตาม txId และแจ้งเตือนเมื่อมี PENDING ที่เกินเวลา timeout ของคุณ

ความปลอดภัย

ลงลายเซ็นคำขอด้วย HMAC-SHA256 เรียกผ่าน TLS 1.2 ขึ้นไปเท่านั้น เก็บ API key ไว้ใน secret store และจำกัดว่าเซิร์ฟเวอร์ใดของคุณเรียก SSG ได้

สถานการณ์ข้อผิดพลาด

ควรเลือกแบบไหน

ผู้ให้บริการหลายรายเริ่มจาก transfer wallet เพื่อเปิดตัว แล้วย้ายไป single wallet เมื่อบริการ wallet ของตนพร้อม สอบถามเราได้ว่าการสลับทำเป็นขั้นตอนอย่างไร

เช็กลิสต์การเชื่อมต่อ

• unique index บน txId และ handler แบบ idempotent สำหรับทุกการเรียกที่เกี่ยวกับการเคลื่อนย้ายเงิน
• การตรวจสอบลายเซ็น HMAC, ช่วง timestamp ที่ยอมรับได้ และ IP allowlist
• การจัดการจำนวนเงินแบบ decimal-safe และการตรวจสอบสกุลเงิน
• ทดสอบ timeout, retry และ rollback ใน sandbox รวมถึง retry ที่มาช้า
• งานกระทบยอดรายวันตาม roundId (single) หรือ txId (transfer)
• การมอนิเตอร์และแจ้งเตือน: callback latency, อัตราข้อผิดพลาด, รายการโอนที่ค้างอยู่, ยอดเงินตกค้าง