View
20
Download
0
Category
Preview:
Citation preview
TECHNICAL GUIDE Web Service API
Version 1.0.0 The information presented herein this document is Confidential Information of SimplePlay created and owned by SimplePlay and is also protected by copyright and applicable laws. Unauthorised use, copying, transmission and disclosure of such information to any person is strictly prohibited without SimplePlay’s prior written consent. In the absence of any specific agreement to the contrary, reverse engineering, recompilation and disassembly are prohibited in any event as to any information or software content/materials provided by SimplePlay. While all efforts have been made to ensure that the content of this document is accurate at the time of publication, the data upon which this document is based is subject to future change at the sole and discretion of SimplePlay. Updated version of this document will be released when necessary, resources permitting.
TECHNICAL GUIDE
Content 1. Introduction 4
2. Version 4
3. API Calling Restriction Information 4 Accuracy of point value 4
4. Encryption Procedures 4 Encryption Requirements 4 Encryption Procedures 6 Example to call API 6 Error handling 8
5. Web service interface 9 User Account Manipulation 9
RegUserInfo 9 VerifyUsername 10 GetUserStatus 11 SetUserMaxBalance 13 SetUserMaxWinning 13
Login Access 14 LoginRequest 14 LoginRequestForFun 17 KickUser 19
Bet Records Query 19 GetAllBetDetails 20
BetDetail structure 20 GetAllBetDetailsForTimeInterval 22 GetUserBetAmount 23 GetUserWinLost 24 GetTransactionDetails 25 GetSlotDetailsURL 26 GetFishermenGoldBetDetails 27
Miscellaneous Functions 29 JackpotQuery 29
Transfer Wallet 30 DebitBalance 30 DebitAllBalance 31 CreditBalance 32
Copyright © SimplePlay 2019 All right reserved 2/52
TECHNICAL GUIDE
CheckOrderId 33
6. Seamless Wallet Integration 34 Introduction 34 Workflow 34 Seamless Wallet Protocol 35
Encryption procedures 36 ASP.Net version 36 PHP version 36
POST 37 Response data 38
GetUserBalance 38 Fund Transfer 39
PlaceBet 39 PlayerWin 42 PlayerLost 43 PlaceBetCancel 44
Important notice 47 Error code list 47
7. Error message code reference 48
8. Game Launching Procedures 50 Slot Game 50 Fishing Game 50
9. Slot Game ID/Game Code to Game mapping 51
10. Supported currencies 51
Copyright © SimplePlay 2019 All right reserved 3/52
TECHNICAL GUIDE
1. Introduction
The Web Service API interface is for accessing the SimplePlay Platform. Including user registration, user balance query, user betting records and charging to or withdraw from a user account. This document includes both Transfer Wallet and Seamless Wallet.
2. Version
Version Description Date
1.0.0 Initial version 2019/05/09
3. API Calling Restriction Information
The following APIs have calling restriction.
Name of API Frequency of calls
GetAllBetDetails Every 5 minutes no more than 5 calls
GetAllBetDetailsForTimeInterval Every 5 minutes no more than 5 calls
JackpotQuery Every 1 minute no more than 1 call
Accuracy of point value
The accuracy of all point value is limited to two decimal places. For example: 1000.23, 89.32, 1002304.89
4. Encryption
4.1 Encryption Requirements
All of the web service queries require DES encryption and MD5 hashing before sending to ensure the content has no modification during transmission. Please ask us for the following information:
1. Secret Key
Copyright © SimplePlay 2019 All right reserved 4/52
TECHNICAL GUIDE
2. EncrypKey 3. MD5Key 4. API URL 5. Lobby game client loader 6. Lobby name (supplied during startup the client)
Example DES Encrypt function: protected byte [] EncryptKey = ASCIIEncoding .ASCII.GetBytes( "ask_us_for_key" );
public string DESEncrypt( string inString)
{
MemoryStream ms = new MemoryStream ();
CryptoStream cs = new CryptoStream (ms, new
DESCryptoServiceProvider ().CreateEncryptor(EncryptKey, EncryptKey),
CryptoStreamMode .Write);
StreamWriter sw = new StreamWriter (cs);
sw.Write(inString);
sw.Flush();
cs.FlushFinalBlock();
sw.Flush();
return Convert.ToBase64String(ms.GetBuffer(), 0, ( int )ms.Length);
}
DES Encrypt function in PHP
Example in PHP
TECHNICAL GUIDE
echo "[ $str ] Encrypted: [ $mstr ] UrlEncoded encrypted string: [ $urlemstr ]";
?>
Example MD5 function: public string BuildMD5( string inString)
{
byte [] hashed = MD5 .Create().ComputeHash( Encoding .UTF8.GetBytes(inString));
StringBuilder sb = new StringBuilder (hashed.Length * 2);
for ( int i = 0; i < hashed.Length; i++)
{
sb.Append(hashed[i].ToString( "x2" ));
}
return sb.ToString();
}
Example in PHP
4.2 Encryption Procedures
1. Construct a Query String (QS) with required parameters (including the web service
method name itself (e.g. method=RegUserInfo)
2. DES encrypts the Query String with the supplied EncryptKey and obtain the encrypted
query string (q)
3. Build an MD5 hash according to (QS) and other parameters to form a signature (s)
4. Use HTTP POST request to call the web service.
5. Obtain the resulting XML response.
4.3 Example to call API
Let’s take RegUserInfo as an example:
Encryption required parameters:
Copyright © SimplePlay 2019 All right reserved 6/52
TECHNICAL GUIDE
method (String, “RegUserInfo”)
Key (String, the Secret Key)
Time (DateTime, Current Time, in yyyyMMddHHmmss format)
Username (String)
method, Key and Time are always inserted. Other parameters please follow the parameter list in each API function. Let say, the Secret Key is XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX and md5key is YYYYYYYY. Example Query String (QS): QS =
“method=RegUserInfo&Key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&Time=20140101123456&U
sername=DemoUser001”;
q = HttpUtility.UrlEncode( DESencrypt(QS) );
For example, q = 'j4tjorjwarfj3trwise0safrwg2wt4awari0fwjfeoh'
Example MD5 String for building the signature (QS + md5key + Time + Key): s = BuildMD5(QS + “YYYYYYYY” + “20140101123456” +
“XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX”);
For example, s = '1234567890abcdef' Resulting POST method query (using “Content-Type: application/x-www-form-urlencoded”):
q=j4tjorjwarfj3trwise0safrwg2wt4awari0fwjfeoh&s=1234567890abcdef POST to: http:///api/api.aspx Output:
DemoUser001
0
Success
Copyright © SimplePlay 2019 All right reserved 7/52
TECHNICAL GUIDE
4.4 Error handling
When we received the q and s, if it is decrypted with an error or the md5 is not match, a generic error response will be output.
ErrorMsgId 128 for decryption error. ErrorMsgId 132 for md5 sign unmatch.
128
Decryption error
Copyright © SimplePlay 2019 All right reserved 8/52
TECHNICAL GUIDE
5. Web service interface
All services require a secret key to access. Please contact us to get one.
5.1 User Account Manipulation
5.1.1 RegUserInfo
Create a user by username and currency type.
Parameters:
Copyright © SimplePlay 2019 All right reserved 9/52
TECHNICAL GUIDE
Name Description Type and Limit Required?
method must be “RegUserInfo” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name. Alphanumeric (5~20 characters)
String (20) Y
CurrencyType Currency: CNY USD Refer to 10. Supported currencies
String (4) Y
Result:
Name Description Type and Limit Required?
Username User name String Y
ErrorMsgId Error message: 0: Success 108: Username length/format incorrect 113: Username duplicated 114: Currency not exist 133: Create user failed
Byte Y
ErrorMsg Error message detail String Y
5.1.2 VerifyUsername
Check if a username is already existing in the database of a lobby.
Parameters:
Name Description Type and Limit Required?
method must be “VerifyUsername” String (32) Y
Key secret key String (32) Y
Time current time in DateTime Y
Copyright © SimplePlay 2019 All right reserved 10/52
TECHNICAL GUIDE
“yyyyMMddHHmmss” format
Username User name String (20) Y
Result:
Name Description Type and Limit Required?
IsExist User exist? True: user existing False: user not existing
Bool Y
Username User name String Y
ErrorMsgId Error message: 0: Success 108: Username length/format incorrect
Byte Y
ErrorMsg Error message detail String Y
Output:
True
DemoUser001
0
Success
5.1.3 GetUserStatus
The status of a user including:
● Online/offline ● Bet exist ● Bet amount and remain balance ● Maximum balance ● Maximum daily winning
Parameters:
Name Description Type and Limit Required?
Copyright © SimplePlay 2019 All right reserved 11/52
TECHNICAL GUIDE
method must be “GetUserStatus” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
Result:
Name Description Type and Limit Required?
IsSuccess Success? True: Success False: Failed
Bool Y
Username User name String Y
Balance Active balance, excluding the betted amount. Correct to the cent.
Decimal Y
Online Online? Bool Y
Betted Betted? Bool Y
BettedAmount Total betted amount Decimal Y
MaxBalance The upper limit in user's balance to place bet
Decimal Y
MaxWinning Daily winning limitation to allow place bet Decimal Y
ErrorMsgId Error message 0: Success 100: Username error 108: Username length/format incorrect 116: Username does not exist
Byte Y
ErrorMsg Error message detail String Y
Output:
True
Copyright © SimplePlay 2019 All right reserved 12/52
TECHNICAL GUIDE
DemoUser001
1234567.89
False
False
0
0
Success
5.1.4 SetUserMaxBalance
Set the maximum balance limit to a user. This only apply to transfer wallet.
Parameters:
Name Description Type and Limit Required?
method must be “SetUserMaxBalance” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
MaxBalance Maximum balance Decimal Y
Result:
Name Description Type and Limit Required?
ErrorMsgId Error message 0: Success 116: Username does not exist 142: Parameter(s) error 148: MaxBalance not zero or smaller than user balance
Byte Y
ErrorMsg Error message detail String Y
5.1.5 SetUserMaxWinning
Set the user’s maximum daily winning. User cannot place a bet if his winning
exceeds this setting.
Copyright © SimplePlay 2019 All right reserved 13/52
TECHNICAL GUIDE
Parameters:
Name Description Type and Limit Required?
method must be “SetUserMaxWinning” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
MaxWinning Maximum daily winning Decimal Y
Result:
Name Description Type and Limit Required?
ErrorMsgId Error message 0: Success 116: Username does not exist 142: Parameter(s) error
Byte Y
ErrorMsg Error message detail String Y
5.2 Login Access
5.2.1 LoginRequest
It is the function to request the login token. If the username doesn’t exist, it will be created automatically.
Parameters:
Name Description Type and Limit Required?
method must be “LoginRequest” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
Copyright © SimplePlay 2019 All right reserved 14/52
TECHNICAL GUIDE
(5 ~ 20 characters)
CurrencyType Currency: CNY USD Refer to 10. Supported currencies
String (4) Y
GameCode Game code string, refer to Section 9.
String (16) N
Lang Language code String N
Mobile Mobile version 1 - Enable mobile 0 - Disable mobile
Bool N
Lang parameter:
Language Description
zh_TW Traditional Chinese
zh_CN Simplified Chinese
en_US English
th Thai
vn Vietnamese
jp Japanese
id Bahasa Indonesia
it Italiano*
ms Malay*
es Spanish*
* Only support Fishing game
Result:
Copyright © SimplePlay 2019 All right reserved 15/52
TECHNICAL GUIDE
Name Description Type and Limit Required?
Token Token for login# String Y
DisplayName* Internally assigned username String (31) Y
GameURL Complete URL to launch Slot Game or Fishing game. Follow the different instruction to launch the games: Slot Game launching instruction Fishing Game launching instruction
String N
ErrorMsgId Error message 0: Success 129: System under maintenance 130: User account is locked (disabled) 133: Create user failed 134: Game code not found 135: Game access denied
Byte Y
ErrorMsg Error message detail String Y
# If login request failed, there is no Token node in the response. * All username will be added a suffix @XX. The DisplayName will be the actual username in our database. You must provide this DisplayName to later login to our server! ^If no supply the GameCode or GameCode invalid, there is no GameURL node in the response. You have to check if this node existing.
Output:
Without GameCode parameter
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
”cstest@cs”
0
Success
Copyright © SimplePlay 2019 All right reserved 16/52
TECHNICAL GUIDE
With GameCode parameter
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
”cstest@cs”
http://www.xxxxx.com/game001/play.html?name=peter&token=1231231
23”
0
Success
5.2.2 LoginRequestForFun
Login to the system in Fun mode. The username will be generated automatically.
Parameters:
Name Description Type and Limit Required?
method must be “LoginRequestForFun” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Amount Initial amount Decimal Y
CurrencyType ISO Currency ID String (4) Y
GameCode Game code string, refer to Section 9.
String (16) N
Lang Language code String N
Mobile Mobile version 1 - Enable mobile 0 - Disable mobile
Bool N
Result:
Name Description Type and Limit
Required?
Token Token for login# String Y
Copyright © SimplePlay 2019 All right reserved 17/52
TECHNICAL GUIDE
DisplayName* Internally assigned username String (31) Y
GameURL^ URL to launch the slot game To start the slot game please refer to Slot Game launching instruction Or Fishing Game launching instruction
String N
ErrorMsgId Error message 0: Success 129: System under maintenance 134: Game code not found 135: Game access denied
Byte Y
ErrorMsg Error message detail String Y
^If no supply the GameCode or GameCode invalid, there is no GameURL node in the response. You have to check if this node existing.
Output:
sa-test1@xx
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0
Success
With GameCode parameter output:
sa-test1@xx
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
http://www.xxxxx.com/game001/play.html?name=peter&token=1231231
23”
0
Success
Copyright © SimplePlay 2019 All right reserved 18/52
TECHNICAL GUIDE
5.2.3 KickUser
Kick user to offline.
Parameters:
Name Description Type and Limit Required?
method must be “KickUser” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
Result:
Name Description Type and Limit Required?
ErrorMsgId Error message 0: Success 102: Secret key incorrect 104: Service not available 108: Username length/format incorrect 116: Username does not exist 125: Kick user fail
Byte Y
ErrorMsg Error message detail String Y
Output:
0
Success
5.3 Bet Records Query
Copyright © SimplePlay 2019 All right reserved 19/52
TECHNICAL GUIDE
5.3.1 GetAllBetDetails
This Web service will fetch bet details for the current lobby of the specified date from 12:00 PM to 11:59:59 AM. If no Date input, the current date will be used. The frequency of the call should be made to this API 5 times per 5 minutes otherwise it will throw an error.
Parameters:
Name Description Type and Limit
Required?
method must be “GetAllBetDetails” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username (optional)
User name String (20) N
Date (optional) Date for details “yyyy-MM-dd”
Date N
Result:
Name Description Type and Limit Required?
BetDetailList Bet details structure XML Y
ErrorMsgId Error message 0: Success 108: Username length/format incorrect 112: API recently called 116: Username does not exist 128: Decryption error 142: Parameter(s) error
Byte Y
ErrorMsg Error message detail String Y
BetDetail structure
Name Description Type and Limit Required?
Copyright © SimplePlay 2019 All right reserved 20/52
TECHNICAL GUIDE
BetTime Bet start time Date Time Y
PayoutTime Payout Time DateTime Y
Username Player name String(31) Y
Detail Slot Game: Slot game code Fishing Game: Game code
String N
GameID Game ID String Y
BetID Bet ID Int64 Y
BetAmount Bet amount Decimal Y
Rolling Rolling Decimal Y
ResultAmount Payout Decimal Y
Balance Balance after this bet Decimal Y
GameType Game type: slot - Slot Game multiplayer - Fishing Game
String Y
BetSource
2 / 2114 /2640
Web
16 / 600/ 8792/8793
HTML5 Mobile Web
1160/1161/5248/5249
iOS app
1288/1289/5379/5377
Android app
Int Y
TransactionID Seamless wallet PlaceBet transaction ID. -1 if not using a seamless wallet
Int64 Y
Output:
Copyright © SimplePlay 2019 All right reserved 21/52
TECHNICAL GUIDE
2014-01-01T00:00:00
2014-01-01T00:01:12
DemoUser001
EG-SLOT-A001
1234567890123456
1234567890
123.45
123.45
434456.35
246.90
slot
2
-1
0
Success
5.3.2 GetAllBetDetailsForTimeInterval
This web service will fetch bet details of a lobby for a time interval maximum of 24 hours. The frequency of the call should be made to this API 5 times per 5 minutes otherwise it will throw an error.
Parameters:
Name Description Type and Limit Required?
method must be “GetAllBetDetailsForTimeInterval” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format DateTime Y
Username (optional)
User name String (20) N
FromTime Date for details “yyyy-MM-dd hh:mm:ss”
DateTime Y
ToTime Date for details “yyyy-MM-dd hh:mm:ss”
DateTime Y
Result:
Copyright © SimplePlay 2019 All right reserved 22/52
TECHNICAL GUIDE
Name Description Type and Limit Required?
BetDetailList Bet details structure XML Y
ErrorMsgId Error message 0: Success 108: Username length/format incorrect 111: Query time range out of limitation 112: API recently called 116: Username does not exist 142: Parameter(s) error
Byte Y
ErrorMsg Error message detail String Y
5.3.3 GetUserBetAmount
This Web service will fetch the stake amount for a lobby.
Parameters:
Name Description Type and Limit Required?
method must be “GetUserBetAmount” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) N
StartDate Start time (default current date) DateTime N
TimeRange Range in hour from 0 to 23 (default 0 = 24 hours)
Int N
Result: A series of follow records will return.
Name Description Type and Limit
Required?
Username user name String (31) Y
StakeAmount Sum of bet amount for all games Decimal Y
Copyright © SimplePlay 2019 All right reserved 23/52
TECHNICAL GUIDE
ErrorMsgId Error message 0: Success 108: Username length/format incorrect 116: Username does not exist
Byte Y
ErrorMsg Error message detail String Y
Output:
user001
1105.45
0
Success
5.3.4 GetUserWinLost
This API function is to get a user’s win/loss summary for a period of time with a maximum of 31 days.
Parameters:
Name Description Type and Limit Required?
method must be “GetUserWinLost ” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
FromTime Start date and time DateTime Y
ToTime End of date and time DateTime Y
Type 0 - includes win and loss Int N
Copyright © SimplePlay 2019 All right reserved 24/52
http://www.w3.org/2001/XMLSchema-instance
TECHNICAL GUIDE
1 - only includes win 2 - only includes loss
Result:
Name Description Type and Limit Required?
Username Username String (20) Y
Winlost Win or loss summary value Decimal Y
ErrorMsgId Error message 0: Success 106: Server not ready 108: Username length/format incorrect 111: Query time range out of limitation 116: Username does not exist 144: Query type invalid
Byte Y
ErrorMsg Error message detail String Y
5.3.5 GetTransactionDetails
This web service will fetch the transaction details of a lobby for a time interval maximum of 31 days. You may specify a username to query transaction details of a certain user.
Parameters:
Name Description Type and Limit Required?
method must be “GetTransactionDetails ” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username (optional)
User name String (20) N
FromTime Start date and time DateTime Y
ToTime End of date and time DateTime Y
Result:
Copyright © SimplePlay 2019 All right reserved 25/52
TECHNICAL GUIDE
Name Description Type and Limit Required?
Count Number of transactions Integer 32bit Y
Winlost Win/lose Decimal Y
TotalBet Total bet amount Decimal Y
ErrorMsgId Error message 0: Success 106: Server not ready 111: Query time range out of limitation 116: Username does not exist
Byte Y
ErrorMsg Error message detail String Y
5.3.6 GetSlotDetailsURL
This web service will generate the URL for display the game details of one Bet ID.
Parameters:
Name Description Type and Limit Required?
method must be “GetSlotDetailsURL ” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
BetID Bet ID of the slot game String (20) Y
Result:
Name Description Type and Limit Required?
URL Full URL to display the details report String Y
ErrorMsgId Error message 0: Success 153: Bet ID not existing
Byte Y
ErrorMsg Error message detail String Y
Copyright © SimplePlay 2019 All right reserved 26/52
TECHNICAL GUIDE
5.3.7 GetFishermenGoldBetDetails
This Web service will fetch bet details for one fishing game session.
Parameters:
Name Description Type and Limit Required?
method must be “GetFishermenGoldBetDetails” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
GameId Fishermen Gold game id String Y
Page Page of record, start from giving 0 Int Y
Result: A series of following records will be returned.
Name Description Type and Limit Required?
BetAmount Total bet amount (Coin) Int64 Y
WinAmount Total winning amount (Coin) Int64 Y
Currency Currency String (4) Y
ExchangeRate Coin to currency exchange rate Int Y
Count Total bullet record count Int Y
ItemCount Number of items queried Int Y
Limit Number of item per page Int Y
BulletDetailsList List of the structure of a bullet details XML Y
ErrorMsgId Error message 0: Success 102: Secret key incorrect 106: Server not ready 152: Game Id does not exist
Byte Y
Copyright © SimplePlay 2019 All right reserved 27/52
TECHNICAL GUIDE
ErrorMsg Error message detail String Y
BulletDetails structure:
Name Description Type and Limit Required?
Denom Denomination Int Y
ID Bullet ID Int64 Y
Multiplier Multiplier Int Y
Cost Cost of the bullet (Coin) Int Y
Reward The reward of the bullet (Coin) Int Y
Species Fish ID Int Y
FreeBulletTotal Total of free bullet Int Y
FreeBulletRemain Remains of free bullet Int Y
FreeBulletReward Rewarded bullet of this shoot Int Y
Output:
2700
500
CNY
1000
35
20
20
50
00000000010537
2
100
0
10
0
0
user001
Copyright © SimplePlay 2019 All right reserved 28/52
http://www.w3.org/2001/XMLSchema-instance
TECHNICAL GUIDE
............
............
............
0
Success
5.4 Miscellaneous Functions
5.4.1 JackpotQuery
This API function is to request to the Slot Jackpot meter in different currencies. The frequency of the call should be made to this API after every 1 minute otherwise it will throw an error.
Parameters:
Name Description Type and Limit Required?
method must be “JackpotQuery” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Currency Currency: CNY USD Refer to 10. Supported currencies
String (4) N
Result:
Name Description Type and Limit Required?
Major Major meter (in cents) Int64 Y
Minor Minor meter (in cents) Int64 Y
Mini Mini meter (in cents) Int64 Y
ErrorMsgId Error message 0: Success
Short Y
Copyright © SimplePlay 2019 All right reserved 29/52
TECHNICAL GUIDE
104: Service is not available
ErrorMsg Error message detail String Y
5.5 Transfer Wallet
The Transfer wallet API includes a transfer in, out and order status checking functions. Throughout those functions, there is an OrderID inside each of them. In case a transfer was failed due to network problem and become unsuccessful, be sure to use the same OrderID to initiate another try. We guarantee the same OrderID will be processed twice. Using a new OrderID for the same transfer may cause the duplicated transfer. Even you have checked the OrderID not existing by using CheckOrderID, you should still use the same OrderID.
5.5.1 DebitBalance
Transfer from the user’s balance.
Parameters:
Name Description Type and Limit Required?
method must be “DebitBalance” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name Alphanumeric (5~20 characters)
String (20) Y
OrderId Order ID: OUT+YYYYMMDDHHMMSS+Username e.g. “OUT20131129130345peter1235”
String (40) Y
DebitAmount Debit amount. Maximum two decimal only.
Decimal Y
Result:
Name Description Type and Limit
Required?
Copyright © SimplePlay 2019 All right reserved 30/52
TECHNICAL GUIDE
Username User name String Y
Balance Remained active balance Decimal Y
DebitAmount Debited amount. Decimal Y
OrderId Order ID String (40) Y
ErrorMsgId Error message 0: Success 106: Server not ready. Try again later. 108: Username length/format incorrect 116: Username does not exist 120: Amount must be larger than zero 121: Not enough points to credit/debit 122: Order ID already exists 124: Database error 127: Invalid order ID format 142: Error Parameter 145: Parameter decimal point greater than 2
Byte Y
ErrorMsg Error message detail String Y
5.5.2 DebitAllBalance
Transfer all amount from the user’s balance.
Parameters:
Name Description Type and Limit Required?
method must be “DebitAllBalance” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
OrderId Order ID: OUT+YYYYMMDDHHMMSS+Username e.g. “OUT20131129130345peter1235”
String (40) Y
Copyright © SimplePlay 2019 All right reserved 31/52
TECHNICAL GUIDE
Result:
Name Description Type and Limit Required?
Username User name String Y
DebitAmount Debited amount. Decimal Y
OrderId Order ID String (40) Y
ErrorMsgId Error message 0: Success 106: Server not ready. Try again later. 108: Username length/format incorrect 116: Username does not exist 122: Order ID already exists 124: Database error 127: Invalid order ID format
Byte Y
ErrorMsg Error message detail String Y
5.5.3 CreditBalance
Transfer fund to user’s balance.
Parameters:
Name Description Type and Limit Required?
method must be “CreditBalance” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Username User name String (20) Y
OrderId Order ID: IN+YYYYMMDDHHMMSS+Username e.g. “IN20131129130345peter1235”
String (40) Y
Copyright © SimplePlay 2019 All right reserved 32/52
TECHNICAL GUIDE
CreditAmount Credit amount. Decimal Y
Result:
Name Description Type and Limit
Required?
Username User name String Y
Balance Remained active balance Decimal Y
CreditAmount Credited amount. Decimal Y
OrderId Order ID String (40) Y
ErrorMsgId Error message 0: Success 106: Server not ready. Try again later. 108: Username length/format incorrect 116: Username does not exist 120: Amount must be larger than zero 121: Not enough points to credit/debit 122: Order ID already exists 124: Database error 127: Invalid order ID format 142: Error Parameter 145: Parameter decimal point greater than 2
Byte Y
ErrorMsg Error message detail String Y
5.5.4 CheckOrderId
Check the OrderId that generated in DebitBalance/DebitAllBalance/CreditBalance is existing or not in our system.
Parameters:
Name Description Type and Limit Required?
method must be “CheckOrderId” String (32) Y
Key secret key String (32) Y
Time current time in “yyyyMMddHHmmss” format
DateTime Y
Copyright © SimplePlay 2019 All right reserved 33/52
TECHNICAL GUIDE
OrderId The OrderId used in ● DebitBalance ● DebitAllBalance ● CreditBalance
String (40) Y
Result:
Name Description Type and Limit Required?
isExist The OrderId exist or not ● true - existing ● false - not existing
Bool Y
ErrorMsgId Error message 0: Success 106: Server not ready. Try again later. 124: Database error
Byte Y
ErrorMsg Error message detail String Y
6. Seamless Wallet Integration
6.1 Introduction
This section is to illustrate the detail of implementing seamless wallet in external partner system. Important: While probably obvious, it’s worth stating that when Seamless Wallet is in use, the CreditBalance/DebitBalance/DebitAllBalance API should not be used to modify a player’s balance.
6.2. Workflow
Basically, the partner system has to provide a set of API functions for our system to call:
1. GetUserBalance 2. Fund Transfer
GetUserBalance will be called when the user login to our platform or user click refresh balance in the web client. Fund Transfer function includes four types of transfer:
1. PlaceBet
Copyright © SimplePlay 2019 All right reserved 34/52
TECHNICAL GUIDE
It is sent to the partner system when the user going to place a bet. The function will be timed out after 3 seconds and PlaceBetCancel will be sent.
2. PlayerWin When a bet placed before is winning, the total amount (including stakes) will send to partner system. If there are timeout or error, the request will be retried after n seconds within m tries. An expired request will move to the unsuccessful transaction list for the back office to further process. Those unsuccessful transactions can be retired by the operator through the back office.
3. PlayerLost When a bet placed before is losing, this request will be sent to the partner system. Although it is no amount adjustment, it is still worth to let partner system to update the state of an open transaction. If there are timeout or error, the request will be retried after n seconds within m tries. An expired request will move to the unsuccessful transaction list for the back office to further process. Those unsuccessful transactions can be retry by the operator through the back office.
4. PlaceBetCancel PlaceBetCancel will only be sent when previous PlaceBet is failed due to timeout or partner system error. Partner system should refund the user if the transaction has been done in the partner system side. If there are timeout or error, the request will be retried after n seconds within m tries. An expired request will move to the unsuccessful transaction list for the back office to further process. Those unsuccessful transactions can be retry by the operator through the back office.
All above Fund Transfer functions provide a unique transaction ID and partner system should only process once and only once, but must always respond. SimplePlay platform assumes that the partner system will handle duplicate transaction request properly and send back a success response for a request that had already been processed. Operator should provide these five individual aspx, php, etc. to allow SimplePlay platform to call: E.g.
/GetUserBalance.aspx, /PlaceBet.aspx, /PlayerWin.aspx, /PlayerLost.aspx and /PlaceBetCancel.aspx
** Operator can only use ONE type of extension, no multiple extension is allowed.
6.3 Seamless Wallet Protocol
SimplePlay platform will use an HTTP POST request to communicate with the external wallet. All of the parameters will be encrypted and pass as a text value.
Copyright © SimplePlay 2019 All right reserved 35/52
TECHNICAL GUIDE
The following is an example of a request string that SimplePlay platform sends to the external wallet before encryption:
username=peter1234¤cy=CNY
6.3.1 Encryption procedures
We will use DES CBC encryption. The following are the example of DES Encrypt/Decrypt function:
ASP.Net version
protected byte [] EncryptKey = ASCIIEncoding .ASCII.GetBytes( "ask_us_for_key" );
public string DESEncrypt( string inString)
{
MemoryStream ms = new MemoryStream ();
CryptoStream cs = new CryptoStream (ms, new
DESCryptoServiceProvider ().CreateEncryptor(EncryptKey, EncryptKey),
CryptoStreamMode .Write);
StreamWriter sw = new StreamWriter (cs);
sw.Write(inString);
sw.Flush();
cs.FlushFinalBlock();
sw.Flush();
return Convert.ToBase64String(ms.GetBuffer(), 0, ( int )ms.Length);
}
public string DESDecrypt( string inString)
{
try
{
return new StreamReader ( new CryptoStream ( new MemoryStream (
Convert .FromBase64String(inString)), new
DESCryptoServiceProvider ().CreateDecryptor(EncryptKey, EncryptKey),
CryptoStreamMode .Read)).ReadToEnd();
}
catch
{
}
return "";
}
PHP version
DES Encrypt/Decrypt function in PHP
TECHNICAL GUIDE
var $key;
var $iv;
function __construct ( $key, $iv=0 ) {
$this ->key = $key;
if ( $iv == 0 ) {
$this ->iv = $key;
} else {
$this ->iv = $iv;
}
}
function encrypt ($str) {
return base64_encode( openssl_encrypt($str, 'DES-CBC' , $this ->key,
OPENSSL_RAW_DATA, $this ->iv ) );
}
function decrypt ($str) {
$str = openssl_decrypt(base64_decode($str), 'DES-CBC' , $this ->key,
OPENSSL_RAW_DATA | OPENSSL_NO_PADDING, $this ->iv);
return rtrim($str, '\x1\x2\x3\x4\x5\x6\x7\x8' );
}
function pkcs5Pad ($text, $blocksize) {
$pad = $blocksize - (strlen ( $text ) % $blocksize);
return $text . str_repeat ( chr ( $pad ), $pad );
}
}
?>
6.3.2 POST
After encrypted the request string, we will POST the encrypted string with urlencoded as plain text:
POST / HTTP/1.0
Content-Type: text/plain
kuVJgHRMSXOT7a7enWsOyki0NTSd7tTraFXJ%2F7xui4V5nWyik20DSurYFWlkzdMGMhbbqkrO5A2o
SUpPWXyrW1yFWFCOdU1GasqDd3WtnWv6htNdXqGw3uIcj%2Bc%2BYUDP2IQIVNL1hQrpytFPyIJisb
Eobll66Wb2IodCT%2Bqq3iDsQeu%2FVd2%2Bb7%2FZjExJOlGisn264ogMCoDsw5ya%2Bo9RDOOLZ6
RS2WHxI99nIOvmkPccx1wGWhT0%2Fw%3D%3D
Partner system have to url decode and decrypt the string by the provided key and perform the requested function.
6.3.3 Response data
Partner system should respond the request in XML format:
Copyright © SimplePlay 2019 All right reserved 37/52
TECHNICAL GUIDE
peter1234
CNY
1532.36
0
6.4 GetUserBalance
This request is sent to the partner system to retrieve the balance of a user.
Input parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except for mXBT String (4) Y
E.g.
username=peter1234¤cy=CNY
Copyright © SimplePlay 2019 All right reserved 38/52
TECHNICAL GUIDE
Response parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except for mXBT String (4) Y
amount Decimal format and max. 2 decimal places Decimal Y
error Error code Int Y
6.5 Fund Transfer
SimplePlay platform makes different fund transfer request to partner system to modify the balance of the player, either to withdraw funds for a bet or to deposit funds for a win.
6.5.1 PlaceBet
When a player makes a bet in a game, SimplePlay platform will send this request to partner system. This request must be responded within 3 seconds, otherwise it is defined as timeout and PlaceBetCancel will be sent to cancel/refund the unsuccessful bet.
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD String (4) Y
amount Amount to bet (decimal format and max. 2 decimal places)
Decimal Y
txnid A unique id for all fund transfer String (16) Y
gametype Game type slot - Slot Game multiplayer - Fishing Game
String Y
platform 0 - desktop 1 - mobile
Byte Y
gamecode Game code of the game String N
Copyright © SimplePlay 2019 All right reserved 39/52
TECHNICAL GUIDE
gameid Game ID String Y
Response parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except for mXBT String (4) Y
amount Amount after adjustment (decimal format and max. 2 decimal places)
Decimal Y
error Error code Int Y
Copyright © SimplePlay 2019 All right reserved 40/52
TECHNICAL GUIDE
Copyright © SimplePlay 2019 All right reserved 41/52
TECHNICAL GUIDE
6.5.2 PlayerWin
When a game completed and the player wins (even bet return when the result is Tie in Baccarat) PlayerWin will send to partner system to adjust the balance of the player. This request will keep trying if the partner system no response or respond error.
Copyright © SimplePlay 2019 All right reserved 42/52
TECHNICAL GUIDE
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD String (4) Y
amount Amount to add back (decimal format and max. 2 decimal places)
Decimal Y
txnid A unique id for all fund transfer String (16) Y
gametype Game type slot - Slot Game multiplayer - Fishing Game
String Y
gamecode Game code of the game String N
Payouttime Time of the payout DateTime Y
gameid Game ID String Y
Response parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except mXBT String (4) Y
amount Amount after adjustment (decimal format and max. 2 decimal places)
Decimal Y
error Error code Int Y
6.5.3 PlayerLost
When a game completed and the player lost (no winning amount,) PlayerLost will be sent to the partner system. Since it is a loss so there is no amount parameter in the request. This request will keep trying if the partner system no response or responding error.
Name Description Type and Required?
Copyright © SimplePlay 2019 All right reserved 43/52
TECHNICAL GUIDE
Limit
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD String (4) Y
txnid A unique id for all fund transfer String (16) Y
gametype Game type slot - Slot Game multiplayer - Fishing Game
String Y
gamecode Game code of the game String N
Payouttime Time of the payout DateTime Y
gameid Game ID String Y
Response parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except mXBT String (4) Y
amount Amount after adjustment (decimal format and max. 2 decimal places)
Decimal Y
error Error code Int Y
6.5.4 PlaceBetCancel
If a PlaceBet request timeout or partner system responded an error, a PlaceBetCancel request will send to partner system. SimplePlay platform will treat it as bet failed and report to the player that his bet has been failed. Partner system must handle this request once and only once and must respond to our platform. In case you cannot find the previous transaction by the txn_reverse_id, you have to send us error = 0, else we will keep sending this request.
Name Description Type and Limit
Required?
Copyright © SimplePlay 2019 All right reserved 44/52
TECHNICAL GUIDE
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD String (4) Y
amount Amount to reverse (decimal format and max. 2 decimal places)
Decimal Y
txnid A unique id for all fund transfer String (16) Y
gametype Game type slot - Slot Game multiplayer - Fishing Game
String Y
gamecode Game code of the game String N
gameid Game ID String Y
txn_reverse_id Previous txnid in PlaceBet request which the response was not received within 3 seconds or responded with an error.
String (16) Y
Response parameters:
Name Description Type and Limit
Required?
username Username of the user String (20) Y
currency ISO 3 characters e.g. CNY/USD. Except mXBT String (4) Y
amount Amount after adjustment (decimal format and max. 2 decimal places)
Decimal Y
error Error code Int Y
Copyright © SimplePlay 2019 All right reserved 45/52
TECHNICAL GUIDE
Copyright © SimplePlay 2019 All right reserved 46/52
TECHNICAL GUIDE
6.6 Important notice
Normally, the PlaceBet and PlayerWin/PlayerLost are paired in the slot game and the fishing game. However, the fishing game does have an exception. In case a player played a round of the fishing game with free bullets remain and logged out. When the player logs into the fishing game later and shoots some bullet, no matter he won or not, if he logged out without transferring fund, a PlayerWin/PlayerLost will send. In this scenario, there is no PlaceBet but PlayerWin/PlayerLost send. It may void your checking for a PlayerWin/PlayerLost to match a PlaceBet by GameID. It is important that you must take care of this situation and make sure you can process the PlayerWin/PlayerLost correctly.
6.7 Error code list
Partner system should report to our platform with the following error codes:
ID Description
0 Success
1000 User account doesn’t exist
1001 Invalid currency
1002 Invalid amount
1003 Locked account
1004 Insufficient balance
1005 General error
1006 Decryption error
1007 Session expired error
9999 System error
Copyright © SimplePlay 2019 All right reserved 47/52
TECHNICAL GUIDE
7. Error message code reference
Common error message code
ID Description
100 Username error
101 Account locked
102 Secret key incorrect
104 Service not available
105 Client side error
106 Server busy. Try again later.
107 Username empty
108 Username length/format incorrect
110 User not online
111 Query time range out of limitation
112 API recently called
113 Username duplicated
114 Currency not exist
116 Username does not exist
120 Amount must greater than zero
121 Not enough points to credit/debit/bet
122 Order ID already exists
125 Kick user fail
127 Invalid order ID format
128 Decryption error
129 System under maintenance
Copyright © SimplePlay 2019 All right reserved 48/52
TECHNICAL GUIDE
130 User account is locked (disabled)
132 Sign unmatch
133 Create user failed
134 Game code not found
135 Game access denied
136 Not enough point to bet
142 Parameter(s) error
144 Query type invalid
145 Parameter decimal point greater than 2
146 API access denied
148 MaxBalance not zero or smaller than user balance
149 Input amount under minimum value
150 Function has been deprecated
151 Duplicate login
152 Game id not existing
153 Bet ID not existing
Copyright © SimplePlay 2019 All right reserved 49/52
TECHNICAL GUIDE
8. Game Launching Procedures
Slot Game
You may use the GameURL returned from LoginRequest or LoginRequestForFun directly to launch the slot game. The following are all parameters used. You are free to append extra parameters to have your needs.
Parameter Description Type Preset?
token Token String Y
name DisplayName or you can specify String Y
language Language to launch the slot, see below String Y
mobile HTML mode (optional) Bool (true/false) Y
lobbycode Lobby code String Y
returnurl The URL will be invoked when the slot logout (optional)
String N
skipintro To skip the introduction video (optional) Bool (1/0) N
Fishing Game
The returned GameURL has been constructed to use directly, however, you may append returnurl=https://www.yourdomain.com/somewhere parameter the same as Slot Game. Moreover, you can control the displayed username in the fishing game client by adding un=your_username, it will override the actual username in our system.
Parameter Description Type
returnurl The URL will be invoked when the Fishermen Gold logout (optional)
String
un To override the displayed username come from system (optional)
String
Copyright © SimplePlay 2019 All right reserved 50/52
https://www.yourdomain.com/somewhere
TECHNICAL GUIDE
9. Slot Game ID/Game Code to Game mapping
➤ Slot Game Please contact our customer service representative to get the latest list of Slot Game game codes and graphics materials. ➤ Fishing Game
Game Game code
Fishing Game EG-FISHING-001
10. Supported currencies
The following is the list of currencies we supported. Please notice that currency has to be enabled in your API account before you can use it, you may contact our CS for queries.
Currency ISO name Currency
CNY Chinese yen
USD US Dollar
EUR Euro
JPY Japanese Yen
VND* Vietnamese Dong
AUD Australian Dollar
TWD Taiwan New Dollar
MYR Malaysian Ringgit
IDR* Indonesian Rupiah
SGD Singapore Dollar
GBP British Pound
Copyright © SimplePlay 2019 All right reserved 51/52
TECHNICAL GUIDE
THB Thai Baht
TRY Turkish Lira
UAH Ukrainian Hryvnia
mXBT milli Bitcoin
BND Bruneian Dollar
CAD Canadian Dollar
MMK* Burmese Kyat
NOK Norwegian Krone
SEK Swedish Krone
ZAR South Africa Rand
BDT Bangladeshi Taka
LKR Sri Lankan Rupee
INR Indian Rupee
RUB Russian Ruble
PLN Polish Zloty
AED Emirati Dirham
KHR* Cambodian Riel
BRL Brazilian Real
CHF Swiss Franc
NZD New Zealand Dollar
HUF Hungarian Forint
In our system, currency with * is divided by 1000 from real-world currency.
Copyright © SimplePlay 2019 All right reserved 52/52
Recommended