Seamless Wallet API

Danger

Avoid strict validation that blocks unknown fields. The API will remain backward-compatible, but new fields may be introduced in future updates.

The Wallet API offers seamless wallet integration. Casino operator should implement the following protocol on their side. VeliGames will call the methods to retrieve and update player’s balance when player makes a bet, gets a win or cancels previous transaction.

All following requests are passed from VeliGames to the operator using the HTTP POST method with the content type application/json. The signature parameter in the header is mandatory for all requests.

See also

Authentication

Important

Idempotent behavior in case of duplicate transactions.

If the initial transaction was successfully processed, any subsequent duplicate transactions should be ignored. Error response should be returned with HTTP status code 409 as a DUPLICATE_TRANSACTION.

The session ID expires on operator side

If the session identifier (the sessionId parameter) expires on operator side, /balance, /win and /cancel API methods should still be processed. The /bet method is only processed if isAdjustment=true.

Tip

Round Id not tied to Player ID

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

Balance with sport providers

Some sport providers, like 568win (SBO), expect a negative player balance in cases when the canceled amount exceeds the actual balance.

API Method: balance

The /balance API method enables receiving the current player’s balance in order to show it in the game. This method is sometimes requested outside the gaming session.

Path:

https://{operator-wallet-url}/balance

HTTP Method:

POST

Request body

Parameter	Type	Description
sessionId	string	A one-time identifier previously generated by the operator for a specific session
providerId	string	The identifier of the game provider
playerId	string	The identifier of the player [4]
currency	string	The player’s currency code [1]
brandId	string	The identifier of the casino brand [3]
gameId	string (optional)	The unique identifier of a game. If the session expires and the gameId is valid, the balance is returned.

JSON Response

The response contains details about the current player’s balance. If the bonus balance is available, related properties- amount and currency -are specified.

Parameter	Type	Description
real	object	The real balance of the player
real.amount	decimal	The balance amount in real money
real.currency	string	Real balance currency [1]
bonus (optional)	object	The player’s bonus balance
bonus.amount	decimal	Bonus balance amount.
bonus.currency	string	The code for the bonus balance currency. This code must match that of the real currency

An example of using balance API method

curl -X 'POST' \
'https://{operator-wallet-url}/balance' \
-H 'Content-Type": application/json' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5d...0GCfUspxw==' \
-d '{
       "brandId":"someBrand",
       "providerId":"acceptance-tests",
       "sessionId":"449d...b1f8b7",
       "currency":"EUR",
       "playerId":"2cafb095...7f05",
       "gameId":"e2e"
 }'
Copy code

An example of the success response to the balance request

{ "real": { "currency":"EUR", "amount":27.3 } }
Copy code

Errors

Error	Status code	Description
UNKNOWN_ERROR	500	A generic error: an internal server error, which can be retried
BAD_REQUEST	400	Missing/invalid parameters
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	There is no player for the requested player identifier
SESSION_NOT_FOUND	404	Session does not exist
SESSION_EXPIRED	410	The session has expired

API Method: bet

The /bet API method enables checking if the player’s balance has enough funds for making a bet and then subtracting the bet amount from the player’s balance.

Path:

https://{operator-wallet-url}/bet

HTTP Method:

POST

Request body

Parameter	Type	Description
sessionId	string	Session Id
betType	string	The type of the bet: BET_SPIN, BET_SPORT, BET_CRASH
transactionId	string	The unique identifier of the transaction
gameId	string	The identifier of the game
playerId	string	Identifier of the player [4]
roundId	string	The identifier of the round
providerId	string	The identifier of the game provider
amount	object	Information about the bet amount
amount.amount	decimal	The bet amount
amount.currency	string	The currency code [1]
correlationId	string	The bet Id Identifier
brandId	string	The identifier of the casino brand [3]
gameType	string	The type of the game: CRASH , SPORT or OTHER
isBonusBuy	boolean	Bonus buy transaction. Such bets can be without corresponding win.
jackpotContribution	decimal	The amount of the contribution to the jackpot
jackpotId	string	The identifier of the active jackpot to contribute
isAdjustment	boolean	The session expiration is ignored when this parameter is set to true
extraInfo	ExtraInfoSchema (optional)	Additional information about the bet

