29. Free Spin

调用顺序：29.1 获取 provider → 29.2 获取该 provider 的游戏（gameID）→ 29.3 发放 free spin → 29.4 查询是否已使用

29.1 Get Provider Free Spin (Common)

供 Merchant 获取支持 free spin 的 provider 列表

Method : [Post]
Path : {{domain}}/ext/getProviderFreeSpin/{{prefix}}/{{agentUsername}}
Content-Type : application/json

Request Body

{
    "agentUsername": "{{agentUsername}}",
    "key": "{{key}}",
    "web": "{{whiteLabel}}"
}

Key	Type	Example Value	Description
agentUsername	String	testopupapixx	The agent's username.
key	String	pbR-P0cnKwLVirSOCvf53	The agent's unique key.
web	String	sportbook101	Active websites.

Response

{
    "code": 0,
    "msg": "SUCCESS",
    "data": [
        {
            "provider": "PGS"
        }
    ]
}

Key	Type	Example Value	Description
code	Number	0	Response code of API
msg	String	SUCCESS	description of code
data	Array	[{"provider":"PGS"}]	Providers that support free spin, returned from the game service as-is

*The provider list is cached for 5 minutes. A provider added on the game service side may take up to 5 minutes to appear.

Error Code

Value	msg
0	Success
100001	Missing 'agent username' field.
100002	Agent username is type string.
100003	Missing 'key' field.
100004	Key is type string.
100012	Key not found.
100013	Agent not found.
998	System error.

*Any other code is returned from the game service as-is, together with its own message.

29.2 Get Free Spin Games (Common)

供 Merchant 获取某个 provider 可发放 free spin 的游戏列表，将列表中的 gameID 作为 Create Free Spin 的 gameId 使用

Method : [Post]
Path : {{domain}}/ext/getFreeSpinGames/{{prefix}}/{{agentUsername}}
Content-Type : application/json

Request Body

{
    "agentUsername": "{{agentUsername}}",
    "key": "{{key}}",
    "provider": "L22",
    "web": "{{whiteLabel}}"
}

Key	Type	Example Value	Description
agentUsername	String	testopupapixx	The agent's username.
key	String	pbR-P0cnKwLVirSOCvf53	The agent's unique key.
provider	String	L22	Provider code from Get Provider Free Spin. Required.
web	String	sportbook101	Active websites.

Response

{
    "code": 0,
    "msg": "SUCCESS",
    "data": [
        {
            "gameID": "66053e460b0139746d384980",
            "gameName": {
                "en": "Apes Squad",
                "th": "",
                "cn": "猿人突击队",
                "la": "",
                "id": "",
                "vn": "",
                "my": "",
                "mm": "",
                "kh": "",
                "tw": ""
            },
            "image": {
                "vertical": "https://ambimgcdn2.co/img/sportsbook/game/L22/L22_Apes%20Squad.webp",
                "horizontal": "https://ambimgcdn2.co/img/sportsbook/game/L22/L22_Apes%20Squad.webp",
                "square": "https://ambimgcdn2.co/img/sportsbook/game/L22/L22_Apes%20Squad.jpg"
            }
        }
    ]
}

Key	Type	Example Value	Description
code	Number	0	Response code of API
msg	String	SUCCESS	description of code
data	Array	[{...}]	Games that can give free spin, returned from the game service as-is
data[].gameID	String	66053e460b0139746d384980	Game id. Send it as `gameId` on Create Free Spin.
data[].gameName	Object	{"en":"Apes Squad",...}	Game name per language: en, th, cn, la, id, vn, my, mm, kh, tw. A language the provider did not fill in is "".
data[].image	Object	{"vertical":"https://...",...}	Game images: vertical, horizontal, square.

*Games hidden on the game service side are not returned.

*The game list is not cached. Every call fetches it from the game service.

Error Code

Value	msg
0	Success
100001	Missing 'agent username' field.
100002	Agent username is type string.
100003	Missing 'key' field.
100004	Key is type string.
100012	Key not found.
100013	Agent not found.
100015	Invalid input format 'provider' field.
998	System error.

*100015 is returned when provider is missing or is not a string, with error_filed "provider".

*A provider that does not support free spin returns code 9901 from the game service.

*Any other code is returned from the game service as-is, together with its own message.

29.3 Create Free Spin (Common)

供 Merchant 给会员发放 free spin

Method : [Post]
Path : {{domain}}/ext/createFreeSpin/{{prefix}}/{{agentUsername}}
Content-Type : application/json

Request Body

