Wallet protocol
RGS wallet protocol, version 1.3.1: the rules that apply to every operation, and the operations.
RGS wallet protocol, version 1.3.1. Download the document: wallet.yaml.
Operators implement this API and the RGS calls it. Amounts are integer micro-units: 1000000 = 1.00. Every request and response is signed. Idempotency by transactionId is required, and a rollback for an unknown debit must be remembered so a late debit is refused.
Credit and rollback settle money that is already decided. A credit must be accepted with an expired session, and neither may fail because of a blocked or self-excluded player. The RGS never drops them; a round is settled by a final answer, or by hand:
- status error with a listed code other than DUPLICATE is a definite refusal: nothing moved. The RGS does not repeat the call. The round goes to the operators' attention queue and is repeated only when an operator asks, or is marked settled once the casino confirms it by hand. A definite refusal of a credit means manual work on both sides, so a wallet should not answer one.
- NOT_FOUND on a rollback means there is nothing to return: the RGS treats it as done.
- any other answer, DUPLICATE and an unknown code included, is an unknown outcome. The RGS repeats the same transactionId with backoff until it gets a final answer.
On a debit an unknown outcome leads to a rollback. So a wallet that adds its own refusal must use a listed code, or the bet is rolled back and the player sees a general error.
HTTP status: 401 and 403 mean the key or signature was refused and no money moved. Every other status outside 2xx (any other 4xx, any 5xx) is an unknown outcome, as are a body that is not JSON, a status other than ok or error, and a response whose signature or timestamp does not hold.
X-Key-Id names the shared secret. While a secret is rotated, requests may carry either key id: verify each request with the secret of its X-Key-Id and sign the response with that same secret. Keep the old secret until the RGS confirms that no call uses it.
Limits:
- X-Timestamp may differ from the receiver's clock by at most 60 s either way. The RGS holds a response to it (outside, the answer is an unknown outcome); a wallet should hold requests to the same bound.
- The RGS reads at most 1 MiB of a response; a longer one fails its signature and is an unknown outcome.
- reason is cut to 64 bytes and message to 512, on a UTF-8 boundary, with control characters replaced by spaces.
- balance and every amount are JSON integers in micro-units; a fraction or a string is not a valid body, so the answer is an unknown outcome.
Transaction ids: a round's debit is roundId:debit:1, its credit
roundId:credit and its rollback roundId:rollback:1. A jackpot win is
credited by the RGS's jackpot service as a second credit of the round,
roundId:jackpot:pool:level:index. They never change, and
reconciliation matches the export by them.
A credit can arrive without a debit of its own: a jackpot win, credited by its own id after its round closed, and the settlement of a player's saved progress, a credit-only round with no debit at all. Accept it like any credit.
A free round's credit carries freeRounds and has no debit before it. Accept
it like any credit: it moves the balance by its amount, once, and its repeat
answers the same.
Operations
- Current balance:
POST /balance - Charge a bet:
POST /debit - Pay out and close the round:
POST /credit - Cancel a named debit:
POST /rollback - Export the applied operations of a period:
POST /operations