VNLOTO API Single Wallet

Overview

1. Language

• Mobile web, desktop web: Vietnamese
• Backoffice: Vietnamese, English, Chinese

2. Currency

• The system supports most currencies. Refer to the appendix.

3. Time Zone and Date/Time

• API: GMT+7
• Backoffice: GMT+7
• Platform: GMT+7
• Required date/time format:
  • Date: dd-mm-yyyy (Example: 03-08-2024)
  • Date and time: dd-mm-yyyy hh24:mi (Example: 03-08-2024 14:20)

4. Error Handling

• All responses should include an error status to indicate whether an error occurred.

Common Responses

Success
{
    "errorCode": 0,
    "message": "Action successful!"
}

Success with data
{
    "balance": "9774000",
    "errorCode": 0,
    "message": "Action successful!"
}
...

Failure
{
    "errorCode": 3,
    "message": "Failure: The username has already been registered."
}

• Generally, an error code of 0 means “no error.” Any other code indicates an error.

5. Logging

• All request and response parameters, including server errors, are logged.

6. Interfaces

The system has two interfaces: xoso168 and xoso188.

• xoso168: Uses a dominant luxurious gold color.
• xoso188: Uses a dominant sky blue color.

7. Game Betting Odds

• Agents can set their own detailed lottery odds for each lottery type, lottery station, and play style.

8. Integration Steps

8.1 Agent Provides Integration Information

• The agent provides the following information to XOSO168 before integration:
  • Wallet type: Seamless
  • Currency: VND (two types: VND or VNDK)
  • Agent code: X88 (used for agent identification)
  • Agent API URL: https://[SERVER]/api/merchant
  • Agent API key: APIKEY01a15085-8460

8.2 XOSO168 Creates the Integration Environment and Returns It to the Agent

• After the agent provides the required information, XOSO168 will create a test integration environment for the agent:
  • agentId (identifier): 161864
  • apikey: KEY24111108254650610
  • API URL: https://stgapi.xoso168.net/
  • Themeid: xoso168
  • Currency: VNDK
  • Prefix: GX
  • BO account: agentA/pass1234
  • BO URL: https://stgbo.xoso168.net/

9. API Authentication

• When the agent calls the XOSO168 API:
  • Include the apiPrivateKey in the header; this key is provided by XOSO168 during integration.

• XOSO168 calls the agent’s API:
  • Include the agentSecretKey in the header; this key is provided by the agent to XOSO168 during integration.

Common APIs

• CreatePlayer, PlayerLogin, BetLog, BetInfo
• These APIs use the [apiPrivateKey] provided by XOSO168 to the agent for authentication.
• Please refer to the TransferWallet documentation.

Single Wallet APIs

• These APIs use the [agentSecretKey] provided by the agent to XOSO168 for authentication.

https://[SERVER]/api/merchant

1. Balance

• This function allows the game provider to periodically synchronize the player’s balance.

URL: https://[SERVER]/api/merchant

Method: POST

info

• Connection Timeout: 5 seconds
• Read Timeout: 5 seconds

Request

Field Name	Type	Max Length	Mandatory	Description
flag	String	32	Y	Fixed value: Balance
account	String	50	Y	Player’s account

Request sample

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "agentSecretKey: APIKEY01a15085-8460" \
  --request POST \
  --data '{
  "flag": "Balance",
  "account": "lt001"
  }' \
  https://[SERVER]/api/merchant

Response

Field Name	Type	Max Length	Mandatory	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
data	Object		N	Holds the response data

Response data structure

Field Name	Type	Max Length	Mandatory	Description
balance	Decimal	18,2	Y	Player’s balance
account	String	50	Y	Player’s account

Response sample

Success
{
    "errorCode": 0,
    "message": "Successfully executed",
    "data": {
        "balance": 998665.75,
        "account": "lt001"
    }
}

Server error
{
    "errorCode": 500,
    "message": "Internal server error"
}

2. Bet

• Send betting information to the single wallet. Each bet request must respond with the updated “balance” parameter to update the player’s game balance.
• The PlaceBet action will start after the player clicks the “Confirm” button.
• The single wallet must check the player’s balance and deduct the bet amount based on the transaction details.

URL: https://[SERVER]/api/merchant

Method: POST

info

• Connection Timeout: 5 seconds
• Read Timeout: 6 seconds

Request

Field Name	Type	Max Length	Mandatory	Description
flag	String	32	Y	Fixed value: Bet
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Bet amount

Request sample

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "agentSecretKey: APIKEY01a15085-8460" \
  --request POST \
  --data '{
  "flag": "Bet",
  "balanceChangeId": "BCB240729153234F1LF",
  "betId": "B2407291532343P4L",
  "account": "lt001",
  "amount": 50
}' \
  https://[SERVER]/api/merchant

Response

Field Name	Type	Max Length	Mandatory	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
data	Object		N	Holds the response data

Data Structure

Field Name	Type	Max Length	Mandatory	Description
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Bet amount
balance	Decimal	18,2	Y	Player’s account balance

Response sample

Success
{
  "errorCode": 0,
  "message": "Success",    
  "data": {
    "balanceChangeId": "abc123",
    "betId": "bet456",
    "account": "lt001",
    "amount": 100,
    "balance": 50
  }
}

Fail
{
  "errorCode": "20",
  "message": "Account balance is not enough"
}

Server error
{
  "errorCode": "500",
  "message": "Internal server error"
}

3. Cancel

• Send a cancel bet request to the single wallet.
• Cancel bet can be triggered when the Bet response times out.
• Cancel bet will be retried several times until it is successful, or the operator returns an error or the retry limit is reached.
• The single wallet must check and refund the bet amount to the player based on the transaction details.
• Retry Policy:
  • 1 retry after 5 seconds
  • 1 retry after 10 seconds
  • 1 retry after 30 seconds
  • 1 retry after 1 minute
  • 1 retry after 2 minutes
  • 1 retry after 5 minutes
  • 1 retry after 10 minutes
  • 1 retry after 15 minutes

URL: https://[SERVER]/api/merchant

Method: POST

info

• Connection Timeout: 5 seconds
• Read Timeout: 12 seconds

Request

Field Name	Type	Max Length	Mandatory	Description
flag	String	32	Y	Fixed value: Cancel
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Bet amount

Request sample

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "agentSecretKey: APIKEY01a15085-8460" \
  --request POST \
  --data '{
  "flag": "Cancel",
  "balanceChangeId": "BCB240729153234F1LF",
  "betId": "B2407291532343P4L",
  "account": "lt001",
  "amount": 50
}' \
  https://[SERVER]/api/merchant

Response

Field Name	Type	Max Length	Mandatory	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
data	Object		N	Holds the response data

Data Structure

Field Name	Type	Max Length	Mandatory	Description
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Bet amount

Response sample

Success
{
  "errorCode": 0,
  "message": "Success",    
  "data": {
    "balanceChangeId": "abc123",
    "betId": "bet456",
    "account": "lt001",
    "amount": 50
  }
}

Server error
{
  "errorCode": 500,
  "message": "Internal server error"
}

4. Settle

• This function is used to send credit transactions (bonus) to the player. The single wallet must update the player's balance based on these credit transactions.
• The Settle call may be retried if there is an error. It will keep retrying until it is successful.

URL: https://[SERVER]/api/merchant

Method: POST

info

• Connection Timeout: 5 seconds
• Read Timeout: 12 seconds

Request

Field Name	Type	Max Length	Mandatory	Description
flag	String	32	Y	Fixed value: Settle
data	Array		N	Stores the request array data

Data structure

Field Name	Type	Max Length	Mandatory	Description
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Winning amount

Request sample

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "agentSecretKey: APIKEY01a15085-8460" \
  --request POST \
  --data '{
  "flag": "Settle",
  "data": [
    {
      "balanceChangeId": "BCB240729153234F1LA",
      "betId": "B2407291532343P4A",
      "account": "lt001",
      "amount": 50
    },
    {
      "balanceChangeId": "BCB240729153234F1LF",
      "betId": "B2407291532343P4L",
      "account": "lt002",
      "amount": 20
    }
  ]
}' \
  https://[SERVER]/api/merchant

Response

Field Name	Type	Max Length	Mandatory	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
data	Array		N	Contains the successful bonus credit data
errors	Array		N	Contains the bonus credit data that failed, if any

Data Structure

