产品API 单一钱包与转账钱包

单一钱包与转账钱包

这是对接线上游戏API时两种钱包模式的技术对比：资金由谁保管、投注过程中有哪些网络调用、故障如何恢复，以及运营商一侧需要开发什么。

概览对比

对比项	单一钱包	转账钱包
资金保管	玩家余额只存放在运营商数据库，游戏商不持有玩家资金。	游戏商保存独立的游戏余额，资金通过转入、转出接口流转。
投注期间的调用	每一次投注和派彩都会触发对运营商的服务器回调（余额、扣款、加款、回滚）。	无。游戏在游戏商侧余额上运行，仅在转入和转出时产生调用。
可用性要求	钱包接口必须响应每次回调，通常需在数百毫秒内返回；一旦宕机，游戏即中断。	仅转账时需要运营商在线；运营商系统短暂离线时，牌局仍可继续。
一致性模型	运营商账本是实时的唯一事实来源，只需对账牌局，无需对账余额。	两本账仅在转账节点保持一致，需要按转账记录对账。
故障恢复	超时通过按交易ID幂等重试和回滚调用来处理。	转账分两阶段：处理中，然后成功或失败；结果未知时通过状态查询确认。
对接工作量	较高。需自行开发并运维低延迟回调服务，并实现幂等和账本。	较低。仅需调用三四个 REST 接口，无需处理入站流量的安全与扩容。
玩家体验	只有一个余额，无需转账步骤，适合红利、跨产品游玩和实时余额显示。	游戏前转入、结束后转出，会有短暂延迟；玩家中途离开可能造成余额滞留游戏商。
适用场景	拥有自有钱包或平台，并需严格掌控资金与营销活动的运营商。	希望快速上线，或尚无实时钱包服务的运营商。

单一钱包（无缝钱包）

在单一钱包（无缝钱包）模式下，运营商系统就是钱包。玩家下注时，SSG API 会调用你的回调接口，你在自己的账本中变更余额并返回最新余额，资金始终不离开你的数据库。

调用流程

启动：运营商后端携带玩家ID和会话令牌向 SSG 请求游戏链接。
投注：每一局 SSG 都会携带唯一 txId 调用 debit；你校验余额、写入账本并返回最新余额。
派彩：同一局结束后，SSG 调用 credit 加款（金额可为 0）。
故障：调用超时时 SSG 会用同一 txId 重试，超过重试次数后发送 rollback。

回调方法（示例）

方法	用途	关键字段	幂等
`balance`	返回玩家当前余额。	`playerId, currency`	是（只读）
`debit`	下注：扣除金额。	`playerId, txId, roundId, gameId, amount, currency`	按 txId
`credit`	派彩：增加金额。	`playerId, txId, roundId, amount, currency`	按 txId
`rollback`	出现错误后，撤销此前的扣款或加款。	`txId, refTxId`	按 txId

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))"
}

响应示例

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

钱包服务必须遵守的规则

幂等性: 相同 txId 的 debit 或 credit 重复到达时，必须返回原结果，且不得再次变动资金。请在 txId 上建立唯一索引来保证。
账本原子写入: 在同一个数据库事务内完成余额校验、账本插入和余额更新，避免并发投注导致透支。
先收到回滚: 原始 debit 超时后，可能先收到一个你从未见过的 txId 的 rollback。请记录一条标记，使随后迟到的同 txId debit 被拒绝。
延迟预算: 含网络耗时，目标 p99 低于 500 毫秒。回调路径只做一次索引读取和一次写入，报表查询不要走这条路径。
金额格式: 金额使用十进制字符串或整数最小单位，禁止使用浮点数，并校验币种与玩家账户一致。
红利与免费旋转: 免费旋转表现为金额 0 的 debit，随后是派彩的 credit。请在账本中将红利余额与现金余额分开。
安全: 校验对规范化请求计算的 HMAC-SHA256 签名，拒绝过期时间戳，仅放行 SSG 源 IP，并要求 TLS 1.2 及以上。
对账: 按 roundId 将 SSG 的每日牌局报表与你的账本逐笔对比，差异通常源于漏掉的回调或回滚。

转账钱包

