Skip to navigation
OverviewWuzzloWuzzlo to Operator

Debit player balance for a bet

View as Markdown

Direction: Wuzzlo → Operator

Debits a player’s wallet when a bet is accepted.

Processing order

  1. Verify the Wuzzlo Signature before creating any records.
  2. Check reqId and transactionId idempotency.
  3. Validate available funds.
  4. Debit atomically and return the resulting balance.

Response contract

ScenarioHTTPStatusBalance behavior
New valid debit200OP_SUCCESSSubtract once
Same reqId replayed200OP_DUPLICATE_REQUESTUnchanged
Existing transactionId with a new reqId200OP_DUPLICATE_TRANSACTIONUnchanged
Insufficient funds200OP_INSUFFICIENT_FUNDSUnchanged
Signature is missing or invalid200OP_INVALID_SIGNATUREReturn 0; actual balance unchanged

Security: Invalid signatures must not create transaction or idempotency records.

Authentication

Signaturestring

Wuzzlo-to-Operator: Base64 RSA-SHA256 PKCS#1 v1.5 signature of the exact UTF-8 JSON body, verified with the Wuzzlo public key.

Request

This endpoint expects an object.
operatorIdstringRequired
sessionTokenstringRequired

Operator session token validated through /auth/login.

userIdstringRequired
reqIdstringRequired

Durable idempotency key. An exact replay must return OP_DUPLICATE_REQUEST without changing balance.

transactionIdstringRequired
Logical wallet transaction identifier shared by the debit lifecycle.
gameIdstringRequired
roundIdstringRequired
amountdoubleRequired

Authoritative monetary amount. Use decimal-safe arithmetic.

tokenstringOptional
debitAmountdoubleOptional
settlementKindstringOptional
settlementStatusstringOptional
resultStatusstringOptional
betTypestringOptional

Response

HTTP 200 debit response. The body status MUST be the single exact value assigned to the matching scenario; statuses are not interchangeable.

balancedouble

Balance returned for this response scenario. Successful mutations return the calculated post-transaction balance; duplicate and rejected scenarios return the unchanged balance.

statusenum
Exact business status required by the matched endpoint scenario. A different status is a contract failure even when the returned balance is correct.
Allowed values: