Single wallet kumpara sa transfer wallet

Sa isang sulyap

Single wallet (seamless)

Sa single wallet (seamless) model, ang iyong sistema ang wallet. Kapag naglagay ng taya ang player, tatawagin ng SSG API ang iyong callback endpoint, babaguhin mo ang balance sa sarili mong ledger, at sasagot ka ng bagong balance. Hindi kailanman lalabas sa iyong database ang pondo.

Call flow

1. Launch: humihingi ang iyong backend sa SSG ng game URL gamit ang player ID at session token.
2. Taya: sa bawat round, tatawag ang SSG ng debit na may natatanging txId. Susuriin mo ang pondo, isusulat ang ledger row at ibabalik ang bagong balance.
3. Panalo: tatawag ang SSG ng credit na may payout (maaaring zero) para sa parehong round.
4. Failure: kung mag-timeout ang isang call, magre-retry ang SSG gamit ang parehong txId, at pagkatapos ng retry limit ay magpapadala ito ng rollback.

Mga callback method (ilustratibo)

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

Mga patakarang dapat sundin ng iyong wallet service

Idempotency

Ang paulit-ulit na debit o credit na may parehong txId ay dapat magbalik ng orihinal na resulta at hindi dapat maglipat muli ng pera. Tiyakin ito gamit ang unique index sa txId.

Atomic na pagsulat sa ledger

Gawin sa iisang database transaction ang pagsuri ng balance, pagpasok ng ledger row at pag-update ng balance, upang hindi kailanman ma-overdraw ng dalawang magkasabay na taya.

Rollback bago ang debit

Maaaring dumating ang rollback para sa txId na hindi mo pa nakikita dahil nag-timeout ang orihinal na debit. Mag-imbak ng tombstone upang tanggihan ang huling dumating na debit na may parehong txId.

Latency budget

Targetin ang p99 na mas mababa sa 500 ms kasama ang network. Panatilihing isang indexed read at isang write lang ang callback path, at huwag isama rito ang mga reporting query.

Format ng halaga

Ituring ang mga halaga bilang decimal string o integer minor unit. Huwag gumamit ng floating point, at i-validate ang currency laban sa account ng player.

Mga bonus at free spin

Ang free spin ay isang debit na 0 na sinusundan ng credit ng panalo. Ihiwalay ang promotional balance sa cash balance sa iyong ledger.

Seguridad

I-verify ang HMAC-SHA256 signature sa canonical request, tanggihan ang mga lumang timestamp, i-allowlist ang mga source IP ng SSG, at hingin ang TLS 1.2 o mas mataas.

Reconciliation

Ihambing ang mga daily round report mula sa SSG sa iyong ledger gamit ang roundId. Ang mga pagkakaiba ay nagpapahiwatig ng mga na-miss na callback o rollback.

Transfer wallet

Sa transfer wallet model, ang provider ang may hawak ng game balance ng bawat player. Inililipat ng iyong backend ang pondo papasok bago maglaro at palabas pagkatapos. Habang naglalaro, walang callback sa iyong system, kaya outbound REST call lang ang kailangan mo.

Call flow

1. Transfer in: tinatawag ng iyong backend ang transferIn gamit ang natatanging txId at ang halaga. Ang resulta ay PENDING o SUCCESS.
2. Paglalaro: ilunsad ang laro. Lahat ng taya at panalo ay nagbabago lang sa balance sa panig ng provider at walang callback sa iyo.
3. Transfer out: kapag umalis ang player, tawagin ang transferOut para sa buong balance at i-credit ito pabalik sa sarili mong ledger kapag SUCCESS.
4. Hindi alam ang resulta: kung nag-timeout ang transfer call, i-query ang getTransferStatus gamit ang parehong txId bago gumawa ng anumang iba.

Mga API method (halimbawa)

Mga panuntunang dapat sundin ng iyong backend

Isang txId bawat intent

Gumawa ng txId bago ang unang call at gamitin ito muli sa bawat retry. Huwag gumawa ng bagong txId hangga't hindi alam ang status ng nauna.

I-debit muna ang iyong ledger

Para sa transfer in, i-reserve ang halaga sa iyong ledger bago tawagin ang SSG, pagkatapos ay i-confirm o i-release ito kapag final na ang status.

I-sweep ang mga naiwang balance

Magpatakbo ng job na naghahanap ng mga player na may game balance at walang aktibong session, saka ito itransfer out. Sakop nito ang mga player na nagsara ng browser sa kalagitnaan ng session.

Wagering at mga report

Dahil hindi mo nakikita ang mga taya nang live, kalkulahin ang turnover, bonus wagering at risk limit mula sa mga round report na kinuha sa SSG, hindi mula sa mga callback.

Reconciliation

I-match ang bawat transfer in at out sa mga record ng SSG gamit ang txId, at mag-alert sa anumang PENDING na lampas sa iyong timeout.

Seguridad

I-sign ang mga request gamit ang HMAC-SHA256, tumawag lang sa TLS 1.2 o mas mataas, itago ang mga API key sa secret store, at limitahan kung aling mga server mo ang puwedeng tumawag sa SSG.

Mga failure scenario

Alin ang dapat mong piliin

Maraming operator ang nagsisimula sa transfer wallet para mag-go live, saka lumilipat sa single wallet kapag handa na ang sarili nilang wallet service. Itanong sa amin kung paano isinasagawa nang paunti-unti ang paglipat.

Integration checklist

• Unique index sa txId at idempotent handler para sa bawat call na gumagalaw ng pera
• HMAC signature check, timestamp tolerance at IP allowlist
• Decimal-safe na mga halaga at currency validation
• Mga test sa timeout, retry at rollback sa sandbox, kasama ang late retry
• Daily reconciliation job gamit ang roundId (single) o txId (transfer)
• Monitoring at mga alert: callback latency, error rate, pending transfer, naiwang balance