{
    "agentUsername": "{{agentUsername}}",
    "key": "{{key}}",
    "username": "{{agentUsername}}ninemb01",
    "transactionId": "FS-20260914-0001",
    "gameId": "60531c5534d88c344ce9acb2",
    "betAmount": 1,
    "freeSpinCount": 10,
    "web": "{{whiteLabel}}"
}

Key	Type	Example Value	Description
agentUsername	String	testopupapixx	The agent's username.
key	String	pbR-P0cnKwLVirSOCvf53	The agent's unique key.
username	String	testopupapixxninemb01	The member who receives the free spin. Must be a direct member of the agent.
transactionId	String	FS-20260914-0001	Merchant reference of this free spin. Use it to query the log later.
gameId	String	60531c5534d88c344ce9acb2	Game to give the free spin on. Get it from Get Free Spin Games.
betAmount	Number	1	Bet amount per spin. Must be greater than 0.
freeSpinCount	Number	10	Number of free spins. Must be greater than 0.
web	String	sportbook101	Active websites.

*minAmount and maxAmount are not accepted. They are fixed at 0 and 100000.

*PG Soft games are served as two game id sets. Send either one — the system converts the id to the set that matches the member before sending it to the game service.

Response

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {}
}

Key	Type	Example Value	Description
code	Number	0	Response code of API
msg	String	SUCCESS	description of code
data	Object	{}	Result returned from the game service as-is

Error Code

Value	msg
0	Success
100001	Missing 'agent Username' field.
100002	Agent username is type string.
100003	Missing 'key' field.
100004	Key is type string.
100005	Missing 'username' field.
100006	Username is type string.
100007	Missing 'transactionId' field.
100008	TransactionId is type string.
100010	Missing 'gameId' field.
100011	GameId is type string.
100012	Key not found.
100013	Agent not found.
100015	Invalid input format 'betAmount' field.
100015	Invalid input format 'freeSpinCount' field.
5044	Permission denied
998	System error.

*5044 means the username does not exist, or the member is not a direct member of the agent that sent the request.

*Any other code is returned from the game service as-is, together with its own message.

29.4 Get Free Spin Logs (Common)

供 Merchant 查询已发放的 free spin 状态（pending 未使用 / used 已使用）

Method : [Post]
Path : {{domain}}/ext/getFreeSpinLogs/{{prefix}}/{{agentUsername}}
Content-Type : application/json

Request Body

{
    "agentUsername": "{{agentUsername}}",
    "key": "{{key}}",
    "transactionId": "FS-20260914-0001",
    "username": "{{agentUsername}}ninemb01",
    "provider": "PGS",
    "status": "pending",
    "page": 1,
    "limit": 20,
    "web": "{{whiteLabel}}"
}

Key	Type	Example Value	Description
agentUsername	String	testopupapixx	The agent's username.
key	String	pbR-P0cnKwLVirSOCvf53	The agent's unique key.
transactionId	String	FS-20260914-0001	Optional. The reference sent on create free spin. Returns only that free spin.
username	String	testopupapixxninemb01	Required. The member to view logs of. Must be a direct member of the agent.
provider	String	PGS	Optional. PGS / FC / PG
status	String	pending	Optional. pending or used only.
page	Number	1	Optional. Whole number (decimals are rounded down). Less than 1 becomes 1. Default 1.
limit	Number	20	Optional. Whole number (decimals are rounded down). Less than 1 becomes 20, more than 100 becomes 100. Default 20.
web	String	sportbook101	Active websites.

*username is required. Logs can be viewed only for members directly under the agent. To view several members, call once per member. The other filters are optional.

Response

{
    "code": 0,
    "msg": "SUCCESS",
    "data": [
        {
            "transactionID": "FS-20260914-0001",
            "username": "testopupapixxninemb01",
            "provider": "PGS",
            "status": "pending"
        }
    ]
}

Key	Type	Example Value	Description
code	Number	0	Response code of API
msg	String	SUCCESS	description of code
data	Array	[{...}]	Free spin logs returned from the game service as-is

Error Code

Value	msg
0	Success
100001	Missing 'agent username' field.
100002	Agent username is type string.
100003	Missing 'key' field.
100004	Key is type string.
100005	Missing 'username' field.
100006	Username is type string.
100008	TransactionId is type string.
100012	Key not found.
100013	Agent not found.
100015	Invalid input format 'provider' field.
100015	Invalid input format 'status' field.
100015	Invalid input format 'page' field.
100015	Invalid input format 'limit' field.
5044	Permission denied
998	System error.

*5044 means the username does not exist, or the member is not a direct member of the agent that sent the request.

*status accepts pending or used only. Any other value returns 100015 with error_filed "status".

*Any other code is returned from the game service as-is, together with its own message.