Field Name	Type	Max Length	Mandatory	Description
balanceChangeId	String	50	Y	Transaction Id
betId	String	50	Y	Bet Id
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Bonus amount for the player

Response sample

Success
{
  "errorCode": 0,
  "message": "Success",
  "data": [
    {
      "balanceChangeId": "BCB240729153234F1LA",
      "betId": "B2407291532343P4A",
      "account": "lt001",
      "amount": 50
    },
    {
      "balanceChangeId": "BCB240729153234F1LF",
      "betId": "B2407291532343P4L",
      "account": "lt002",
      "amount": 20
    }
  ]
}

Fail
{
  "errorCode": 1,
  "message": "Success but content failed",
  "data": [
    {
      "balanceChangeId": "BCB240729153234F1LA",
      "betId": "B2407291532343P4A",
      "account": "lt001",
      "amount": 50
    }
  ],
  "errors": [
    {
      "balanceChangeId": "BCB240729153234F1LF",
      "betId": "B2407291532343P4L",
      "account": "lt002",
      "amount": 20
    }
  ]
}

Server error
{
  "errorCode": 500,
  "message": "Internal server error"
}

5. Note: Settle & Cancel

Note: The “Settle” and “Cancel” APIs only indicate the bet status on our platform. The operator must determine whether the corresponding transactions are charged or voided. Our platform does not specify or affect the handling method on the operator’s side.

Appendix

1. Error Codes

Error Code	Error Message	Error Type	Source	Wallet Type
0	Operation successful!	Transaction success	AGENT, XOSO168	Single, Transfer
1	Successful but content is invalid	Settle	AGENT	Single
20	Insufficient account balance	Bet	AGENT	Single
4001	Failure: Access denied.	Access rights error	XOSO168	Single, Transfer
4002	Failure: Invalid agentId.	Access rights error	XOSO168	Single, Transfer
4004	Failure: System is under maintenance.	Access rights error	XOSO168	Single, Transfer
500	Failure: Please try again or contact customer support!	System error	XOSO168	Single, Transfer
1001	Failure: Username already registered.	User account error	XOSO168	Single, Transfer
1002	Failure: Incorrect username or password, please try again!	User account error	XOSO168	Single, Transfer
1003	Your account has been disabled, please contact customer support!	User account error	XOSO168	Single, Transfer
1004	Failure: Account does not exist	User account error	XOSO168	Single, Transfer
1005	Failure: Account is locked, cannot deposit funds	User account error	XOSO168	Single, Transfer
1006	Your account has been disabled, please contact customer support!	User account error	XOSO168	Single, Transfer
1007	Failure: Test account cannot deposit funds	User account error	XOSO168	Single, Transfer
1008	Failure: Account is locked, cannot withdraw funds	User account error	XOSO168	Single, Transfer
2001	Failure: Reference number 0 already exists	Duplicate reference error	XOSO168	Single, Transfer
2005	Failure: Insufficient account balance	Withdrawal transaction error	XOSO168	Single, Transfer

2. Betting Status

Betting Status	Description	Payout
0	Not yet drawn	No
1	Awaiting draw	No
2	Awaiting settlement	No
3	Lost	No
4	Won	Yes
5	Canceled "maintenance"	No
6	Individual bet canceled	No
7	Draw canceled	No
10	Bet created and pending transaction processing (Agent system deducting bet amount)	No
12	Bet failed due to error or invalid conditions (e.g., insufficient balance or other exceptions)	No

3. Frontend Transaction Status

Status	Description
0	Processing
1	Cancelled by system
2	Successful

4. Backend Transaction Status

Status	Description
0	Processing by system
1	Failed
2	System processing timed out
3	Processing error
4	Successful
5	Cancellation in process
6	Cancelled by system
7	Bonus credit in process

5. GameId Table

