Wallet API

Overview

• Requests and responses contain the header Content-Type: application/json
• Requests are made via the HTTP POST method
• All requests passed from/to the Operator’s system have a signature header.
• Request Direction: Veligames => Operator

Important

We expect idempotent behavior in case of duplicate transactions. If the initial transaction was successfully processed, any subsequent duplicate transactions should be ignored response should be returned with HTTP status code 409 as a DUPLICATE_TRANSACTION.

Important

In some cases, a single roundId is not tied to a specific playerId. For instance, in crash games, rounds are global, meaning all users participating in the same round will share the same roundId.

Important

if sessionId was expired on operator side, /win and /cancel should be still processed. /bet should be processed if isAdjustment=true

Balance

Request

Using this method VeliGames system will receive the current balance of the player and will show it in the game.

POST /balance

Property	Type	Description	Required
sessionId	string	One-time identifier generated by OPERATOR for the specific session	Yes
providerId	string	Identifier of the game provider	Yes
playerId	string	Identifier of the player	Yes
currency	string	Player's ISO 4217 currency code. Examples: EUR, USD	Yes
brandId	string	Casino Brand Identifier	Yes
providerId	string	Game provider Id	Yes
gameId	string	If session is expired and the gameId is valid, you should return balance	No

Response

Property	Type	Description	Required
real	object	Real balance of the player	Yes
real.amount	decimal	Real balance amount.	Yes
real.currency	string	Real balance currency.	Yes
bonus	object	Bonus balance of the player	No
bonus.amount	decimal	Bonus balance amount.	Yes
bonus.currency	string	Bonus balance currency.	Yes

Error Protocol

Error	Status Code	Description
UNKNOWN_ERROR	500	General error, internal server error, can be retried
BAD_REQUEST	400	Missing/invalid parameters
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	Player does not exist
SESSION_NOT_FOUND	404	Session does not exist
SESSION_EXPIRED	410	Session expired

Bet

Request

Using this method VeliGames system will check the player’s balance to ensure enough funds are available to make a bet. The amount of the bet must be subtracted from the player’s balance.

POST /bet

Property	Type	Description	Required
sessionId	string	Session Id	Yes
betType	string	Type of the bet (BET_SPIN, BET_SPORT, BET_CRASH)	Yes
transactionId	string	Unique Id of the transaction	Yes
gameId	string	Identifier of the game	Yes
playerId	string	Identifier of the player	Yes
roundId	string	Identifier of the round	Yes
providerId	string	Identifier of the game provider	Yes
amount	object	Amount object of the bet	Yes
amount.amount	decimal	Bet amount.	Yes
amount.currency	string	Player's ISO 4217 currency code. Examples: EUR, USD	Yes
correlationId	string	Bet Id Identifier	Yes
brandId	string	Casino Brand Identifier	Yes
gameType	string	CRASH, OTHER	Yes
jackpotContribution	decimal	Amount of the contribution to the jackpot	No
jackpotId	string	Id of the active jackpot to contribute	No
isAdjustment	boolean	Session expiration should be ignored if the bet is adjustment	No

Response

Property	Type	Description	Required
walletTransactionId	string	Id of the transaction in wallet.	Yes
real	object	Real balance of the player	Yes
real.amount	decimal	Real balance amount.	Yes
real.currency	string	Real balance currency.	Yes
bonus	object	Bonus balance of the player	No
bonus.amount	decimal	Bonus balance amount.	Yes
bonus.currency	string	Bonus balance currency.	Yes
usedBonusAmount	decimal	Part of the bet amount which is taken from bonus balance	No

Error Protocol

Error	Status Code	Description
UNKNOWN_ERROR	500	General error, internal server error, can be retried
BAD_REQUEST	400	Missing/invalid parameters
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	Player does not exist
SESSION_NOT_FOUND	404	Session does not exist
SESSION_EXPIRED	410	Session expired
INSUFFICIENT_BALANCE	400	Balance is insufficient
BET_LIMIT_REACHED	400	Bet limit reached - for regulated markets
ACCOUNT_LOCKED	403	Player is locked/frozen
DUPLICATE_TRANSACTION	409	Duplicate transaction
REALITY_CHECK_WARNING

