Backend integration

Seamless Wallet API introduction

note

Provider - side which provides games (Aviatrix).

Partner - side which integrates games.

Brand - partner's casino website where users playing games and making bets.

Current document describes methods that should be implemented by partner. Methods will be called by provider during the game flow.

note

For the game launch please read the following document Game API

important

Can not be combined with Transfer Wallet API

IP Whitelisting & Firewalls

To have a secure connection and network traffic control we are recommending to all our partners consider to use L7 Firewall and request header filtering. Particularly, each our outgoing request contains X-Auth-Signature header required for the host authentication.

We strongly do not recommend to use IP Whitelisting and L4 Firewall. Such approach brings restrictions in usage of modern cloud technologies given by hosting services.

important

If partner insists on using IP Whitelisting and L4 Firewall then that means agreement on periodical downtime of our services and partner's whitelists update within one working day.

Seamless Wallet API methods

good to know

All POST requests contain the X-Auth-Signature HTTP header required to authenticate the host. That allows to refuse IP whitelisting during integration process. Otherwise, it deprives the provider of the ability to scale quickly (horizontally) without notifying the platform.

A client side of the provider makes a series of requests to a server side of the provider to receive some data or execute some actions.

The server side of provider interacts with a server side of the brand through the API.

important

Therefore, if the brand is not available, the operation will be resent with an increase in the repetition interval. For example, repetition intervals may be [1s, 2s, 5s ... 1h, 3h]

good to know

All bonus bets are calculated inside game. They are not sent to the brand. Only bonus wins are sent through /transactions/promoWin. Endpoint is also used for other in-game rewards.

do not miss

We expect idempotent behavior in case of duplicates for /bet, /win and /transactions/promoWin. If the first transaction was processed successfully then on the duplicate transaction you shouldn't provide any changes but return the same successful response as if it was processed for the first time

As part of client app integration, the brand must transfer into URL sessionToken of the user.

We recommend choosing the time-to-live (TTL) of the token between 1 hour - 24 hours.

In case when /bet or /playerInfo request comes to the brand with an expired user token it is needed to respond with an appropriate error (see client error section).

do not miss

/win and /transactions/promoWin should be processed even if sessionToken was expired by this time.

important

On all outgoing requests there is set default timeout in X sec. After reaching that time request will be canceled and will be resent again. Carefully read each endpoint description to see the expected values.

/health

The method is called to make health checks. It is desirable that it executes a query to the database or cache. The method does not need any authentication.

It is expected to receive an HTTP code 200 (OK) in response.

important

Expected response time (latency) < 500ms, exceeding 2s is not permitted. After reaching 2s request is canceled and considered as failed.

Example of the request

GET /health HTTP/1.1

/playerInfo

The method is used to receive information about the user (balance, currency, country). The sessionToken is a session token which is passed to the URL in the provider client side integration.

important

Expected response time (latency) < 500ms, exceeding 2s is not permitted. After reaching 2s request is canceled and considered as failed.

Example of the request

POST /playerInfo HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "timestamp": 1234567890
}

Parameter	Description	Type	Requirements	Explanation
cid	unique brand identifier	string	mandatory	value from URL parameters of games provider during integration
sessionToken	user session token	string	mandatory	value from URL parameters of games provider during integration
timestamp	operation time	integer	mandatory	Unix time format

Example of a response from the server

HTTP/1.1 200 OK

{
  "playerId": "someplayerid123",
  "balance": 10000,
  "currency": "EUR"
}

Parameter	Description	Type	Requirements	Explanation
playerId	unique user identifier	string	mandatory	unique within the brand
balance	user balance	integer	mandatory	user balance in the format minor currency unit (given the cents, i.e. the number multiplied by 100)
currency	user currency	string	mandatory	user's balance currency

/bet

The method is used when the user places a bet on the client side of the app.

important

Expected response time (latency) < 2s, exceeding 5s is not permitted. After reaching 10s request is canceled and starts retries logic. If all attempts will fail then starts bet cancellation (/win(operation=CancelBet)).

Bet

Example of the request

POST /bet HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlBsYWNlQmV0Iiwia2V5IjoiIn0=",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 10000,
  "amount": 100,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "bonusId": ""
}

Parameter	Description	Type	Requirements	Explanation
betId	bet identifier	string	mandatory	created on the provider side
cid	unique brand identifier	string	mandatory	value from URL parameters of games provider during integration
sessionToken	token with user session	string	mandatory	value from URL parameters of games provider during integration
playerId	user identifier	string	mandatory	value from request `/playerInfo`
productId	brand game identifier	string	mandatory	value from URL parameters of games provider during integration
txId	transaction identifier	string	mandatory	generated on the provider side
roundId	round identifier	string	mandatory	created on the provider side
market	market	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
outcome	result	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
specifier	specifier	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
odds	coefficient	double	optional	payout ratio
amount	bet amount	integer	mandatory	user bet amount in the format minor currency unit (given the cents, i.e. the number multiplied by 100)
currency	bet currency	string	mandatory	currency in which the user made a bet
roundClosed	flag for closed round	bool	optional	outdated, left for back compatibility
timestamp	operation time	integer	mandatory	Unix time format
bonusId	bonus identifier	string	optional	created on the provider side

Example of a response from the server

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlBsYWNlQmV0Iiwia2V5IjoiIn0="
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Parameter	Description	Type	Requirements	Explanation
processedTxId	transaction identifier	string	optional	transaction identifier on the brand side (useful for debug, error handling or feedback)
createdAt	transaction time	timestamp	mandatory	yyyy-MM-ddThh:mm:ss.sssZ format
balance	user balance	integer	mandatory	new user balance in the format minor currency unit (given the cents, i.e. the number multiplied by 100)

/win

The method is called when the user makes a cashout. In that case the server side of provider sends /win requests for each user bet to settle it. /win is sent for lost bets as well. In that case 0 is written in the amount field.

Also, /win is sent when the bet is canceled. For example, due to the fact that player has canceled bet before game round has started. In that case the original bet amount is written in the amount field and CancelBet operation type is specified in the operation field.

If /win is sent for not existing betId, then brand should return Bet not found error. If /win with different operations(SettleBet, CancelBet) is sent for the same betId, then brand should return Invalid transaction error. If /bet was processed successfully then it's expected that /win will be also processed even when sessionToken expired.

important

Expected response time (latency) < 2s, exceeding 5s is not permitted. After reaching 10s request is canceled and starts retries logic. If all attempts will fail then bet is considered as unsettled and not included to financial statistics.

Example of the request

Bet won

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 12.34,
  "amount": 1234,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "SettleBet",
  "bonusId":""
}

Bet lost

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 12.34,
  "amount": 0,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "SettleBet",
  "bonusId":""
}

Bet canceled

POST /win HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "betId": "1a2b3c4d-6f5e-4d3c-b2a1-f6e5d4c3b2a1",
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IkNhbmNlbEJldCIsImtleSI6IiJ9",
  "roundId": "1234567",
  "market": "result",
  "outcome": "crash",
  "specifier": "",
  "odds": 1,
  "amount": 100,
  "currency": "EUR",
  "roundClosed": false,
  "timestamp": 1234567890,
  "operation": "CancelBet",
  "bonusId":""
}

Parameter	Description	Type	Requirements	Explanation
betId	bet identifier	string	mandatory	created on the provider side
cid	unique brand identifier	string	mandatory	value from URL parameters of games provider during integration
sessionToken	token with user session	string	mandatory	value from URL parameters of games provider during integration
playerId	user identifier	string	mandatory	value from request `/playerInfo`
productId	brand game identifier	string	mandatory	value from URL parameters of games provider during integration
txId	transaction identifier	string	mandatory	generated on the provider side
roundId	round identifier	string	mandatory	created on the provider side
market	market	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
outcome	result	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
specifier	specifier	string	optional	could be used for additional validation, analytics, or to show somewhere on UI
odds	coefficient	double	optional	payout ratio
amount	win amount	integer	mandatory	user win amount in the format minor currency unit (given the cents, i.e. the number multiplied by 100)
currency	win currency	string	mandatory	currency in which the user made a bet
roundClosed	flag for closed round	bool	optional	outdated, left for back compatibility
timestamp	operation time	integer	mandatory	Unix time format
operation	operation type	string	mandatory	Possible values: SettleBet, CancelBet
bonusId	bonus identifier	string	optional	created on the provider side

Example of a response from the server

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlNldHRsZUJldCIsImtleSI6IiJ9"
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Parameter	Description	Type	Requirements	Explanation
processedTxId	transaction identifier	string	optional	transaction identifier on the brand side (useful for debug, error handling or feedback)
createdAt	transaction time	timestamp	mandatory	yyyy-MM-ddThh:mm:ss.sssZ format
balance	user balance	integer	mandatory	new user balance in the format minor currency unit (given the cents, i.e. the number multiplied by 100)

/transactions/promoWin

The method is used when the user transfer bonus win amount to real account.

important

Expected response time (latency) < 2s, exceeding 5s is not permitted. After reaching 10s request is canceled and starts retries logic. If all attempts will fail then promoWin is considered as unsettled and not included to financial statistics.

Example of the request

POST /transactions/promoWin HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "sessionToken": "some4session7token5",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "txId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlByb21vV2luIiwia2V5IjoiIn0=",
  "amount": 1000,
  "currency":"EUR",
  "promo": {
    "type": "bonus",
    "bonusId": "some1bonus2id"
  }
}

Parameter	Description	Type	Requirements	Explanation
cid	unique brand identifier	string	mandatory	value from URL parameters of games provider during integration
sessionToken	token with user session	string	mandatory	value from URL parameters of games provider during integration
playerId	user identifier	string	mandatory	value from request `/playerInfo`
productId	brand game identifier	string	mandatory	value from URL parameters of games provider during integration
txId	transaction identifier	string	mandatory	generated on the provider side
amount	bonus win amount	integer	mandatory	user win amount in the format minor currency unit (given the cents, i.e. the number multiplied by 100)
currency	bonus currency	string	mandatory	currency in which bonus was assigned
promo	promo transaction details	object	mandatory	contains promo transation type and additional identifiers
promo.type	promo transaction type	string	mandatory	possible values: `bonus`, `tournament`
promo.bonusId	bonus idetifier	string	optional	present in request when promo transaction type is `bonus`

Example of a response from the server

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxYTJiM2M0ZC02ZjVlLTRkM2MtYjJhMS1mNmU1ZDRjM2IyYTEiLCJvcCI6IlByb21vV2luIiwia2V5IjoiIn0="
  "createdAt": "0001-02-03T04:05:06.789Z",
  "balance": 10000,
}

Parameter	Description	Type	Requirements	Explanation
processedTxId	transaction identifier	string	optional	transaction identifier on the brand side (useful for debug, error handling or feedback)
createdAt	transaction time	timestamp	mandatory	yyyy-MM-ddThh:mm:ss.sssZ format
balance	user balance	integer	mandatory	new user balance in the format minor currency unit (given the cents, i.e. the number multiplied by 100)

/closeMatch (optional)

The method is used when specific match is over. Round is an interval between start of accepting bets and its calculation. Some brands use /closeMatch method to keep bets closed. Method is called for each player who has made at least one bet in given round.

After match is closed, no any bet/win calls are expected. If bet/win is sent after match is closed then Invalid transaction error will be expected.

important

Expected response time (latency) < 2s, exceeding 5s is not permitted. After reaching 10s request is canceled and starts retries logic.

Example of the request

POST /closeMatch HTTP/1.1
Content-Type: application/json
X-Auth-Signature: <signature>

{
  "cid": "somebrand",
  "playerId": "someplayerid123",
  "productId": "nft-aviatrix",
  "matchId": "1234567",
  "txId": "eyJiaWQiOiIxMjM0NS0xMjM0NTYiLCJvcCI6IkNsb3NlTWF0Y2giLCJrZXkiOiIifQ=="
}

Parameter	Description	Type	Requirements	Explanation
cid	unique brand identifier	string	mandatory	value from URL parameters of games provider during integration
playerId	user identifier	string	mandatory	value from request `/playerInfo`
productId	brand game identifier	string	mandatory	value from URL parameters of games provider during integration
matchId	round identifier	string	mandatory	generated on the provider side
txId	transaction identifier	string	mandatory	generated on the provider side

Example of a response from the server

HTTP/1.1 200 OK