Important

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

• Some Sport providers expect a negative player balance support in case when the canceled amount exceeds the actual balance.

• If sessionId expires on the operator’s side, /win and /cancel are still processed. The /bet API method is processed even if isAdjustment is set to true. Some providers may readjust players’ balance outside of the session. In this case the bet contains isAdjustment set to true.

• The following parameters are optional: jackpotContribution, jackpotId, isAdjustment, and extraInfo

See also

API Method: win, API Method: cancel

An example of a bet request

curl -X 'POST' \
'https://{operator-wallet-url}/bet' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==' \
-H 'Content-Type: application/json' \
-d '{
       "providerId":"acceptance-tests",
       "sessionId":"449d1e54-5f7b-42d1-b851-93e6fcb1f8b7",
       "brandId":"someBrand",
       "betType":"BET_CRASH",
       "gameId":"e2e",
       "gameType":"CRASH",
       "playerId":"PLAYER-2cafb...7f05",
       "roundId":"ceef015...96bce",
       "transactionId":"TRX-b93...42eb",
       "correlationId":"eda29e8...c514",
       "amount":{"amount":50,"currency":"EUR"}
}'
Copy code

JSON Response

{
  "real": {
    "currency": "EUR",
    "amount": 27.3
  },
  "bonus": {
    "currency": "EUR",
    "amount": 10
  },
  "walletTransactionId": "TRX-b93...42eb",
  "usedBonusAmount": 0,
  "usedRealAmount": 10
}
Copy code

Parameter	Type	Description
walletTransactionId	string	The identifier of the transaction in the wallet
real	object	Information about the player’s balance in real money
real.amount	decimal	The amount of the real balance
real.currency	string	The currency code [1]
bonus (optional)	object	The bonus balance of the player
bonus.amount	decimal	The bonus balance amount
bonus.currency	string	The code of the bonus balance currency. This cannot be different from the currency of the real balance
usedRealAmount	decimal	The part of the bet amount which is taken from real balance
usedBonusAmount	decimal	The part of the bet amount which is taken from bonus balance

Optional response parameters

The following parameters are optional: usedRealAmount, usedBonusAmount. All parameters related to the bonus money are included in case the player has the bonus amount. Otherwise, all bonus related parameters are omitted.

Errors

An example of an error response to the bet request

{"error":"INSUFFICIENT_BALANCE"}
Copy code

Error ID	Status code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are missing or invalid
UNAUTHORIZED	401	Invalid signature
PLAYER_NOT_FOUND	404	The player does not exist
SESSION_NOT_FOUND	404	The session does not exist
SESSION_EXPIRED	410	The session has expired
INSUFFICIENT_BALANCE	400	The balance is not sufficient
BET_LIMIT_REACHED	400	The bet limit has been reached (for regulated markets)
ACCOUNT_LOCKED	403	The player is locked or frozen
DUPLICATE_TRANSACTION	409	Duplicate transaction
REALITY_CHECK_WARNING	409	A reality check warning

API Method: win

Via the /win API method, VeliGames sends the winning result of a player’s bet. The player’s balance is updated by the winning amount. Then, the updated balance is returned in the response. The operator may not reject the win on the round even if the session has expired. The request can be retried or the bet can be settled later.

Path:

https://{operator-wallet-url}/win

HTTP Method:

POST

Request body