Win

Request

Using this method VeliGames system will send the Operator the winning result of a bet. The player balance should be updated by the amount and returned in the response. Operator should to not reject win on the round even if the session is expired. It can be a retry or bet can be settled later.

POST /win

Property	Type	Description	Required
sessionId	string	Session Id	Yes
winType	string	Type of the win (WIN_ORDINARY, WIN_FREE, WIN_JACKPOT). WIN_FREE is only sent if freespin/freebet was assigned by operator.	Yes
transactionId	string	Unique Id of the transaction	Yes
gameId	string	Identifier of the game	Yes
playerId	string	Identifier of the player	Yes
roundId	string	Identifier of the round	Yes
correlationId	string	Bet Id Identifier	Yes
providerId	string	Identifier of the game provider	Yes
amount	object	Amount object of the bet	Yes
amount.amount	decimal	Win amount.	Yes
amount.currency	string	Player's ISO 4217 currency code. Examples: EUR, USD	Yes
brandId	string	Casino Brand Identifier	Yes
gameType	string	CRASH, OTHER	Yes
rewardId	string	Reward (Freespin / Freebet identifier)	No, Yes if WIN_FREE

Response

Property	Type	Description	Required
walletTransactionId	string	Id of the transaction in wallet.	Yes
real	object	Real balance of the player	Yes
real.amount	decimal	Real balance amount.	Yes
real.currency	string	Real balance currency.	Yes
bonus	object	Bonus balance of the player	No
bonus.amount	decimal	Bonus balance amount.	Yes
bonus.currency	string	Bonus balance currency.	Yes

Error Protocol

Error	Status Code	Description
UNKNOWN_ERROR	500	General error, internal server error, can be retried
BAD_REQUEST	400	Missing/invalid parameters
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	Player does not exist
SESSION_NOT_FOUND	404	Session does not exist
DUPLICATE_TRANSACTION	409	Duplicate transaction
SESSION_EXPIRED	410	Session expired
FREE_BET_NOT_FOUND	404	RewardId is not registered on the operator side or was cancelled

Cancel

Request

Using this method VeliGames system will send the Operator in order to reverse the transaction and adjust the player's balance, The Operator should return the money back to the player's balance. Operator should to not reject cancel of the transaction even if the session is expired.

POST /cancel

Property	Type	Description	Required
sessionId	string	Session Id	Yes
cancelType	string	Type of the cancel (CANCEL_ROUND, CANCEL_BET, CANCEL_TRANSACTION)	Yes
transactionId	string	Unique Id of the transaction	Yes
refTransactionId	string	Reference to the original transaction ID (Not relevant for CANCEL_ROUND	Yes/No
gameId	string	Identifier of the game	Yes
playerId	string	Identifier of the player	Yes
roundId	string	Identifier of the round	Yes
correlationId	string	Bet Id Identifier	No
providerId	string	Identifier of the game provider	Yes
adjustmentRefund	object	Adjustment refund amount object (If cancelType = CANCEL_BET)	No
adjustmentRefund.amount	decimal	Refund amount	Yes
adjustmentRefund.currency	string	Player's ISO 4217 currency code. Examples: EUR, USD	Yes
brandId	string	Casino Brand Identifier	Yes
gameType	string	CRASH, OTHER	Yes

Response

Property	Type	Description	Required
walletTransactionId	string	Id of the transaction in wallet.	Yes
real	object	Real balance of the player	Yes
real.amount	decimal	Real balance amount.	Yes
real.currency	string	Real balance currency.	Yes
bonus	object	Bonus balance of the player	No
bonus.amount	decimal	Bonus balance amount.	Yes
bonus.currency	string	Bonus balance currency.	Yes

Error Protocol

Error	Status Code	Description
UNKNOWN_ERROR	500	General error, internal server error, can be retried
BAD_REQUEST	400	Missing/invalid parameters
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	Player does not exist
SESSION_NOT_FOUND	404	Session does not exist
TRANSACTION_NOT_FOUND	404	Transaction not found
DUPLICATE_TRANSACTION	409	Duplicate transaction
SESSION_EXPIRED	410	Session expired