Rollback an unpaid debit | Wuzzlo

Direction: Wuzzlo → Operator

Restores an eligible debit that has not already been settled or rolled back.

Processing order

Verify the Wuzzlo Signature before creating any records.
Load the original debit and validate its lifecycle state.
Confirm the rollback amount matches the original debit.
Restore funds atomically and return the resulting balance.

Response contract

Scenario	HTTP	Status	Balance behavior
New valid rollback	`200`	`OP_SUCCESS`	Restore once
Same `reqId` replayed	`200`	`OP_DUPLICATE_REQUEST`	Unchanged
Transaction already rolled back	`200`	`OP_DUPLICATE_TRANSACTION`	Unchanged
Transaction already credited or settled	`200`	`OP_TRANSACTION_ALREADY_SETTLED`	Unchanged
Rollback amount does not match	`200`	`OP_ROLLBACK_AMOUNT_MISMATCH`	Unchanged
Original debit does not exist	`200`	`OP_TRANSACTION_DOES_NOT_EXIST`	Unchanged
Signature is missing or invalid	`200`	`OP_INVALID_SIGNATURE`	Return `0`; actual balance unchanged

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

**Direction:** Wuzzlo → Operator Restores an eligible debit that has not already been settled or rolled back. ### Processing order 1. **Verify the Wuzzlo `Signature`** before creating any records. 2. **Load the original debit** and validate its lifecycle state. 3. **Confirm the rollback amount** matches the original debit. 4. **Restore funds atomically** and return the resulting balance. ### Response contract | Scenario | HTTP | Status | Balance behavior | | --- | ---: | --- | --- | | New valid rollback | `200` | `OP_SUCCESS` | Restore once | | Same `reqId` replayed | `200` | `OP_DUPLICATE_REQUEST` | Unchanged | | Transaction already rolled back | `200` | `OP_DUPLICATE_TRANSACTION` | Unchanged | | Transaction already credited or settled | `200` | `OP_TRANSACTION_ALREADY_SETTLED` | Unchanged | | Rollback amount does not match | `200` | `OP_ROLLBACK_AMOUNT_MISMATCH` | Unchanged | | Original debit does not exist | `200` | `OP_TRANSACTION_DOES_NOT_EXIST` | Unchanged | | Signature is missing or invalid | `200` | `OP_INVALID_SIGNATURE` | Return `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

rollbackAmountdoubleOptional

betTypestringOptional

settlementKindstringOptional

settlementStatusstringOptional

resultStatusstringOptional

rollbackReasonstringOptional

Response

HTTP 200 rollback 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.