Product API Ví đơn và ví chuyển khoản
Ví đơn và ví chuyển khoản
So sánh kỹ thuật hai mô hình ví dùng để kết nối số dư người chơi của nhà vận hành với API game casino: ai giữ tiền, lệnh gọi nào đi qua mạng khi đặt cược, khôi phục lỗi thế nào, và bạn phải xây gì ở phía mình.
Tóm tắt
| Khía cạnh | Ví đơn | Ví chuyển khoản |
|---|---|---|
| Nơi giữ số dư | Cơ sở dữ liệu của bạn giữ số dư duy nhất. Nhà cung cấp không bao giờ giữ tiền người chơi. | Nhà cung cấp giữ một số dư game riêng. Tiền vào và ra bằng lệnh chuyển. |
| Lệnh gọi khi đặt cược | Mỗi lần cược và thắng đều kích hoạt một callback server-to-server tới bạn (balance, debit, credit, rollback). | Không có. Game chạy trên số dư phía nhà cung cấp. Chỉ có lệnh gọi khi chuyển vào và chuyển ra. |
| Yêu cầu khả dụng | Endpoint ví của bạn phải trả lời mọi callback, thường trong vài trăm mili giây. Nếu chúng ngừng, game dừng. | Chỉ cần khi chuyển tiền. Các ván vẫn chạy nếu hệ thống của bạn tạm ngoại tuyến. |
| Mô hình nhất quán | Sổ cái của bạn là nguồn dữ liệu thời gian thực. Chỉ các ván game cần đối soát, không phải số dư. | Hai sổ cái chỉ khớp nhau tại thời điểm chuyển tiền. Cần đối soát ở cấp lệnh chuyển. |
| Khôi phục lỗi | Timeout được xử lý bằng gửi lại idempotent và lệnh rollback theo mã giao dịch. | Lệnh chuyển có hai pha: pending, rồi success hoặc failed. Truy vấn trạng thái giải quyết kết quả chưa rõ. |
| Khối lượng tích hợp | Cao hơn. Bạn xây và vận hành một dịch vụ callback độ trễ thấp, có idempotency và sổ cái. | Thấp hơn. Bạn gọi ba hoặc bốn endpoint REST, không có lưu lượng chiều vào phải bảo vệ hay mở rộng. |
| Trải nghiệm người chơi | Một số dư, không có bước chuyển. Phù hợp với khuyến mãi, chơi xuyên sản phẩm và hiển thị số dư trực tiếp. | Tiền được chuyển vào trước khi chơi và ra sau đó. Thêm độ trễ ngắn và rủi ro số dư bị kẹt nếu người chơi rời giữa phiên. |
| Phù hợp với | Nhà vận hành có ví hoặc nền tảng riêng và kiểm soát chặt tiền và khuyến mãi. | Nhà vận hành muốn ra mắt nhanh hoặc chưa có dịch vụ ví thời gian thực. |
Ví đơn (seamless)
Trong mô hình ví đơn (seamless), hệ thống của bạn chính là ví. Khi người chơi đặt cược, API SSG gọi endpoint callback của bạn, bạn thay đổi số dư trong sổ cái của mình và trả về số dư mới. Tiền không bao giờ rời khỏi cơ sở dữ liệu của bạn.
Luồng gọi
- Khởi chạy: backend của bạn xin SSG URL game kèm ID người chơi và token phiên.
- Cược: với mỗi ván, SSG gọi debit với một txId duy nhất. Bạn kiểm tra số dư, ghi dòng sổ cái và trả về số dư mới.
- Thắng: SSG gọi credit với tiền thưởng (có thể bằng 0) cho cùng ván đó.
- Lỗi: nếu lệnh gọi bị timeout, SSG gửi lại với cùng txId, và sau giới hạn gửi lại thì gửi rollback.
Phương thức callback (minh họa)
| Phương thức | Mục đích | Trường chính | Idempotent |
|---|---|---|---|
balance | Trả về số dư hiện tại của người chơi. | playerId, currency | Có (chỉ đọc) |
debit | Đặt cược: trừ số tiền. | playerId, txId, roundId, gameId, amount, currency | Theo txId |
credit | Trả thưởng: cộng số tiền. | playerId, txId, roundId, amount, currency | Theo txId |
rollback | Hủy một debit hoặc credit trước đó sau khi có lỗi. | txId, refTxId | Theo txId |
Ví dụ yêu cầu debit
{
"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))"
}Ví dụ phản hồi
{
"status": "OK",
"txId": "tx_20261007_000184",
"balance": "97.50",
"currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
// DUPLICATE_TX (return original result), INTERNAL_ERRORQuy tắc dịch vụ ví của bạn phải tuân theo
- Idempotency
- Một debit hoặc credit lặp lại với cùng txId phải trả về kết quả ban đầu và không được chuyển tiền lần nữa. Thực thi bằng chỉ mục duy nhất trên txId.
- Ghi sổ cái nguyên tử
- Kiểm tra số dư, thêm dòng sổ cái và cập nhật số dư trong một giao dịch cơ sở dữ liệu, để hai lệnh cược đồng thời không bao giờ làm âm số dư.
- Rollback trước debit
- Rollback có thể đến cho một txId bạn chưa từng thấy vì debit gốc bị timeout. Lưu một bản ghi đánh dấu để debit đến muộn với txId đó bị từ chối.
- Ngân sách độ trễ
- Nhắm p99 dưới 500 ms kể cả mạng. Giữ đường callback ở mức một lần đọc có chỉ mục và một lần ghi, và tách truy vấn báo cáo ra.
- Định dạng tiền
- Xử lý số tiền dạng chuỗi thập phân hoặc số nguyên đơn vị nhỏ. Không bao giờ dùng số thực dấu phẩy động, và kiểm tra tiền tệ với tài khoản người chơi.
- Khuyến mãi và free spin
- Một free spin là debit 0 theo sau là credit tiền thắng. Tách số dư khuyến mãi khỏi số dư tiền mặt trong sổ cái.
- Bảo mật
- Xác minh chữ ký HMAC-SHA256 trên yêu cầu chuẩn hóa, từ chối timestamp cũ, chỉ cho phép IP nguồn của SSG, và yêu cầu TLS 1.2 trở lên.
- Đối soát
- So sánh báo cáo ván hằng ngày từ SSG với sổ cái của bạn theo roundId. Chênh lệch cho thấy callback hoặc rollback bị bỏ sót.
Ví chuyển khoản
Trong mô hình ví chuyển khoản, nhà cung cấp giữ số dư game cho từng người chơi. Backend của bạn chuyển tiền vào trước khi chơi và ra sau đó. Khi chơi không có callback tới hệ thống của bạn, nên bạn chỉ cần các lệnh gọi REST chiều ra.
Luồng gọi
- Chuyển vào: backend gọi transferIn với txId duy nhất và số tiền. Kết quả là PENDING hoặc SUCCESS.
- Chơi: mở game. Mọi lần cược và thắng thay đổi số dư phía nhà cung cấp, không có callback tới bạn.
- Chuyển ra: khi người chơi rời đi, gọi transferOut cho toàn bộ số dư và cộng lại vào sổ cái của bạn khi SUCCESS.
- Kết quả chưa rõ: nếu lệnh chuyển bị timeout, truy vấn getTransferStatus với cùng txId trước khi làm bất cứ điều gì khác.
Phương thức API (minh họa)
| Phương thức | Mục đích | Trường chính | Idempotent |
|---|---|---|---|
transferIn | Chuyển tiền từ ví của bạn vào số dư game của người chơi. | playerId, txId, amount, currency | Theo txId |
transferOut | Chuyển tiền từ số dư game về lại ví của bạn. | playerId, txId, amount | all | Theo txId |
getBalance | Đọc số dư game của người chơi. | playerId | Có (chỉ đọc) |
getTransferStatus | Trả về PENDING, SUCCESS hoặc FAILED cho một txId. | txId | Có (chỉ đọc) |
Quy tắc backend của bạn phải tuân theo
- Một txId cho mỗi ý định
- Tạo txId trước lần gọi đầu và dùng lại cho mọi lần gửi lại. Không tạo txId mới cho tới khi biết trạng thái của txId trước.
- Trừ sổ cái của bạn trước
- Với chuyển vào, giữ số tiền trong sổ cái trước khi gọi SSG, rồi xác nhận hoặc giải phóng khi trạng thái là cuối cùng.
- Thu hồi số dư bị kẹt
- Chạy một tác vụ tìm người chơi có số dư game nhưng không có phiên hoạt động, rồi chuyển ra. Điều này xử lý người chơi đóng trình duyệt giữa phiên.
- Doanh số cược và báo cáo
- Vì bạn không thấy cược trực tiếp, hãy tính doanh số, yêu cầu cược khuyến mãi và hạn mức rủi ro từ báo cáo ván lấy từ SSG, không phải từ callback.
- Đối soát
- Đối chiếu mọi lệnh chuyển vào và ra với dữ liệu SSG theo txId, và cảnh báo mọi PENDING quá thời gian timeout của bạn.
- Bảo mật
- Ký yêu cầu bằng HMAC-SHA256, chỉ gọi qua TLS 1.2 trở lên, giữ khóa API trong kho bí mật, và giới hạn máy chủ nào của bạn được gọi SSG.
Tình huống lỗi
| Tình huống | Ví đơn | Ví chuyển khoản |
|---|---|---|
| Timeout mạng | Khi đang cược, SSG gửi lại cùng txId, rồi gửi rollback sau giới hạn gửi lại. Bạn phải idempotent. | Chỉ lệnh chuyển bị ảnh hưởng. Truy vấn getTransferStatus với cùng txId, rồi xử lý. |
| Hệ thống của bạn ngừng hoạt động | Người chơi không thể bắt đầu hay tiếp tục ván. Các ván đang mở bị rollback. | Người chơi tiếp tục chơi với số dư game hiện có. Lệnh chuyển mới bị chặn. |
| Yêu cầu trùng lặp | Trả về phản hồi đã lưu cho txId đó và không thay đổi gì. | Trả về kết quả đã lưu cho txId đó và không thay đổi gì. |
| Người chơi mất kết nối giữa ván | Ván kết thúc tại nhà cung cấp và credit được gửi bình thường. | Ván kết thúc và tiền nằm trong số dư game cho tới khi chuyển ra hoặc tác vụ thu hồi chạy. |
| Lệch số dư | Thường do callback hoặc rollback bị bỏ sót. Phát hiện bằng cách so báo cáo ván theo roundId. | Thường do lệnh chuyển bị kẹt hoặc đang chờ. Phát hiện bằng cách so lệnh chuyển theo txId. |
Nên chọn mô hình nào
Chọn ví đơn nếu
- Bạn đã có dịch vụ ví hoặc sổ cái thời gian thực.
- Bạn cần một số dư chung cho thể thao, casino và khuyến mãi.
- Bạn cần dữ liệu cược trực tiếp cho rủi ro, yêu cầu cược khuyến mãi hoặc hạn mức chơi có trách nhiệm.
- Đội ngũ của bạn vận hành được dịch vụ độ trễ thấp, độ sẵn sàng cao.
Chọn ví chuyển khoản nếu
- Bạn muốn ra mắt nhanh với ít công sức kỹ thuật nhất.
- Bạn chưa có dịch vụ ví thời gian thực.
- Bạn chỉ muốn lệnh gọi chiều ra, không có callback công khai phải bảo vệ.
- Khoảng thời gian số dư bị kẹt ngắn là chấp nhận được và bạn chạy được tác vụ thu hồi.
Nhiều nhà vận hành bắt đầu bằng ví chuyển khoản để vận hành, rồi chuyển sang ví đơn khi dịch vụ ví riêng sẵn sàng. Hãy hỏi chúng tôi cách chuyển đổi theo từng giai đoạn.
Danh sách kiểm tra tích hợp
- Chỉ mục duy nhất trên txId và xử lý idempotent cho mọi lệnh gọi chuyển tiền
- Kiểm tra chữ ký HMAC, dung sai timestamp và danh sách IP cho phép
- Số tiền an toàn dạng thập phân và kiểm tra tiền tệ
- Kiểm thử timeout, gửi lại và rollback trong sandbox, bao gồm cả lần gửi lại muộn
- Tác vụ đối soát hằng ngày theo roundId (ví đơn) hoặc txId (chuyển khoản)
- Giám sát và cảnh báo: độ trễ callback, tỷ lệ lỗi, lệnh chuyển đang chờ, số dư bị kẹt
Trao đổi với kỹ sư tích hợp
Chúng tôi có thể hướng dẫn kỹ sư của bạn qua sandbox và giúp chọn mô hình phù hợp với nền tảng. Cam kết tích hợp trong vòng dưới bảy ngày.
Email cho bộ phận kinh doanh Chat qua Telegram Quay lại Product API
sales@ssggaming.com