在转账钱包模式下，游戏商为每位玩家保存一份游戏余额。运营商后端在游戏前转入资金、游戏后转出资金。游戏过程中不会回调运营商系统，因此只需要发起出站 REST 调用。

调用流程

转入：运营商后端携带唯一 txId 和金额调用 transferIn，结果为处理中或成功。
游戏：启动游戏。所有投注和派彩都只变更游戏商侧余额，不会回调运营商。
转出：玩家离开时调用 transferOut 转出全部余额，成功后再记入运营商自己的账本。
结果未知：转账调用超时后，先用同一 txId 调用 getTransferStatus 查询，再决定后续操作。

接口方法（示例）

方法	用途	关键字段	幂等
`transferIn`	将资金从运营商钱包转入玩家游戏余额。	`playerId, txId, amount, currency`	按 txId
`transferOut`	将游戏余额转回运营商钱包。	`playerId, txId, amount \| all`	按 txId
`getBalance`	查询玩家游戏余额。	`playerId`	是（只读）
`getTransferStatus`	返回某个 txId 的状态：处理中、成功或失败。	`txId`	是（只读）

运营商后端必须遵守的规则

一个意图一个 txId: 在首次调用前生成 txId，所有重试都复用它；在上一笔状态确定之前，绝不要生成新的 txId。
先扣本地账本: 转入时，先在自己的账本中冻结该金额再调用 SSG，待状态终态后确认或释放。
清扫滞留余额: 运行定时任务，找出有游戏余额但没有活跃会话的玩家并转出，覆盖中途关闭浏览器的情况。
流水与报表: 由于实时看不到投注，请通过从 SSG 拉取的牌局报表来计算流水、红利打码和风控限额，而不是依赖回调。
对账: 按 txId 将每笔转入、转出与 SSG 记录核对，对超过超时阈值仍处于处理中的记录告警。
安全: 使用 HMAC-SHA256 对请求签名，仅通过 TLS 1.2 及以上调用，API 密钥存放在密钥管理系统，并限制可调用 SSG 的服务器。

故障场景

场景	单一钱包	转账钱包
网络超时	投注期间 SSG 会用同一 txId 重试，超过次数后发送 rollback，运营商必须保证幂等。	仅转账受影响。用同一 txId 调用 getTransferStatus 查询后再处理。
运营商系统宕机	玩家无法开始或继续牌局，未完成牌局将被回滚。	玩家可用现有游戏余额继续游戏，新的转账会被阻止。
重复请求	按该 txId 返回已保存的响应，不做任何变更。	按该 txId 返回已保存的结果，不做任何变更。
玩家中途断线	牌局在游戏商侧正常结束，并按常规发送 credit。	牌局正常结束，资金留在游戏余额中，直到转出或被清扫任务转出。
余额不一致	通常由遗漏的回调或回滚造成，可按 roundId 对比牌局报表发现。	通常由滞留或处理中的转账造成，可按 txId 对比转账记录发现。

如何选择

在以下情况选择单一钱包

你已有实时钱包或账本服务。
需要体育、娱乐场和营销活动共用同一个余额。
需要实时投注数据来做风控、红利打码或责任博彩限额。
团队能够运维高可用、低延迟的服务。

在以下情况选择转账钱包

希望以最少的开发量快速上线。
尚无实时钱包服务。
只希望发起出站调用，不想暴露并保护公网回调接口。
可以接受余额短暂滞留，并能运行清扫任务。

许多运营商先用转账钱包快速上线，待自有钱包服务就绪后再切换到单一钱包。欢迎咨询如何分阶段切换。

对接检查清单

所有涉及资金的调用都在 txId 上建唯一索引并实现幂等处理
HMAC 签名校验、时间戳容差和 IP 白名单
金额使用十进制安全类型，并校验币种
在测试环境验证超时、重试和回滚，包括迟到的重试
按 roundId（单一钱包）或 txId（转账钱包）执行每日对账任务
监控与告警：回调延迟、错误率、处理中转账、滞留余额

联系对接工程师

我们可以带领你的工程师熟悉测试环境，并帮助你选择适合平台的钱包模式。对接保证在七天内完成。

发送邮件 Telegram 联系返回产品API

sales@ssggaming.com