llms.txt API v1 · 2026-11-02
Wallet API钱包回调接口

Debit扣款

Take a stake. Idempotent by txnId; one wallet round may contain several debits.扣款（下注）。按 txnId 幂等；一个钱包局可以有多笔扣款。

POST{callbackUrl}/debit

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

Take a stake. Common and transaction fields, plus:

扣款。公共字段与交易字段，另加：

bets[]array
Bets in this debit: {betCode, betAmount}; the sum of betAmount equals amount. Informational.这笔扣款包含的注 {betCode, betAmount}，betAmount 之和等于 amount。仅供参考。
merchantTxnIdstring
Your transaction id; same value on repeats. Required on OK.商户交易号，重发时相同。OK 时必填。
balancestring
Balance after the debit; on INSUFFICIENT_BALANCE the current balance (required).扣款后余额；INSUFFICIENT_BALANCE 时为当前余额（必填）。
Must必须Check, in one database transaction: txnId seen before? → original result · txnId already rolled back? → TXN_ROLLED_BACK · round closed? → ROUND_CLOSED · player / currency / limits · balance ≥ amount → deduct and record. Record failures too.在同一个数据库事务里依次检查：txnId 处理过？→ 返回第一次的结果 · txnId 已被冲正？→ TXN_ROLLED_BACK · 钱包局已关？→ ROUND_CLOSED · 玩家 / 币种 / 限额 · 余额 ≥ 金额 → 扣款并记录。失败也要记录。
Your answer商户返回What we do平台处理
OKBet accepted.注生效。
INSUFFICIENT_BALANCE · BET_REJECTED · PLAYER_* · CURRENCY_MISMATCHBet refused; no rollback (nothing was taken).注不生效；不冲正（本来就没扣）。
TXN_CONFLICT · TXN_ROLLED_BACK · ROUND_CLOSEDBet refused; alert (states diverged).注不生效；告警（两边状态不一致）。
Timeout · transport error · HTTP ≠ 200 · INTERNAL_ERROR · MAINTENANCE · response failing Strict response validation超时 · 网络错误 · HTTP ≠ 200 · INTERNAL_ERROR · MAINTENANCE · 响应不满足 响应强制校验Bet refused; rollback sent for this debit (rollbackReason: debit_uncertain or decision_failed).注不生效；对这笔扣款发冲正（rollbackReason: debit_uncertain 或 decision_failed）。

In blackjack, a failed insurance / split / double debit means that decision does not happen and the hand continues without it; a failed main-bet debit means the player sits out the round.

21 点里，保险 / 分牌 / 加倍的扣款失败 = 这个决策不生效，这手牌按没加注继续；主注扣款失败 = 玩家不参与这局。

Result codes结果码

OKINSUFFICIENT_BALANCEBET_REJECTEDPLAYER_NOT_FOUNDPLAYER_DISABLEDCURRENCY_MISMATCHTXN_CONFLICTROUND_CLOSEDTXN_ROLLED_BACK

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

Test cases测试用例

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