Parameter	Type	Description
sessionId	string	The identifier of the session
winType	string	The type of the win. This parameter is set to one of WIN_ORDINARY WIN_FREE WIN_JACKPOT The WIN_FREE type is only sent if a free spin or a free bet has been assigned by the operator.
transactionId	string	The unique identifier of the transaction
gameId	string	The identifier of the game
playerId	string	The identifier of the player [4]
roundId	string	The identifier of the round
correlationId	string	The Bet Id Identifier
providerId	string	The identifier of the game provider
amount	object	The amount object that describes the winning
amount.amount	decimal	The won amount
amount.currency	string	The player’s currency [1]
brandId	string	The identifier of the casino brand [3]
gameType	string	The type of the game: CRASH SPORT OTHER
rewardId	string	The identifier of the free spin or free bet reward. (Freespin or Freebet)
isCashOut	boolean	Indicates if the winning is a result of a cash-out operation
isPromo	boolean	such wins can be without corresponding bet, for example for in-game bonus, tournaments, etc.
isAdjustment	boolean	Such wins can be without corresponding bet. If the win was initiated from Provider as an adjustment.
extraInfo	ExtraInfoSchema	Additional information about the winning

Optional parameters

The following parameters are optional: isCashOut, extraInfo, isPromo, isAdjustment. The rewardId parameter is only required with the winType set to WIN_FREE.

An example of a win API method

curl -X 'POST' \
'https://{operator-wallet-url}/win' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==' \
-H 'Content-Type: application/json' \
-d '{
       "brandId":"someBrand",
       "sessionId":"03bbdd...54fd3",
       "providerId":"btg",
       "winType":"WIN_ORDINARY",
       "gameId":"whiterabbitv4000",
       "gameType":"OTHER",
       "playerId":"PLAYER-be6f...26de7",
       "roundId":"9940...5ad01c71e3",
       "transactionId":"TRX-680b24...540e1a",
       "correlationId":"9940b...d01c71e3",
       "roundClosed":true,
       "amount":{"amount":1830,"currency":"ZAR"}
}'
Copy code

JSON Response

Parameter	Type	Description
walletTransactionId	string	The identifier of the transaction in the wallet
real	object	The balance of the player in real money
real.amount	decimal	The amount of the real balance
real.currency	string	Real balance currency
bonus (optional)	object	Bonus balance of the player [2]
bonus.amount	decimal	The amount of the bonus balance
bonus.currency	string	The code of the bonus balance currency. The currency code must match that of the real balance
usedRealAmount	decimal	Part of the win amount which is added to real balance
usedBonusAmount	decimal	Part of the win amount which is added to bonus balance

{
    "walletTransactionId": "TRX-b93...42eb",
    "real": {
       "currency": "EUR",
       "amount":27.3,
    },
    "bonus": {
       "currency": "EUR",
       "amount": 10,
       ""
    },
    "usedRealAmount": 5,
    "usedBonusAmount" 5
}
Copy code

Errors

Error ID	Status Code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are missing or invalid
UNAUTHORIZED	401	The signature is invalid
PLAYER_NOT_FOUND	404	The player does not exist
SESSION_NOT_FOUND	404	Session does not exist
DUPLICATE_TRANSACTION	409	A duplicate transaction
SESSION_EXPIRED	410	The session has expired
FREE_BET_NOT_FOUND	404	The rewardId is not registered on the operator side or has been canceled

API Method: cancel

The /cancel API method reverses the transaction and adjusts the player’s balance. The operator returns the money back to the player’s balance. The operator may not reject the cancellation of the transaction even if the session has expired.

Path:

https://{operator-wallet-url}/cancel

HTTP Method:

POST

Request body

All parameters in the JSON request are mandatory unless specified otherwise.

Parameter	Type	Description
sessionId	string	A unique session identifier
cancelType	string	The type of the cancellation. This parameter may be set to one of the following values: CANCEL_ROUND CANCEL_BET CANCEL_TRANSACTION
transactionId	string	The unique identifier of the transaction
refTransactionId	string	A reference to the original transaction identifier
gameId	string	The identifier of the game
playerId	string	The identifier of the player [4]
roundId	string	The identifier of the round
correlationId	string	The Bet Id Identifier
providerId	string	The identifier of the game provider
adjustmentRefund	object	Adjustment refund amount
adjustmentRefund.amount	decimal	The amount of the refund
adjustmentRefund.currency	string	The player’s currency code [1]
isAdjustment	boolean	If the cancel was initiated by Provider as an adjustment.
brandId	string	The identifier of the casino brand [3]
gameType	string	The game type. This parameter may be set to one of the following values: CRASH SPORT OTHER
extraInfo	ExtraInfoSchema	Additional information about the cancel request

