Seamless Wallet Explained
How To - build an idempotent service against an operator where the operator holds the wallet and the game provider remotely operates the wallet API.Use the right arrow key to show the next slide
Step by step (GAME LAUNCH)   - Flowchart -
1 - Player performs login at operator's site(Login - operator's site)
2 - Player chooses a game and performs game launch(Game load - operator's site)Here the operator will create a unique authentication 
"token"
used to validate the server-to-server calls (cont. step 4).
eg. https://[host]/[path]?operatorid=aggregatedfun1&lang=se&token=82391b6f36374f55bf8f3e69a8444e55&gameref=baccarat
3 - Game provider's server receives the HTTP [ GET ] call from the operator's client and sends the initial call's parameters to the operators wallet server as an 
"authentication"
call(Game load - provider's client)Here the game provider normally initiates loading the game client for the player.
4 - Operator receives the
"authentication"
call from the game provider's server and will optionally (*) respond with the player's balance(Authentication - operator's server)Here the operator will validate the
"token"
parameter and retrieve the players balance and send a response that contains the players balance, currency and display name.
* The authenticate call could also just return the status and a second call can be made to retrieve the players balance.
5 - Game provider receives the balance from the operator and finalizes the loading of the game providers game client(Game load - provider's client)Here the game provider has received all the information needed to present the player with a fully loaded game client that can receive player input.
Step by step (BET)   - Flowchart -
6 - Player performs a bet in the game client(Game play - provider's client)Here the player will decide what kind of bet to perform.
7a - The game provider receives the player's bet from the game client and the game provider sends a
"bet"
call to the operator(Game play - provider's server)Here the game provider will call the operator's wallet API to perform a 
"bet"
(DEBIT) action upon the player's wallet.
8a - The operator will process the bet (DEBIT) request if the parameters in the call are accepted and respond with the new balance(Game play - operator's server)Here the operator validates the
"gameid", "userid", "amount", "channel", "roundid" and "transid"
parameters and responds with the new balance if the parameters are valid and the player's wallet has enough funds.
9 - The game provider receives the new balance and updates the game client accordingly(Game play - providers's client)Here the provider normally update the game client, ie. updates the game client's balance and bet fields.
Step by step (WIN)   - Flowchart -
10a - The game provider has a bet to act upon, calculates an outcome and then sends a 
"win"
call to the operator's wallet API which will respond with the player's new balance(Game play - operator's server)Here the operator validates the
"gameid", "userid", "amount", "channel", "roundid" and "transid"
parameters and responds with the new balance if the parameters are valid (CREDIT).
11a - The game provider receives the new balance and updates the game client accordingly(Game play - provider's client)Here the operator normally updates the game client, ie. stops the reels and updates the game client's balance and win fields.
Step by step (BET - TIMEOUT - ROLLBACK)   - Flowchart -
7b - The game provider receives the player's bet from the game client and the game provider sends a
"bet"
call to the operator's wallet API(Game play - provider's server)WALLET SERVER DOWN - no response from operator.
8b - The game provider's 
"bet"
call to the operator's wallet API now times out(Game play - provider's server)Here the provider normally changes the call type to 
"rollback"
and retries the call with predetermined intervals (2 sec, 5 sec, 60 sec, 600 sec, 600 sec, ....).
[ NOTE ] The
"rollback"
call must be retried until the operator has responded. Here the game provider updates the game client with an error and closes the current game client session.
Step by step (WIN - TIMEOUT - RETRY)   - Flowchart -
10b - The game provider has a bet to act upon (same as step 10a), calculates an outcome and then sends a 
"win"
call to the operator's wallet API(Game play - provider's server)WALLET SERVER DOWN - no response from operator.
11b - The game provider's 
"win"
call to the operator's wallet API now times out(Game play - operator's server)Here the provider normally retries the call with predetermined intervals (2 sec, 5 sec, 60 sec, 600 sec, 600 sec, 600 sec, ....).
[ NOTE ] This call must be retried until the operator has responded. Here the game provider updates the game client with an error and closes the current game client session. If the win call could be completed after the 5 sec interval (decided by provider) then the game session can be kept and the game play can continue.
Request <--> Response (GAME LAUNCH)
Request
// Wallet API request used in step 3
// HTTP [POST]

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="authenticate">
      <token>82391b6f36374f55bf8f3e69a8444e55</token>
      <username>provider_username</username>
      <password>provider_password</password>
   </request>
</n2xsd:n2root>
Response
// Wallet API response used in step 4

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="authenticate">
      <userid>jandoe12345</userid>
      // Success
      <displayname>JigglyPuff</username>
      <currency>EUR</currency>
      <balance>10000</balance>
      // Failure (Parameter validation error)
      <status>ERROR</status>
      <code>1001</code>
   </request>
</n2xsd:n2root>
Request <--> Response (BET)
Request
// Wallet API request used in step 7
// HTTP [POST]

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="bet" roundid="1" transactionid="1">
      <userid>jandoe12345</userid>
      <gameref>baccarat</gameref>
      <username>provider_username</username>
      <password>provider_password</password>
      <channel>desktop</channel>
      <currency>EUR</currency>
      <amount>1200</amount>
   </request>
</n2xsd:n2root>
Response
// Wallet API response used in step 8

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="bet" roundid="1" transactionid="1">
      <userid>jandoe12345</userid>
      // Success
      <balance>8800</balance>
      // Failure (Not sufficient funds)
      <status>ERROR</status>
      <code>1002</code>
   </request>
</n2xsd:n2root>
Request <--> Response (WIN)
Request
// Wallet API request used in step 7
// HTTP [POST]

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="win" roundid="1" transactionid="2">
      <userid>jandoe12345</userid>
      <gameref>baccarat</gameref>
      <username>provider_username</username>
      <password>provider_password</password>
      <channel>desktop</channel>
      <currency>EUR</currency>
      <amount>2200</amount>
   </request>
</n2xsd:n2root>
Response
// Wallet API response used in step 8

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="win" roundid="1" transactionid="2">
      <userid>jandoe12345</userid>
      // Success
      <balance>11000</balance>
      // Failure (No matching bet transaction found)
      <status>ERROR</status>
      <code>1003</code>
   </request>
</n2xsd:n2root>
Request <--> Response (ROLLBACK)
Request
// Wallet API request used in step 7
// HTTP [POST]

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="rollback" roundid="1" transactionid="1">
      <userid>jandoe12345</userid>
      <username>provider_username</username>
      <password>provider_password</password>
   </request>
</n2xsd:n2root>
Response
// Wallet API response used in step 8

<?xml version="1.0" encoding="utf-16"?>
<n2xsd:n2root xmlns:n2xsd="urn:n2ns">
   <request action="rollback" roundid="1" transactionid="1">
      <userid>jandoe12345</userid>
      // Success
      <balance>10000</balance>
      // Failure (Internal error)
      <status>ERROR</status>
      <code>1004</code>
   </request>
</n2xsd:n2root>
Error codes
To alleviate tracking errors we use error codes:

1001 - Parameter validation error
1002 - Not sufficient funds (NSF)
1003 - No matching bet transaction found
1004 - Internal error
Security concerns
To counter malicious attempts upon the Wallet API:

1. All communication is performed using SSLv3 (or TLS1.2).
2. All communication is whitelisted (IP-blocking - opened by operator).
3. All API calls are authenticated by using the provider's authentication details (given by provider).
4. The game session is authenticated using the token (generated by operator on initial game load).
5. All API calls are validated using roundid and transactionid to prevent replay attacks (https://en.wikipedia.org/wiki/Replay_attack).
Extendability
Please note that this Seamless Wallet API specification is a proposal that aims to cover the most basic cases that usually occur while communicating with a Seamless wallet API.
Thus there is room for changes and addons to this general communication scheme.
Seamless API Version 1.0
@Author - Rikard Lagerman (rikard.lagerman@plaingaming.com)
@Reviewed by - Tommy Corbett (tommy.corbett@plaingaming.com)
Appendix
   - BACK -
   - BACK -
   - BACK -
   - BACK -
   - BACK -