GameId	Type	Description
0	MAIN	Main lobby
1	MAIN	ASIA 24H Menu
2	MAIN	VIP Menu
3	MAIN	Rapid Menu
4	MAIN	Northern Menu
5	MAIN	Central Menu
6	MAIN	Southern Menu
7	MAIN	Folk Games Menu
400	ASIA 24H	Southern 24H14
401	ASIA 24H	Central 24H14
402	ASIA 24H	Northern 24H14
300	VIP	Vietnam VIP 12H14
301	VIP	Saigon VIP 15H14
302	VIP	Ho Chi Minh VIP 16H14
303	VIP	Da Nang VIP 17H14
304	VIP	Ha Noi VIP 19H14
305	VIP	Thang Long VIP 20H14
50	Siêu Tốc	Siêu Tốc 1 Second
100	Siêu Tốc	Siêu Tốc 45 Seconds
101	Siêu Tốc	Siêu Tốc 1 Minute
102	Siêu Tốc	Siêu Tốc 1.5 Minutes
103	Siêu Tốc	Siêu Tốc 2 Minutes
104	Siêu Tốc	Siêu Tốc 5 Minutes
105	Miền Nam	Ho Chi Minh
106	Miền Nam	Dong Thap
107	Miền Nam	Ca Mau
108	Miền Nam	Ben Tre
109	Miền Nam	Vung Tau
110	Miền Nam	Bac Lieu
111	Miền Nam	Dong Nai
112	Miền Nam	Can Tho
113	Miền Nam	Soc Trang
114	Miền Nam	Tay Ninh
115	Miền Nam	An Giang
116	Miền Nam	Binh Thuan
117	Miền Nam	Vinh Long
118	Miền Nam	Binh Duong
119	Miền Nam	Tra Vinh
120	Miền Nam	Long An
121	Miền Nam	Binh Phuoc
122	Miền Nam	Hau Giang
123	Miền Nam	Tien Giang
124	Miền Nam	Kien Giang
125	Miền Nam	Da Lat
126	Miền Trung	Thua Thien Hue
127	Miền Trung	Phu Yen
128	Miền Trung	Dak Lak
129	Miền Trung	Quang Nam
130	Miền Trung	Da Nang
131	Miền Trung	Khanh Hoa
132	Miền Trung	Binh Dinh
133	Miền Trung	Quang Tri
134	Miền Trung	Quang Binh
135	Miền Trung	Gia Lai
136	Miền Trung	Ninh Thuận
137	Miền Trung	Quang Ngai
138	Miền Trung	Dak Nong
139	Miền Trung	Kon Tum
200	Miền Bắc	Northern 18H14
201	Miền Bắc	Special 6h25
60	Folk Games	Tai Xiu 1 Second
80	Folk Games	Tai Xiu 1 Minute
90	Folk Games	Xoc Dia 1 Second
91	Folk Games	Xoc Dia 1 Minute
92	Folk Games	Bau Cua 1 Second
93	Folk Games	Bau Cua 1 Minute

6. Currency List

Currency Code	Description
USDT	USDT
AED	United Arab Emirates dirham
AMD	Armenian dram
ARS	Argentine peso
AUD	Australian dollar
BDT	Bangladeshi taka
BND	Brunei dollar
BRL	Brazilian real
CAD	Canadian dollar
CHF	Swiss franc
CLP	Chilean peso
COP	Colombian peso
CNY	Chinese yuan (Renminbi)
DZD	Algerian dinar
EGP	Egyptian pound
ETB	Ethiopian birr
EUR	Euro
FRF	French franc
GBP	British pound sterling
GHS	Ghanaian cedi
HKD	Hong Kong dollar
IDR	Indonesian rupiah (1:1000)
INR	Indian rupee
JPY	Japanese yen
KRW	South Korean won
KZT	Kazakhstani tenge
KHR	Cambodian riel (1:1000)
KES	Kenyan shilling
LAK	Lao kip (original)
LAKK	Lao kip (1:1000)
LKR	Sri Lankan rupee
MAD	Moroccan dirham
MOP	Macanese pataca
MMK	Myanmar kyat (original) (1:1)
MMKK	Myanmar kyat (1:1000)
MYR	Malaysian ringgit
MXN	Mexican peso
MNT	Mongolian tugrik
NOK	Norwegian krone
NZD	New Zealand dollar
NPR	Nepalese rupee
NGN	Nigerian naira
PGK	Papua New Guinean kina
PTI	Indonesian rupiah (original) (1:1)
PKR	Pakistani rupee
PHP	Philippine peso
PEN	Peruvian nuevo sol
RUB	Russian ruble
SEK	Swedish krona
SGD	Singapore dollar
THB	Thai baht
TRY	Turkish lira
TND	Tunisian dinar
TZS	Tanzanian shilling
USD	United States dollar
UAH	Ukrainian hryvnia
UGX	Ugandan shilling
VND	Vietnamese đồng (original) (1:1)
VNDK	Vietnamese đồng (1:1000)
ZAR	South African rand
ZWD	Zimbabwean dollar
ZMW	Zambian kwacha

