Batch Send FreeSpin Operator Card
Send FREE SPIN cards to specified Players, supports sending to multiple Players across multiple games at once.
Note: FREE SPIN Cards: Free Spin Card, Multiplier Free Spin Card (cardType 1, 2)
API Information
- URL:
POST /v2/items/usesimplefreespin/batch - Authentication: Bearer Token
- Encryption: Requests are encrypted using AES-256-GCM; responses are returned as plaintext JSON
Request
Request Headers
POST /v2/items/use HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-agentid: integratorNBTest04
x-timestamp: 1769746894501
x-nonce: 56ffd5ecd8a3a4457863a0bd7c298fb2
x-signature: 904e97bee2589b93e9747eed0346c68b23d8ff8b568dabaf4b94a5e89093df67
Request Parameters
Decrypted Request
{
"cipherText": "G0ZMDELeJwx+7JcIfIFOLJjkSzANPu6krGM2uw==..."
}
Parameters Before Encryption
{
"usernames": ["alice01", "bob02"],
"gameCodes": ["VP_230001_1", "VP_230002_1"],
"spinIds": [
"spin_alice_g1_0001",
"spin_alice_g2_0002",
"spin_bob_g1_0003",
"spin_bob_g2_0004"
],
"round": 10,
"itemBet": 100,
"multiple": 2,
"maxWinAmount": 5000,
"expiredTime": "2026-04-30T12:00:00.000Z"
}
| Field | Type | Required | Description |
|---|---|---|---|
usernames | string Array | Yes | Player Account |
gameCodes | string Array | Yes | Game Code |
spinIds | string Array | No | Operator Card Unique Identifier, automatically generated by the system if not provided |
round | number | Yes | Number of rounds, must be an integer, Lower Limit 1, Upper Limit 100 |
maxWinAmount | number | No | Maximum Win Amount |
itemBet | number | No | Operator Card Bet Amount, can be filled by referring to BetList. If not filled, the minimum bet will be used by default |
multiple | number | No | Free Spin Multiplier, can be 1/2/3/5x. If not filled, 1x will be used by default |
expiredTime | string | Yes | Card expiration time |
Response
Success Response
{
"code": 0,
"message": "No error.",
"data": {
"successList": [
{
"username": "alice01",
"gameCode": "VP_230001_1",
"spinId": "spin_alice_g1_0001",
"code": 0,
"message": "No error.",
"itemId": "generated-item-id1"
},
{
"username": "alice01",
"gameCode": "VP_230003_1",
"spinId": "spin_alice_g1_0001",
"code": 0,
"message": "No error.",
"itemId": "generated-item-id2"
}
],
"failedList": [
{
"username": "bob02",
"gameCode": "VP_230001_1",
"spinId": "spin_bob_g2_0004",
"code": 8,
"message": "The User is not exist"
},
{
"username": "bob02",
"gameCode": "VP_230003_1",
"spinId": "spin_bob_g2_0004",
"code": 8,
"message": "The User is not exist"
}
]
},
"logUUID": "c6a85c7b-6108-4c88-95fb-fd79a1bda0a1"
}
| Field | Type | Description |
|---|---|---|
code | number | Response code, 0 indicates Success |
message | string | Response message |
data.successList | Object Array | List of successful Item deliveries |
data.failedList | Object Array | List of failed Item deliveries |
logUUID | string | Request tracking ID for troubleshooting and log queries |
- Item Delivery List Parameter Description
| Field | Type | Description |
|---|---|---|
username | number | Player Account |
gameCode | string | Game Code |
spinId | string | Operator Card Unique Identifier |
code | number | Item delivery result response code |
message | string | Item delivery result response message |
itemId | string | System Operator Card ID, generated only in the successful Item delivery list |
Error Response
Error Codes
| Code | Description | Handling Suggestion |
|---|---|---|
| 5 | Game is not found | Game does not exist, is offline, or does not support this currency. Please confirm whether gameCode is correct |
| 8 | The User is not exist | Player does not exist, please create Player first |
| 78 | Operator card spinId was used | Please change spinId, if you have any questions, contact Customer Support |
| 86 | Game is restricted | Please refer to the Game List document or inquire Customer Support |
| 87 | Invalid item parameter value | Reconfirm parameter rules or contact Customer Support Team |
| 89 | The item has not been used yet, or the spinId does not exist | Reconfirm whether the item has been used or if the item is expired/non-existent |
Error Response Example
Operator Card Parameter Combination Error
{
"code": 11,
"message": "spinIds length must match usernames x gameCodes combinations",
"logUUID": "2b82cfaf-d6ad-48fa-9963-4d91639b9b31"
}
Important Notes
- spinId Uniqueness: Each spinId must be unique and cannot be reused
- spinId Full Match: If spinId is provided, it must match the number of "Player Account" x "Game Code" combinations, otherwise, it will trigger an error
- Immediate Effect: Every FREE SPIN card successfully sent via this API takes effect immediately
- Partial Delivery: Partial Item delivery failures will not prevent the entire batch of Items from being sent
Frequently Asked Questions
Q1: Do FREE SPIN cards sent via this API have an expiration time?
A: Yes, the expiration time is specified by the expiredTime parameter. Unused cards will expire directly at the expiration time; automatic settlement will only occur after the Player starts using the card in games.
Q2: Can FREE SPIN cards sent via this API be cancelled?
A: Yes, they can be cancelled via the Cancel Operator Card API, but this must be done before the Player enters the game to use it or before automatic settlement. Otherwise, it cannot be cancelled.
Q3: Will Players be notified after automatic settlement?
A: When the Player logs into games, a reward notification message will be displayed, but the performance animation will not be re-displayed. If multiple records are settled, only the last settlement record will be displayed.
Q4: If the expiration time is reached, will the Operator Card be automatically settled or cancelled?
A: When the expiration time is reached, unused cards will directly expire, and the Operator Card spinId can no longer be reused. There will be no record of this data in the backend or bet logs.
Q5: If a Player leaves the game during a game animation, will the FREE SPIN be automatically settled?
A: If the Player exits midway and returns to the game, they will continue to complete it, and settlement will only occur after all spins are used. If the Player has used half of the spins and is stuck with remaining rounds, automatic settlement will occur after 12 hours.
Q6: What is the interaction logic between Card expiration time "expiredTime" and automatic settlement?
A: expiredTime is Required. Expiration and invalidation times are always calculated from the moment of sending, regardless of whether the Player has logged in. Unused cards will directly expire at the expiration time; automatic settlement will only occur after the Player starts using them in games. If a FREE SPIN card is stuck with remaining rounds, automatic settlement will occur after 12 hours.