VNLOTO API Transfer Wallet

Overview

1. Language

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

2. Currency Types

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

3. Time Zone and Date/Time Format

• 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 must include an error status indicating whether an error occurred.

Common Responses

Success
{
    "errorCode": 0,
    "message": "The operation was successful!"
}

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

Failure
{
    "errorCode": 1001,
    "message": "Failed: Username has been registered."
}

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

5. Logging

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

6. Interfaces

The system provides two interfaces: xoso168 and xoso188.

• xoso168: Uses a luxurious gold theme.
• xoso188: Uses a sky blue theme.

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: Transfer
  • Currency type: VND (two options: VND or VNDK)
  • Agent code: X88 (used for agent identification)
  • Interface type: xoso168 (two interface templates: xoso168 and xoso188)

8.2 XOSO168 Creates a Test Integration Environment and Returns Results to the Agent

• After the agent supplies sufficient information, XOSO168 creates a test integration environment for the agent:
  • agentId (indicator): 161864
  • apikey: KEY24111108254650610
  • API Address: https://stgapi.xoso168.net/
  • Themeid: xoso168
  • Currency: VNDK
  • Prefix: GX
  • BO account: agentA/pass1234
  • BO Address: https://stgbo.xoso168.net/

9. API Authentication

• When calling XOSO168 APIs:
  • Add apiPrivateKey in the header; this key is provided by XOSO168 during integration

API List

1. Create Player (CreatePlayer)

URL: /LotoService.aspx

Method: POST

Request

Field Name	Type	Max Length	Required	Description
flag	String	20	Y	Fixed value: CreatePlayer
account	String	50	Y	Only alphanumeric characters [a-z, A-Z, 0-9, _ ] allowed
password	String	50	Y	Player’s password
sign	Number	10	Y	Agent identifier provided during system integration

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request POST \
  --data '{
      "flag": "CreatePlayer",
      "account": "test01",
      "password": "123qwe",
      "sign": "161825"
  }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message

Response Example

Success
{
    "errorCode": 0,
    "message": "The operation was successful!"
}

Failure
{
    "errorCode": 500,
    "message": "Failed: Please try again or contact customer service!"
}

Unauthorized
{
    "errorCode": 4001,
    "message": "Failed: Insufficient access."
}

Account already exists
{
    "errorCode": 1001,
    "message": "ailed: Username has been registered."
}

2. Player Login (PlayerLogin)

URL: /LotoService.aspx

Method: POST

Request

Field Name	Type	Max Length	Required	Description
flag	String	20	Y	Fixed value: PlayerLogin
account	String	50	Y	Only alphanumeric characters [a-z, A-Z, 0-9, _ ]
password	String	50	Y	Player’s password
loginType	Number	1	Y	0 for mobile 1 for PC The simplest is 1, and if accessed from mobile, the system automatically redirects.
gameId	Number	1	Y	Refer to the GameId table
lang	String	10	N	List of values: 'en', 'zh_CN', 'vi'. If this parameter is not provided, the default game link will be displayed in Vietnamese.

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request POST \
  --data '{
        "flag": "PlayerLogin",
        "account": "player1",
        "password": "abcd1234",
        "loginType": 0,
        "gameId": 0
    }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
gameLink	String	512	Y	If loginType is 0, returns mobile web link If loginType is 1, returns PC web link

Response Example

Successful mobile login
{
    "errorCode": 0,
    "gameLink": "http://[SERVER]/?token=Z2FtZSZwbGF5ZXIxJmFiY2QxMjM0&gameId=0",
    "message": "The operation was successful!"
}

Successful PC login
{
    "errorCode": 0,
    "gameLink": "http://[SERVER]/game?token=Z2FtZSZwbGF5ZXIxJmFiY2QxMjM0&gameId=0",
    "message": "The operation was successful!"
}

Incorrect username or password
{
    "errorCode": 1002,
    "gameLink": "",
    "message": "Failed: Invalid username or password, please try again!"
}

3. Balance

URL: /LotoService.aspx

Method: POST

Request

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

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request POST \
  --data '{
        "flag": "Balance",
        "account": "player1"
    }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
balance	String	15	Y	Player’s balance

Response Example

Query successful
{
    "balance": "9874000",
    "errorCode": 0,
    "message": "The operation was successful!"
}

4. Deposit

URL: /LotoService.aspx

Method: POST

Request

Field Name	Type	Max Length	Required	Description
flag	String	50	Y	Fixed value: Deposit
refno	String	50	Y	Transaction ID on the Merchant side
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	A decimal number with 18 digits and 2 digits after the decimal point.

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request POST \
  --data '{
    "flag": "Deposit",
    "refno": "refno1",
    "account": "player1",
    "amount": 100000
}' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message

Response Example

Success
{
    "errorCode": 0,
    "message": "The operation was successful!"
}

Refno already exists
{
    "errorCode": 2001,
    "message": "Failure: Reference number refno10 already exists"
}

5. Withdraw

URL: /LotoService.aspx

Method: POST

Request

Field Name	Type	Max Length	Required	Description
flag	String	20	Y	Fixed value: Withdraw
refno	String	50	Y	Transaction ID on the Merchant side
account	String	50	Y	Player’s account
amount	Decimal	18,2	Y	Must be a negative number, a decimal with 18 digits and 2 digits after the decimal point.

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request POST \
  --data '{
        "flag": "Withdraw",
        "refno": "refno1",
        "account": "player1",
        "amount": 100000
    }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message

Response Example

Success
{
    "errorCode": 0,
    "message": "The operation was successful!"
}

Refno already exists
{
    "errorCode": 2001,
    "message": "Failure: Reference number refno10 already exists"
}

Account balance is insufficient
{
    "errorCode": 2005,
    "message": "Failed: Account balance is insufficient."
}

6. BetLog

URL: /LotoService.aspx

Method: POST

info

• Rate limit: 1 request every 10 seconds
• Query interval: up to 1 hour (distance between start_time and end_time)
• Date limit: up to 35 days

Parameter Data

Field Name	Type	Max Length	Required	Description
flag	String	20	Y	Fixed value: BetLog
sign	Number	10	Y	Agent identifier provided during system integration
startTime	String	16	N	Search by betting time. Format: yyyy-MM-dd HH:mm, e.g., "2024-10-12 00:00:00"
endTime	String	16	N	Search by betting time. Format: yyyy-MM-dd HH:mm, e.g., "2024-10-12 00:00:00"

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request GET \
  --data '{
        "flag": "BetLog",
        "sign": "171762",
        "startTime": "2024-10-12 00:00:00",
        "endTime": "2024-12-12 23:59:59"
    }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
reslist	array	-	N	List of bets

Data Structure

Field Name	Type	Max Length	Description
amount	Number		Betting amount
betcontent	String	4000	Betting content
betfrom	Number		0: Bet on PC web 3: Bet on Mobile web
betnumber	Number		The number of digits the player picked
bettime	String		Betting time
bettype	String	10	Number input method: pick numbers, manually enter, quick pick
bonus	Number		Bonus amount
codes	String	4000	Betting content code
finishtime	String		End time
id	String	50	Betting ID (unique)
inserttime	String		Data insertion time
ip	String	50	IP address
issue	String	50	Lottery draw
loginname	String	50	Login name
lotteryid	Number		Lottery ID
methodid	Number		Betting method type
multiple	Number		Betting multiplier
status	Number		Bet status (see Appendix)
traceid	String	30	Number of betting codes, one betting code includes many betting tickets (When User creates an automatic betting plan, it will create a betting code
usertime	String		User’s local time
winnumber	String	200	Winning number
wintimes	Number		Number of wins
odd	Number		Odds when calculating prizes for lottery games

info

• Bonus calculation formula = Bet multiplier * Odd * Number of wins * Exchange ratio
• Exchange ratio is either 1 or 1000 (Ex: VND = 1000, VNDK, USD,... = 1)

Response Example

Success
{
    "errorCode": 0,
    "message": "The operation was successful!",
    "reslist": [
       {
            "amount": 100000,
            "betcontent": "[Đánh Đề - Đề đặc biệt] -,-,X,X",
            "betfrom": 0,
            "betnumber": 50,
            "bettime": "2025-03-30 13:57:10",
            "bettype": "digital",
            "bonus": 199000,
            "codes": "0&1&2&3&4&5&6&7&8&9|5&6&7&8&9",
            "finishtime": "2025-03-30 13:57:52",
            "id": "B250330135710100068",
            "inserttime": "2025-03-30 13:57:10",
            "ip": "0:0:0:0:0:0:0:1",
            "issue": "20250330-1118",
            "loginname": "transfervnd",
            "lotteryid": 100,
            "methodid": 6,
            "multiple": 2,
            "odd": 99.5,
            "status": 4,
            "traceid": "",
            "usertime": "2025-03-30 13:57:10",
            "winnumber": "723127,19002,71299,38929,76096,53274,56712,52535,78395,83693,33270,79533,5903,0471,9356,1519,741,33,",
            "wintimes": 1
        },
        {
            "amount": 900000,
            "betcontent": "[Bao Lô - Lô 2 Số] -,-,X,X",
            "betfrom": 0,
            "betnumber": 50,
            "bettime": "2025-03-30 13:56:55",
            "bettype": "digital",
            "bonus": 796000,
            "codes": "0&1&2&3&4&5&6&7&8&9|5&6&7&8&9",
            "finishtime": "2025-03-30 13:56:55",
            "id": "B250330135655100067",
            "inserttime": "2025-03-30 13:56:55",
            "ip": "0:0:0:0:0:0:0:1",
            "issue": "20250330-1s",
            "loginname": "transfervnd",
            "lotteryid": 50,
            "methodid": 1,
            "multiple": 1,
            "odd": 0,
            "status": 4,
            "traceid": "",
            "usertime": "2025-03-30 13:56:55",
            "winnumber": "211216,13327,95851,95490,57097,35194,57905,45782,75330,61023,27181,76665,5676,5638,7240,9073,536,13,",
            "wintimes": 8
        }
    ]
}

Failure
{
    "errorCode": 4001,
    "message": "Failed: Insufficient access.."
}

7. BetInfo

URL: /LotoService.aspx

Method: POST

Parameter Data

Field Name	Type	Max Length	Required	Description
flag	String	20	Y	Fixed value: BetInfo
betId	String	50	Y	Betting ID (unique)

Request Example

curl --header "Content-Type:application/json" \
  --header "Accept: application/json" \
  --header "apiPrivateKey : [apiPrivateKey]" \
  --request GET \
  --data '{
        "flag": "BetInfo",
        "betId": "B250404085016100055"
    }' \
  https://[SERVER]/LotoService.aspx

Response

Field Name	Type	Max Length	Required	Description
errorCode	Integer		Y	Error code
message	String	255	Y	Error message
betinfo	Object	-	N	Bet ticket info

Data Structure: Refer BetLog API

Response Example

Success
{
    "betinfo": {
        "amount": 10,
        "betcontent": "betdata[da]=5&betdata[xiao]=5",
        "betfrom": 0,
        "betnumber": 1,
        "bettime": "2025-04-04 08:50:16",
        "bettype": "",
        "bonus": 0,
        "codes": "betdata[da]=5&betdata[xiao]=5",
        "finishtime": "",
        "id": "B250404085016100055",
        "inserttime": "2025-04-04 08:50:16",
        "ip": "0:0:0:0:0:0:0:1",
        "issue": "20250404-0051",
        "loginname": "transfervndk",
        "lotteryid": 80,
        "methodid": 0,
        "multiple": 1,
        "odd": 0,
        "status": 2,
        "traceid": "",
        "usertime": "2025-04-04 08:50:16",
        "winnumber": "331",
        "wintimes": 0
    },
    "errorCode": 0,
    "message": "The operation was successful!",
}

Failure
{
    "errorCode": 4010,
    "message": "Failed: No record found."
}


Failure
{
    "errorCode": 4001,
    "message": "Failed: Insufficient access.."
}

Failure
{
    "errorCode": 500,
    "message": "Failed: Please try again or contact customer service!"
}

Appendix

1. Error Codes

Error Code	Error Message	Error Type
0	The operation was successful!	Transaction Success
4001	Failed: Insufficient access.	Access Error (e.g., wrong apikey..)
4002	Failed: Invalid agentId.	Access Error
4004	Failed: System under maintenance.	Access Errors
4010	Failed: No record found.	Client-side errors (Error not found requested resource)
500	Failed: Please try again or contact customer service!	System Errors
1001	Failed: Username has been registered.	Account Errors
1002	Failed: Invalid username or password, please try again!	Account Errors
1003	Your account has been disabled, if you have any questions, please contact customer service!	Account Errors
1004	Failure: Account does not exist	Account Errors
1005	Failure: Account is locked and cannot be deposited	Account Errors
1006	Your account has been disabled, if you have any questions, please contact customer service!	Account Errors
1007	Failure: Trial account cannot be deposited	Account Errors
1008	Failure: Account is locked and cannot be withdrawn	Account Errors
2001	Failure: Reference number 0 already exists	Reference Errors
2005	Failed: Account balance is insufficient.	Withdrawal Errors

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 results canceled	No

3. 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	Rapid	Rapid 1 Second
100	Rapid	Rapid 45 Seconds
101	Rapid	Rapid 1 Minute
102	Rapid	Rapid 1.5 Minutes
103	Rapid	Rapid 2 Minutes
104	Rapid	Rapid 5 Minutes
105	Southern	Ho Chi Minh
106	Southern	Dong Thap
107	Southern	Ca Mau
108	Southern	Ben Tre
109	Southern	Vung Tau
110	Southern	Bac Lieu
111	Southern	Dong Nai
112	Southern	Can Tho
113	Southern	Soc Trang
114	Southern	Tay Ninh
115	Southern	An Giang
116	Southern	Binh Thuan
117	Southern	Vinh Long
118	Southern	Binh Duong
119	Southern	Tra Vinh
120	Southern	Long An
121	Southern	Binh Phuoc
122	Southern	Hau Giang
123	Southern	Tien Giang
124	Southern	Kien Giang
125	Southern	Da Lat
126	Central	Thua Thien Hue
127	Central	Phu Yen
128	Central	Dak Lak
129	Central	Quang Nam
130	Central	Da Nang
131	Central	Khanh Hoa
132	Central	Binh Dinh
133	Central	Quang Tri
134	Central	Quang Binh
135	Central	Gia Lai
136	Central	Ninh Thuan
137	Central	Quang Ngai
138	Central	Dak Nong
139	Central	Kon Tum
200	Northern	Northern 18H14
201	Northern	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

4. 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