openlivegame · 商户对接文档（Dev）

┌──────────────┐         ①  POST /provider/v1/gameurl        ┌──────────────┐
│              │ ────────────────────────────────────────▶   │              │
│              │ ◀────────────────────────────────────────   │              │
│              │         返回 gameURL (含 JSESSIONID)         │              │
│   商户       │                                              │   openlivegame    │
│   Merchant   │         ②  玩家跳转游戏客户端 (WS)            │   Platform   │
│              │                                              │              │
│              │ ◀────────────────────────────────────────   │              │
│              │    ③  POST {callback_url}/authenticate       │              │
│              │    ④  POST {callback_url}/bet / result ...   │              │
│              │ ────────────────────────────────────────▶   │              │
└──────────────┘         返回 cash / transactionId            └──────────────┘

步骤

1. 收集所有请求参数的 原始值（表单解码后），排除 hash 本身。
2. 对参数名按 字母序（ASCII 升序）排序。
3. 按顺序拼接为 k1=v1&k2=v2&...&kn=vn。
4. 在末尾 直接追加 secretKey（无分隔符）。
5. 对整串做 MD5，取 小写十六进制。

适用接口

/bet、/result、/refund 三个接口必须强制幂等。/authenticate 与 /balance 为只读接口，不写入状态，天然幂等。

幂等键

请求中的 reference 字段即幂等键（1 位类型前缀 B/R/F + 16 位 roundId，共 17 字符），由 openlivegame 生成，在同一商户范围内全局唯一。

数据库唯一键

商户交易流水表（建议命名 wallet_transactions）必须建立以下数据库级唯一索引：

CREATE UNIQUE INDEX uk_operator_reference
  ON wallet_transactions (operator_id, reference);

-- 同时建议加一个业务维度索引用于查询和对账
CREATE INDEX ix_user_round_type
  ON wallet_transactions (user_id, round_id, txn_type);

说明：reference 在 openlivegame 侧对单个商户全局唯一，因此唯一键用 (operator_id, reference) 足以防止所有重复提交。依靠代码层 if exists then skip 而没有 DB 唯一索引的实现， 在并发场景下会失效。

Bet 接口的推荐流程

// 关键不变量：唯一键 (operator_id, reference) 限制下，一个 reference 只能有一条记录。

BEGIN TRANSACTION;

// Step 1: 先查幂等键，命中则直接返回该流水（场景 A / B）
tx := SELECT * FROM wallet_transactions
      WHERE operator_id = $op AND reference = $ref
      FOR UPDATE;  // 行级锁保证并发安全
if tx exists {
    return { transactionId: tx.id, cash: tx.cash_after,
             currency: tx.currency, error: tx.error_code,
             description: tx.description };
}

// Step 2: 锁定玩家账户行
player := SELECT * FROM players
          WHERE operator_id = $op AND user_id = $userId
          FOR UPDATE;

// Step 3: 业务判断
if player.cash < $amount {
    // 余额不足也要落一条失败流水，重试命中时场景 B 返回
    INSERT INTO wallet_transactions(operator_id, reference, user_id,
        table_code, game_id, round_id, txn_type, amount, cash_before, cash_after,
        error_code, description, status)
    VALUES ($op, $ref, $userId,
            $tableCode, $gameId, $roundId, 'bet',
            $amount, player.cash, player.cash,
            1, 'insufficient balance', 'failed');
    COMMIT;
    return { cash: player.cash, error: 1,
             description: "insufficient balance" };
}

// Step 4: 扣减余额 + 写流水（同一事务内）
UPDATE players SET cash = cash - $amount
                 WHERE id = player.id;

txId := INSERT INTO wallet_transactions(operator_id, reference, user_id,
          table_code, game_id, round_id, txn_type, amount, cash_before, cash_after,
          error_code, description, status)
        VALUES ($op, $ref, $userId,
                $tableCode, $gameId, $roundId, 'bet',
                $amount, player.cash, player.cash - $amount,
                0, 'OK', 'success')
        ON CONFLICT (operator_id, reference) DO NOTHING
        RETURNING id;

// 并发冲突兜底：另一个线程已插入 → 回滚本次扣款，查询已有流水返回（场景 C）
if txId is null {
    ROLLBACK;
    goto Step 1;
}

COMMIT;
return { transactionId: txId, cash: player.cash - $amount,
         currency: player.currency, error: 0, description: "OK" };

Result 与 Refund 同构，区别仅是 txn_type 以及余额是加而非减，且无余额不足分支。 注意 result 的 amount 可能为 0（未中奖结算）——照常落流水、加 0、返回成功。

商户侧实现核对

• ☐ 已与 openlivegame 协商并记录 secureLogin / secretKey / callback_url 三项配置
• ☐ 实现了 5 个回调端点：/authenticate / /balance / /bet / /result / /refund
• ☐ 所有回调对 hash 字段做了签名校验（对全部非 hash 字段计算），签名失败返回 error=4
• ☐ 签名实现用本文档「完整示例」的输入跑出了相同的 MD5 结果
• ☐ 生成的 token 是一次性的、短期有效、与玩家绑定
• ☐ authenticate 返回的 userId 一定等于商户传给 gameurl 的 externalPlayerId，currency 一定等于 gameurl 请求的 currency
• ☐ 多币种用户已使用不同的 externalPlayerId（如 uid_USD / uid_EUR），并在内部维护了自然人到多 ID 的映射
• ☐ 解析回调时机台字段读的是 tableCode（不是 tableId）
• ☐ bet / result / refund 基于 reference 实现了数据库唯一索引级幂等（UNIQUE (operator_id, reference)）
• ☐ result 在 amount="0.00"（未中奖结算）时也能正确落流水并返回成功
• ☐ 扣款 / 加款与流水写入在同一 DB 事务内提交
• ☐ 重复请求不重跑业务，严格返回首次落库的流水与错误码
• ☐ 失败场景（余额不足等）也会落一条 status=failed 流水，保证重试幂等
• ☐ 找不到对应 bet 的 refund 返回 error=2，不凭空加款
• ☐ 所有业务错误均使用 HTTP 200 + JSON error 字段返回，未用 HTTP 4xx/5xx 代替业务错误
• ☐ 余额计算使用 Decimal 类型，未使用 float
• ☐ 回调接口 P99 响应 < 3 秒（bet 的硬超时只有 5 秒）
• ☐ 玩家账户与资金流水表设计了幂等隔离，不会因并发下注导致透支
• ☐ 生产环境配好了服务器 IP 白名单（如有）并向 openlivegame 报备
• ☐ 已完成 openlivegame 提供的联调沙箱测试，包含成功、余额不足、重复 reference、退款等场景

建议的监控指标

• 回调接口 QPS / P99 延迟 / 错误率（按 endpoint 拆分）
• error=1（余额不足）的日占比趋势
• error=5（重复交易）次数 —— 少量正常（对应openlivegame重试），激增需联系openlivegame排查
• 未匹配到 bet 却请求 refund 的次数 —— 对应「bet 超时未落账」场景，激增说明商户侧 bet 链路过慢
• 签名校验失败次数 —— 可能是密钥泄露或被攻击