{
  "processedTxId": "eyJiaWQiOiIxMjM0NS0xMjM0NTYiLCJvcCI6IkNsb3NlTWF0Y2giLCJrZXkiOiIifQ=="
}

Parameter	Description	Type	Requirements	Explanation
processedTxId	transaction identifier	string	optional	transaction identifier on the brand side (useful for debug, error handling or feedback)

Error processing

In general, if an error occurs on the brand side, in addition to the corresponding HTTP status code it is necessary to return an object of the form:

{
  "message": "error text"
}

important

The value of the message field must be equal to the value described in the error text column of the table below.

It is necessary to set an HTTP header Content-Type in the response:

Content-Type: application/json

good to know

The brand may not return the entire list of required errors if the specific error does not apply to it.

good to know

If, based on the specifics, the brand wants to send additional errors that are not presented in the list below, then during the integration process it is necessary to notify the provider about this.

Client errors 4XX

HTTP Status	Error text	Requests	Resending	Description
400	Invalid authentication signature	`playerInfo` `bet` `win` `promoWin` `closeMatch`	No	The authentication signature sent in the X-Auth-Signature header does not match the server-side computed signature of the request body parameters.
400	Invalid session token	`playerInfo` `bet` `win` `promoWin`	No	The session token sent in the request body as a sessionToken parameter is not in the correct format.
400	Invalid request	`playerInfo` `bet` `win` `promoWin` `closeMatch`	No	The brand was unable to deserialize the request, or it contains an invalid format.
400	Invalid transaction	`bet` `win` `promoWin` `closeMatch`	No	The transaction sent in the request body as a txId parameter is not in the correct format.
400	Invalid player currency	`bet` `win` `promoWin`	No	The currency sent in the request body as currency parameter does not match the player's currency.
401	Session token expired	`playerInfo` `bet`	No	The TTL of the session token sent in the request body as a sessionToken parameter has expired.
403	Player banned	`bet` `win` `promoWin` `closeMatch`	No	The player sent in the request body as the playerId parameter is blocked.
403	Insufficient balance	`bet`	No	The player sent in the request body as the playerId parameter has insufficient balance to place a bet.
403	Bet limit exceeded	`bet`	No	The player sent in the request body as the playerId parameter has exceeded any limit on the brand side.
404	Platform not found	`playerInfo` `bet` `win` `promoWin` `closeMatch`	No	The brand identifier sent in the request body as the cid parameter does not exist.
404	Product not found	`bet` `win` `promoWin` `closeMatch`	No	The product (game) sent in the request body as the productId parameter does not exist.
404	Player not found	`bet` `win` `promoWin` `closeMatch`	No	The player sent in the request body as the playerId parameter does not exist.
404	Bet not found	`win`	No	The bet identifier sent in the request body as the betId parameter does not exist.
429	Service overloaded	`bet` `win` `promoWin` `closeMatch`	Yes	Service is overloaded with requests.

Client errors 5XX

HTTP Status	Error text	Resending	Description
500	<Any server error>	Yes	Any server error not described below.
501	Method not supported	No	The request was sent by an unsupported HTTP method (i.e. any non-POST method).
503	Service unavailable	Yes	Server is temporarily unavailable.

Error example

HTTP/1.1 400 Bad Request

{
  "message": "Invalid session token"
}

Seamless Wallet API introduction​

IP Whitelisting & Firewalls​

Seamless Wallet API methods​

/health​

Example of the request​

/playerInfo​

Example of the request​

Example of a response from the server​

/bet​

Example of the request​

Example of a response from the server​

/win​

Example of the request​

Example of a response from the server​

/transactions/promoWin​

Example of the request​

Example of a response from the server​

/closeMatch (optional)​

Example of the request​

Example of a response from the server​

Error processing​

Client errors 4XX​

Client errors 5XX​

Error example​

Seamless Wallet API introduction

IP Whitelisting & Firewalls

Seamless Wallet API methods

/health

Example of the request

/playerInfo

Example of the request

Example of a response from the server

/bet

Example of the request

Example of a response from the server

/win

Example of the request

Example of a response from the server

/transactions/promoWin

Example of the request

Example of a response from the server

/closeMatch (optional)

Example of the request

Example of a response from the server

Error processing

Client errors 4XX

Client errors 5XX

Error example