7. Single Wallet Integration Issues

There are several scenarios that may be encountered in production. We provide the following recommendations for each case so that your technical team can prepare solutions in advance.

A. Financial Data Dispute

If any issue causes a financial data dispute and cannot be processed immediately due to technical difficulties on your side in the production environment, you must accept our final decision if no consensus is reached.

B. Continuous Transaction Issues

If any production incident occurs, causing continuous transactions or transactions being stuck due to technical difficulties on your side and we cannot contact your technical team immediately for an effective resolution, please note that we will suspend your single wallet service to prevent worse situations that could affect the player experience until the technical issue is resolved.

Real-life Scenarios

Based on our real-world API notifications, you may encounter situations as described below. Please confirm that you can handle them correctly.

No.	Description	Details
1	Normal Case: You will receive the bet request first and then the cancel bet request.	Scenario: If XOSO168 does not receive the proper response for the bet request within the designated timeout period from the Operator. Solution: If the bet transaction has been accepted by the Operator (the balance has been deducted), then the cancel bet for that transaction (with the same transactionId/balanceChangeId) must be processed. The balance should be refunded based on the bet amount.
2	Exceptional Case: You receive the cancel bet request before receiving the bet request.	Scenario: This may occur due to network instability. Example: 1. XOSO168 sends a bet request to you. 2. Unstable network. 3. Your bet response times out. 4. XOSO168 sends a cancel bet request. 5. Due to network issues, you receive the cancel bet before the bet request. Solution: If you receive a cancel bet with a transactionId/balanceChangeId that does not match any stored bet transaction, the bet may still arrive later and should be reversed. Therefore, the Operator must retain this cancel bet until a matching bet is received or store it concurrently with other processed transactionIds/balanceChangeIds. One approach is to store this transactionId/balanceChangeId along with others that have been processed. In this way, if a bet with the same transactionId/balanceChangeId is received, it will not be processed.
3	Exceptional Case: You receive a cancel bet request but no corresponding bet exists.	Scenario: This may occur when the network experiences an issue. Example: 1. XOSO168 sends a bet request to you. 2. Due to unstable network, the bet requests are lost. 3. Your bet response times out. 4. XOSO168 sends a cancel bet request. 5. Due to network issues, you receive the cancel bet before the bet request. Solution: In this case, we recommend handling it in the same manner as Case 2.
4	Retry Count for Cancel Bet	Scenario: If we do not receive the expected cancel bet response from you, we will continue to resend the request until it is received. Solution: Please ensure your system can process and cancel the bet transaction using the same transactionId/balanceChangeId for the cancel bet, then respond successfully after verification. Expected response from the Operator: [cancelBet] errorCode: 0
5	Bet Failure due to Insufficient Balance	Scenario: If a bet fails due to insufficient balance or other bet limits on your side, XOSO168 will not request a separate cancel bet. Solution: Please confirm that your system can automatically log and verify these failed bet transactions. XOSO168 will request a cancel bet in these situations: 1. Bet response from the Operator times out. 2. The game provider sends a cancel bet request to XOSO168. 3. Even if your bet response does not time out, but the HTTP status code from your side is not 200, XOSO168 will request a cancel bet.
6	Duplicate Request	Scenario: If you receive a duplicate request that has already been successfully responded to XOSO168 (the bet deduction will not be retried). Solution: Please ensure that your system can recognize and not update the balance again, and respond with status: 0 to us. Any status other than 0 will be identified as invalid, and we will continue to resend the request until a valid response is received. Expected response from the Operator: status: 0

Please confirm that you have set up a complete storage environment. In other words, that you can receive and store any requests from XOSO168. If not, please implement it first.

The rationale is to allow you to monitor in real-time through anomaly logging and provide backup solutions so that you can restore necessary data from your log files.

Example: You should ensure that your system logs accurately while receiving a bet and then responds with 0 and the balance to us. No bet, settle, or cancel transaction should be dropped or deleted so that no data is lost.