Wallet API钱包回调接口

Rollback冲正

Reverse exactly one debit, in full.全额冲正恰好一笔扣款。

POST{callbackUrl}/rollback

Implemented by the merchant · called by the platform商户实现 · 平台调用 · timeout超时 10 s

Reverse exactly one debit. Common and transaction fields (amount = amount of the referenced debit), plus:

冲正恰好一笔扣款。公共字段与交易字段（amount = 被冲正扣款的金额），另加：

refTxnIdstring

The txnId of the debit to reverse.被冲正的那笔扣款的 txnId。

rollbackReasonstring

debit_uncertain (the debit's result was unknown) · decision_failed (a mid-round decision did not go through) · round_cancelled (the platform cancelled the round)debit_uncertain 扣款结果未知 · decision_failed 局中决策没生效 · round_cancelled 平台取消了这局

roundClosedbool

true: no further transactions for this round after this one.true = 这笔之后该局不再有任何交易。

Response data: merchantTxnId (required on OK), balance.

响应 data：merchantTxnId（OK 时必填）、balance。

Situation on your side商户侧的情况	Answer返回	Money资金
Referenced debit succeeded and is not yet reversed被冲正的扣款成功过、还没冲正过	`OK`	Return `amount` to the player退回 `amount`
Same rollback `txnId` repeated同一笔冲正重发	Original result第一次的结果	No change不动
Referenced debit never received被冲正的扣款从没收到过	`TXN_NOT_FOUND` — and remember that `refTxnId` is rolled back, so the debit is refused with `TXN_ROLLED_BACK` if it arrives later`TXN_NOT_FOUND`，并记下这个 `refTxnId` 已被冲正；那笔扣款之后到达时返回 `TXN_ROLLED_BACK`	No change不动
Referenced debit failed (e.g. insufficient balance)被冲正的扣款是失败的（如余额不足）	`TXN_NOT_FOUND`	No change不动
Amount differs from the debit, or the debit belongs to another player / round金额与扣款不同，或扣款属于别的玩家 / 局	`TXN_CONFLICT`	No change不动
Round already closed钱包局已关	`ROUND_CLOSED`	No change不动

We treat both OK and TXN_NOT_FOUND as "rollback complete". TXN_CONFLICT / ROUND_CLOSED are flagged for manual attention and alerted, and retries continue. Anything uncertain is retried (Retries).

OK 和 TXN_NOT_FOUND 平台都视为「冲正完成」。TXN_CONFLICT / ROUND_CLOSED 标「需人工关注」并告警，重试照常继续。结果不确定的一律重试（重试）。

Result codes结果码

OK TXN_NOT_FOUND TXN_CONFLICT ROUND_CLOSED

In addition to the common codes listed in另可能返回通用结果码，见 Result codes结果码.

Test cases测试用例

The conformance test sends the following 5 requests to /rollback. Each response must match the expected result exactly.接口对接测试会向 /rollback 发送以下 5 个请求，每个响应都必须与期望结果完全一致。 All test cases全部测试用例

ROL-03 blocking阻断级 Rollback of a debit never received未收到扣款的冲正 Expected期望 TXN_NOT_FOUND

/rollback R10 ref Tx (never sent) A debit_uncertain

ROL-06 blocking阻断级 Rollback with the correct amount金额正确的冲正 Expected期望 OK

/rollback R11 new T ref Tb 2A roundClosed

ROL-08 blocking阻断级 Rollback after round closure关局后的冲正 Expected期望 ROUND_CLOSED

/rollback R4 ref MUL-01's debit

ROL-09 blocking阻断级 Rollback of a failed debit失败扣款的冲正 Expected期望 TXN_NOT_FOUND

/rollback R2 ref T3 (DEB-05)

ROL-10 warning警告级 Rollback referencing another round's debit跨钱包局的冲正 Expected期望 TXN_CONFLICT or或 ROUND_CLOSED

/rollback R13 ref ROL-07's main debit

POST /rollback { "txnId": "T9W4K7R2PX6NB3HZ", "roundId": "R5X2N8C4V7B9M3K2", "txnSeq": 2, "extPlayerId": "u123_USD", "currency": "USD", "amount": "10.00", "platform": "evo", "tableCode": "evo_lightning_roulette_01", "gameType": "roulette", "platformRoundId": "17af3c0e5d2b", "refTxnId": "T8F3K2M9QHZ5A7B4", "rollbackReason": "debit_uncertain", "roundClosed": true, "createdAt": "2026-11-02T08:00:09.004Z" }

from flask import Flask, request, Response from merchant_sign import verify, envelope, OK app = Flask(__name__) @app.post("/wallet/rollback") def rollback(): raw = request.get_data() # verify the raw bytes BEFORE parsing JSON check = verify(SECRET_KEY, MERCHANT_CODE, request.headers, "POST", request.path, raw) if check != OK: return Response(envelope(check), mimetype="application/json") data = request.get_json() # In ONE database transaction, unique on (merchantCode, txnId): # txnId seen before -> answer exactly the stored result # refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND # amount / player / round differ from that debit -> TXN_CONFLICT # otherwise return amount to the player, close the round if roundClosed return Response(envelope("OK", "OK", {"merchantTxnId":"MT-88414","balance":"1250.50"}), mimetype="application/json")

http.HandleFunc("POST /wallet/rollback", func(w http.ResponseWriter, r *http.Request) { raw, _ := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20)) // verify the raw bytes BEFORE decoding w.Header().Set("Content-Type", "application/json") if check := merchantsign.Verify(secretKey, merchantCode, r.Header, r.Method, r.URL.EscapedPath(), raw, time.Now()); check != merchantsign.OK { w.Write(merchantsign.Envelope(check, "", nil)) return } var in map[string]any _ = json.Unmarshal(raw, &in) // In ONE database transaction, unique on (merchantCode, txnId): // txnId seen before -> answer exactly the stored result // refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND // amount / player / round differ from that debit -> TXN_CONFLICT // otherwise return amount to the player, close the round if roundClosed w.Write(merchantsign.Envelope("OK", "OK", json.RawMessage(`{"merchantTxnId":"MT-88414","balance":"1250.50"}`))) // always HTTP 200 })

@RestController class WalletController { @PostMapping(value = "/wallet/rollback", produces = "application/json") String rollback(@RequestBody byte[] raw, @RequestHeader Map<String, String> headers) throws IOException { String check = MerchantSign.verify(SECRET_KEY, MERCHANT_CODE, headers, "POST", "/wallet/rollback", raw, System.currentTimeMillis()); if (!check.equals(MerchantSign.OK)) { return "{\"code\":\"" + check + "\",\"message\":\"" + check + "\"}"; } JsonNode in = new ObjectMapper().readTree(raw); // parse only after the signature checks out // In ONE database transaction, unique on (merchantCode, txnId): // txnId seen before -> answer exactly the stored result // refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND // amount / player / round differ from that debit -> TXN_CONFLICT // otherwise return amount to the player, close the round if roundClosed return "{\"code\":\"OK\",\"message\":\"OK\",\"data\":" + "{\"merchantTxnId\":\"MT-88414\",\"balance\":\"1250.50\"}" + "}"; } }

<?php require 'MerchantSign.php'; // /wallet/rollback header('Content-Type: application/json'); $raw = file_get_contents('php://input'); // verify the raw bytes BEFORE json_decode $check = MerchantSign::verify(SECRET_KEY, MERCHANT_CODE, getallheaders(), $_SERVER['REQUEST_METHOD'], parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH), $raw); if ($check !== MerchantSign::OK) { echo MerchantSign::envelope($check); exit; } $in = json_decode($raw, true); // In ONE database transaction, unique on (merchantCode, txnId): // txnId seen before -> answer exactly the stored result // refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND // amount / player / round differ from that debit -> TXN_CONFLICT // otherwise return amount to the player, close the round if roundClosed echo MerchantSign::envelope('OK', 'OK', json_decode('{"merchantTxnId":"MT-88414","balance":"1250.50"}', true));

app.MapPost("/wallet/rollback", async (HttpRequest req) => { using var ms = new MemoryStream(); await req.Body.CopyToAsync(ms); var raw = ms.ToArray(); // verify the raw bytes BEFORE deserializing var headers = req.Headers.ToDictionary(h => h.Key, h => h.Value.ToString()); var check = MerchantSign.Verify(SecretKey, MerchantCode, headers, req.Method, req.Path, raw); if (check != MerchantSign.Ok) return Results.Json(new { code = check, message = check }); var input = JsonDocument.Parse(raw).RootElement; // In ONE database transaction, unique on (merchantCode, txnId): // txnId seen before -> answer exactly the stored result // refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND // amount / player / round differ from that debit -> TXN_CONFLICT // otherwise return amount to the player, close the round if roundClosed return Results.Text("{\"code\":\"OK\",\"message\":\"OK\",\"data\":" + "{\"merchantTxnId\":\"MT-88414\",\"balance\":\"1250.50\"}" + "}", "application/json"); });

require 'sinatra' require 'json' require_relative 'merchant_sign' post '/wallet/rollback' do content_type :json raw = request.body.read # verify the raw bytes BEFORE JSON.parse check = MerchantSign.verify(SECRET_KEY, MERCHANT_CODE, request.env, 'POST', request.path_info, raw) return MerchantSign.envelope(check) unless check == MerchantSign::OK input = JSON.parse(raw) # In ONE database transaction, unique on (merchantCode, txnId): # txnId seen before -> answer exactly the stored result # refTxnId never received or failed -> REMEMBER it as rolled back, answer TXN_NOT_FOUND # amount / player / round differ from that debit -> TXN_CONFLICT # otherwise return amount to the player, close the round if roundClosed MerchantSign.envelope('OK', 'OK', JSON.parse('{"merchantTxnId":"MT-88414","balance":"1250.50"}')) end