Batch Send FreeSpin Operator Card
Send FREE SPIN card to specified Player, supports sending to multiple Players and 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, Upper Limit is 100 |
maxWinAmount | number | No | Maximum winning amount |
itemBet | number | No | Operator Card Bet Amount, can be filled according to BetList. If not filled, the smallest Bet will be used by default. |
multiple | number | No | Free Spin Multiplier, can be 1/2/3/5 times. If not filled, 1x will be used by default. |
expiredTime | string | No | 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 means Success |
message | string | Response message |
data.successList | Object Array | Item sent Success list |
data.failedList | Object Array | Item sent failed list |
logUUID | string | Request tracking ID for troubleshooting and log queries |
- Item send list parameter Description
| Field | Type | Description |
|---|---|---|
username | number | Player Account |
gameCode | string | Game Code |
spinId | string | Operator Card Unique Identifier |
code | number | Item sending result response code |
message | string | Item sending result response message |
itemId | string | System Operator Card ID, generated only in the Item Success send list |
Error Response
Error Codes
| Code | Description | Handling Suggestion |
|---|---|---|
| 5 | Game is not found | Games not found, delisted, or currency not supported, please confirm 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 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 |
| 88 | Only one item can be active at a time in the same game | Player currently has another card active in the Games that has not been used yet |
| 89 | The item has not been used yet, or the spinId does not exist | Reconfirm if Item has been used or if Item has expired and does not exist |
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 completeness: If spinId is provided, it must match the quantity of "Player Account" x "Game Code", otherwise an error will be Triggered
- Immediate effect: Every FREE SPIN card sent successfully by this API takes immediate effect
- Partial sending: This batch of Items will not fail to send entirely due to some Items failing to send successfully
Common QA
Q1: Does the API sending FREE SPIN have an expiration time?
A: After sending, if Player has not logged into Games to use it, it will automatically Settlement after 12 hours.
Q2: Can the API sending FREE SPIN be cancelled?
A: Yes, it can be cancelled via the Cancel Operator Card API, but it must be done before Player enters Games to use it or before automatic Settlement, otherwise it cannot be cancelled.
Q3: Will the Player be notified after automatic Settlement?
A: When Player logs into Games, a reminder reward message will be displayed, but the animation will not be re-shown. If multiple records are Settlement, only the last Settlement record will be displayed.
Q4: If the expiration time is reached, will the Operator Card automatically Settlement or be cancelled?
A: It will be cancelled, and the Operator Card spinId cannot be reused. There will be no record of this in the backend or bet logs.
Q5: If Player leaves Games during the Games animation, will FREE SPIN automatically Settlement?
A: If Player quits midway and returns to Games, it will continue until completed, and will only Settlement after all uses are finished.
Q6: What is the interaction logic between Card expiration time "expiredTime" and automatic Settlement?
A: Automatic Settlement is fixed to 12 hours later. Therefore, if the Card expiration time parameter is set to less than 12 hours, automatic Settlement will be Triggered first. If the Card expiration time is set to more than 12 hours from the sending time, it will be fixed at 12 hours to avoid Player experience discrepancy.