Wallet tunggal vs wallet transfer

Sekilas

Single wallet (seamless)

Pada model single wallet (seamless), sistem Anda adalah wallet-nya. Saat pemain memasang taruhan, SSG API memanggil endpoint callback Anda, Anda mengubah saldo di ledger Anda sendiri, lalu menjawab dengan saldo baru. Tidak ada dana yang keluar dari database Anda.

Alur panggilan

1. Peluncuran: backend Anda meminta URL game dari SSG dengan ID pemain dan token sesi.
2. Taruhan: untuk setiap ronde SSG memanggil debit dengan txId unik. Anda memeriksa dana, menulis baris ledger, dan mengembalikan saldo baru.
3. Kemenangan: SSG memanggil credit dengan nilai pembayaran (bisa nol) untuk ronde yang sama.
4. Kegagalan: jika panggilan timeout, SSG mencoba ulang dengan txId yang sama, dan setelah batas percobaan ulang tercapai, SSG mengirim rollback.

Metode callback (ilustratif)

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

Aturan yang harus dipatuhi layanan wallet Anda

Idempotensi

Debit atau credit berulang dengan txId yang sama harus mengembalikan hasil asli dan tidak boleh memindahkan dana lagi. Pastikan dengan unique index pada txId.

Penulisan ledger atomik

Periksa saldo, sisipkan baris ledger, dan perbarui saldo dalam satu transaksi database, sehingga dua taruhan bersamaan tidak pernah bisa menyebabkan saldo minus.

Rollback sebelum debit

Rollback dapat tiba untuk txId yang belum pernah Anda terima karena debit aslinya timeout. Simpan tombstone agar debit terlambat dengan txId tersebut ditolak.

Anggaran latensi

Targetkan p99 di bawah 500 ms termasuk jaringan. Batasi jalur callback pada satu pembacaan terindeks dan satu penulisan, dan jauhkan query pelaporan dari jalur ini.

Format nominal

Perlakukan nominal sebagai string desimal atau satuan terkecil berupa integer. Jangan pernah gunakan floating point, dan validasi mata uang terhadap akun pemain.

Bonus dan free spin

Free spin adalah debit senilai 0 yang diikuti credit sebesar kemenangan. Pisahkan saldo promosi dari saldo tunai di ledger Anda.

Keamanan

Verifikasi tanda tangan HMAC-SHA256 atas canonical request, tolak timestamp kedaluwarsa, daftarkan IP sumber SSG dalam allowlist, dan wajibkan TLS 1.2 atau lebih tinggi.

Rekonsiliasi

Bandingkan laporan round harian dari SSG dengan ledger Anda berdasarkan roundId. Selisih biasanya menunjukkan callback atau rollback yang terlewat.

Transfer wallet

Pada model transfer wallet, provider menyimpan saldo game untuk setiap pemain. Backend Anda memindahkan dana masuk sebelum bermain dan keluar sesudahnya. Selama bermain tidak ada callback ke sistem Anda, sehingga Anda hanya memerlukan panggilan REST outbound.

Alur panggilan

1. Transfer masuk: backend Anda memanggil transferIn dengan txId unik dan nominal. Hasilnya PENDING atau SUCCESS.
2. Bermain: luncurkan game. Semua taruhan dan kemenangan hanya mengubah saldo di sisi provider tanpa callback ke Anda.
3. Transfer keluar: saat pemain keluar, panggil transferOut untuk seluruh saldo dan kreditkan kembali ke ledger Anda saat SUCCESS.
4. Hasil tidak diketahui: jika panggilan transfer timeout, query getTransferStatus dengan txId yang sama sebelum melakukan tindakan lain.

Metode API (ilustrasi)

Aturan yang harus dipatuhi backend Anda

Satu txId per intent

Buat txId sebelum panggilan pertama dan gunakan kembali untuk setiap retry. Jangan buat txId baru sebelum status txId sebelumnya diketahui.

Debit ledger Anda lebih dulu

Untuk transfer masuk, cadangkan nominal di ledger Anda sebelum memanggil SSG, lalu konfirmasi atau lepaskan saat status sudah final.

Bersihkan saldo tertahan

Jalankan job yang mencari pemain dengan saldo game tanpa sesi aktif, lalu transfer keluar saldonya. Ini mencakup pemain yang menutup browser di tengah sesi.

Wagering dan laporan

Karena Anda tidak melihat taruhan secara langsung, hitung turnover, wagering bonus, dan batas risiko dari laporan round yang diambil dari SSG, bukan dari callback.

Rekonsiliasi

Cocokkan setiap transfer masuk dan keluar dengan catatan SSG berdasarkan txId, dan beri alert untuk PENDING yang melebihi batas timeout Anda.

Keamanan

Tandatangani request dengan HMAC-SHA256, panggil hanya melalui TLS 1.2 atau lebih tinggi, simpan API key di secret store, dan batasi server Anda yang boleh memanggil SSG.

Skenario kegagalan

Mana yang harus Anda pilih

Banyak operator memulai dengan transfer wallet untuk go live, lalu beralih ke single wallet setelah layanan wallet mereka siap. Tanyakan kepada kami bagaimana peralihan dilakukan secara bertahap.

Checklist integrasi

• Unique index pada txId dan handler idempoten untuk setiap panggilan yang memindahkan dana
• Pemeriksaan tanda tangan HMAC, toleransi timestamp, dan IP allowlist
• Nominal aman desimal dan validasi mata uang
• Uji timeout, retry, dan rollback di sandbox, termasuk retry yang terlambat
• Job rekonsiliasi harian berdasarkan roundId (single) atau txId (transfer)
• Pemantauan dan alert: latensi callback, tingkat error, transfer pending, saldo tertahan