SIG-08 blocking阻断级 Debit with an invalid signature签名错误的扣款 Expected期望 INVALID_SIGNATURE
/debit R0 T0 A, wrong signature
The balance remains unchanged.余额不变。
SIG-09 blocking阻断级 Same debit resubmitted with a valid signature以正确签名重新提交同一扣款 Expected期望 OK
/debit R0 T0 A, same body, correct signature
The request with the invalid signature was not recorded as processed.签名错误的请求未被记为已处理。
DEB-01 blocking阻断级 Debit扣款 Expected期望 OK
/debit R1 T1 seq1 A
balance = B0 − Abalance = B0 − A
DEB-02 blocking阻断级 Idempotent repeat of a debit扣款幂等重发 Expected期望 OK
/debit T1, identical body
merchantTxnId is identical to DEB-01; no second deduction.merchantTxnId 与 DEB-01 一致；未重复扣款。
DEB-03 blocking阻断级 Debit with a reused txnId and a different amount同一交易号不同金额的扣款 Expected期望 TXN_CONFLICT
/debit T1 with amount 2A
DEB-05 blocking阻断级 Insufficient balance余额不足 Expected期望 INSUFFICIENT_BALANCE
/debit R2 T3 amount = balance + A
data.balance is present and equals the current balance.响应须携带 data.balance，且与当前余额一致。
DEB-06 blocking阻断级 Persistence of a failed debit result失败结果的持久化 Expected期望 INSUFFICIENT_BALANCE
/debit T3, identical body
Identical to DEB-05.与 DEB-05 一致。
DEB-07 blocking阻断级 Amount exceeding the currency precision超出币种精度的金额 Expected期望 INVALID_PARAM
/debit R3, one decimal more than the currency allows
DEB-08 blocking阻断级 Debit with a mismatched currency币种不符的扣款 Expected期望 CURRENCY_MISMATCH
/debit R3 new T, currency C'
DEB-09 blocking阻断级 Debit for an unknown player不存在玩家的扣款 Expected期望 PLAYER_NOT_FOUND
/debit R3 new T, extPlayerId zz_<random>
DEB-10 warning警告级 Debit with bet lines and losing settlement带注单明细的扣款与输局结算 Expected期望 OK, OK
/debit R3 A, bets 2 × A/2; /credit R3 0 roundClosed
If the amount cannot be split in two at the currency precision, the debit is sent without bet lines; the round is still settled as debit A, credit 0.金额在币种精度下无法均分时，扣款不携带注单明细；该局仍按「扣款 A、派彩 0」结算。
MUL-01 blocking阻断级 First debit in a wallet round同一钱包局第 1 笔扣款 Expected期望 OK
/debit R4 seq1 main A
MUL-02 blocking阻断级 Second debit in the same wallet round同一钱包局第 2 笔扣款 Expected期望 OK
/debit R4 new T seq2 insurance A
The debit must not be treated as a duplicate.不得视为重复请求。
MUL-03 blocking阻断级 Third debit in the same wallet round同一钱包局第 3 笔扣款 Expected期望 OK
/debit R4 new T seq3 double 2A
MUL-05 blocking阻断级 Debit after round closure关局后的扣款 Expected期望 ROUND_CLOSED
/debit R4 new T seq5 A
MUL-08 blocking阻断级 Mid-round credit局中派彩 Expected期望 OK ×3
/debit R5 2A; /credit R5 A roundClosed=false; /credit R5 A roundClosed
MUL-09 blocking阻断级 Zero-amount credit closing the round零金额派彩关局 Expected期望 OK ×2
/debit R6 A; /credit R6 0 roundClosed
MUL-10 blocking阻断级 Round status after a zero-amount credit零金额派彩后的关局状态 Expected期望 ROUND_CLOSED
/debit R6 new T A
CRE-03 blocking阻断级 Restoration of the test balance测试余额复原 Expected期望 OK ×2
/debit R8 A; /credit R8 2A roundClosed
Offsets the loss of MUL-09.抵补 MUL-09 的输局金额。
ROL-01 blocking阻断级 Debit rollback扣款冲正 Expected期望 OK ×2
/debit R9 Ta A; /rollback ref Ta A round_cancelled roundClosed
ROL-04 blocking阻断级 Late debit after its rollback冲正后迟到的扣款 Expected期望 TXN_ROLLED_BACK
/debit R10 txnId Tx A
No deduction is made.未发生扣款。
ROL-05 blocking阻断级 Rollback with a mismatched amount金额不符的冲正 Expected期望 OK, TXN_CONFLICT
/debit R11 Tb 2A; /rollback ref Tb amount A
ROL-07 blocking阻断级 Rollback of one debit among several (failed blackjack double)多笔扣款中单笔冲正（21 点加倍失败） Expected期望 OK ×4
/debit R12 main A; /debit R12 Td double A; /rollback ref Td decision_failed; /credit R12 A roundClosed
BND-01 blocking阻断级 Smallest currency unit币种最小金额单位 Expected期望 OK ×2
/debit R16 one unit (USD 0.01); /credit R16 same amount roundClosed
Both transactions are posted with the exact amount.两笔交易均按精确金额记账。
BND-02 blocking阻断级 Debit equal to the full balance扣款额等于余额 Expected期望 OK ×2 or或 BET_REJECTED
/debit R17 amount = current balance; /credit R17 same amount roundClosed
data.balance is 0 after the debit. BET_REJECTED (risk limits) is also compliant.扣款后 data.balance 为 0。返回 BET_REJECTED（风控限额）亦视为合规。
BND-03 blocking阻断级 Amount as a JSON number金额为 JSON 数字 Expected期望 INVALID_PARAM
/debit R18 "amount": 1.00 (number, not string)
No change of funds.资金不变。
BND-04 blocking阻断级 Negative amount负数金额 Expected期望 INVALID_PARAM
/debit R18 "amount": "-1.00"
No change of funds.资金不变。
BND-05 blocking阻断级 Amount in exponent notation科学计数法金额 Expected期望 INVALID_PARAM
/debit R18 "amount": "1e2"
No change of funds.资金不变。
BND-06 blocking阻断级 Missing required field缺少必填字段 Expected期望 INVALID_PARAM
/debit R18 without currency
No change of funds.资金不变。
BND-07 blocking阻断级 Identifiers at maximum length最大长度编号 Expected期望 OK ×2
/debit + /credit R19 with roundId and txnId of 32 characters
Both transactions are posted.两笔交易均成功记账。
BND-09 warning警告级 Bet lines not matching the amount注单明细合计与金额不符 Expected期望 OK ×2
/debit R20 A with one bet line A/2; /credit R20 A roundClosed
The debit is posted at amount A.扣款按金额 A 记账。
BND-10 warning警告级 Debit of an excessive amount超大金额扣款 Expected期望 INSUFFICIENT_BALANCE or或 BET_REJECTED
/debit R21 amount 100000000000000.00
No change of funds; no error and no timeout.资金不变，且不得出现错误或超时。
CON-01 blocking阻断级 Concurrent duplicate debit (10 requests)同一扣款并发重复提交（10 次） Expected期望 OK
/debit R14 T A × 10 in parallel
All OK responses carry the same merchantTxnId and the amount is deducted exactly once. INTERNAL_ERROR among the responses is tolerated; any other result code is not.所有 OK 响应的 merchantTxnId 一致，且仅扣款一次。允许夹杂 INTERNAL_ERROR，不允许其他结果码。
CON-03 blocking阻断级 Concurrent debits in 10 wallet rounds10 个钱包局并发扣款 Expected期望 OK ×10
/debit R15…R24 A each, in parallel