Optional parameters

The adjustmentRefund parameter is only available if the cancelType parameter is set to CANCEL_BET. In this case, the parameters adjustmentRefund.amount and adjustmentRefund.currency will also be specified along with isAdjustment.

The refTransactionId parameter is omitted if cancelType is set to CANCEL_ROUND.

The parameters correlationId and extraInfo are optional.

An example of using the cancel API method

curl -X 'POST' \
'https://{operator-wallet-url}/cancel' \
-H 'accept: */*' \
-H 'signature:OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==' \
-H 'Content-Type: application/json' \
-d '{
       "sessionId":"0fc68f...61726de8b",
       "providerId":"jili",
       "transactionId":"TRX-b367c9...87688222",
       "refTransactionId":"TRX-bba5...54394",
       "playerId":"PLAYER-d39...08c57",
       "gameId":"101",
       "gameType":"OTHER",
       "cancelType":"CANCEL_TRANSACTION",
       "roundId":"776686",
       "correlationId":"776686",
       "brandId":"someBrand"
}'
Copy code

JSON Response

Parameter	Type	Description
walletTransactionId	string	The identifier of the transaction in the wallet
real	object	The balance of the player in real money
real.amount	decimal	The amount of the real balance
real.currency	string	The code of the currency on the real balance
bonus (optional)	object	Bonus balance of the player [2]
bonus.amount	decimal	Bonus balance amount
bonus.currency	string	The currency code of the bonus balance. The currency code must match that of the real balance
usedRealAmount	decimal	The part of the cancel amount which is taken from real balance
usedBonusAmount	decimal	The part of the cancel amount which is taken from bonus balance

Optional parameters

The parameters usedRealAmount and usedBonusAmount are optional.

Errors

Error ID	Status Code	Description
UNKNOWN_ERROR	500	A generic error or an internal server error that can be retried
BAD_REQUEST	400	The parameters are either missing or invalid
UNAUTHORIZED	401	The signature is invalid
PLAYER_NOT_FOUND	404	The player does not exist
SESSION_NOT_FOUND	404	The session does not exist
TRANSACTION_NOT_FOUND	404	The transaction has not been found
DUPLICATE_TRANSACTION	409	Duplicate transaction
SESSION_EXPIRED	410	The session has expired

ExtraInfoSchema Type

ExtraInfoSchema is a type that may optionally be passed in requests in order to specify additional information with JSON documents in the scope of the Wallet API. This type is normally used with sport integrations.

If present, conforming objects must have the following parameters:

Parameter	Type	Description
betType	string	The type of the bet
globalCoefficient	number	The global coefficient for the bet
stakes	ExtraInfoStakeSchema[]	A list of stakes

Each stake from the list of stakes passed as the value of the stakes parameter is structured as follows:

Parameter	Type	Description
coefficient	number	The coefficient of the stake
eventName	string	The name of the event
eventDate	string (date-time)	The date of the event
stakeType	string	The type of the stake
stake	string	Stake information
tournament	string	The name of the tournament
sportType	string	The type of the sport
status	string	Stake status

Testing Seamless Wallet

To test if implementation is correct, launch a real game session with following parameters:

• providerId: acceptance-tests

• gameId: e2e

(Stage Only)

See also

Game API Request Example

Footnotes

[1] (1,2,3,4,5,6)

Currency codes comply with ISO 4217: EUR, USD and so on.

[2] (1,2)

If the bonus balance is available, related properties- amount and currency -are specified. Otherwise, this paramater is omitted.

[3] (1,2,3,4)

In some configurations, the brandId parameter appears as agent

[4] (1,2,3,4)

In some configurations, the playerId parameter appears as member