Send FreeSpin Operator Card
Sends a FREE SPIN card to a specified Player. Note: FREE SPIN cards include: Free Spin Card and Multiplier Free Spin Card (cardType 1, 2)
API Information
- URL：
POST /v2/items/usesimplefreespin - 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
{
"username": "VPSysDevTest001",
"spinId": "SystemItemTestTrans150",
"gameCode": "VP_230001_1",
"round": 3,
"maxWinAmount": 10,
"itemBet": 2,
"multiple": 1,
"expiredTime": "2026-04-12T00:00:00.000Z"
}
| Field | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Player Account |
spinId | string | Yes | Operator Card Unique Identifier |
gameCode | string | Yes | Game Code |
round | number | Yes | Number of Rounds; the Upper Limit is 100 |
maxWinAmount | number | No | Maximum Win Amount |
itemBet | number | No | Operator Card Bet Amount; can be set by referring to the BetList. If not provided, the minimum Bet is used by default |
multiple | number | No | Free Spin Multiplier; can be set to 1/2/3/5x. If not provided, 1x is used by default |
expiredTime | string | No | Card Expiration Time |
Response
Success Response
{
"code": 0,
"message": "No error.",
"data": {
"itemId": "f2cb520579c8014452d6f521693a4aa8_VPItemTestTrans1042_ghjklhtombg"
},
"logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
| Field | Type | Description |
|---|---|---|
code | number | Response code; 0 indicates Success |
message | string | Response message |
data.itemId | string | System Operator Card ID |
logUUID | string | Request tracking ID for troubleshooting and log queries |
Error Response
Error Codes
| Code | Description | Handling Suggestion |
|---|---|---|
| 5 | Game is not found | The game does not exist, has been taken offline, or does not support this currency; please confirm whether the gameCode is correct |
| 8 | The User is not exist | The Player does not exist; please create the Player first |
| 78 | Operator card spinId was used | Please use a different spinId; if you have questions, contact Customer Support |
| 86 | Game is restricted | Please refer to the Game List documentation or ask Customer Support |
| 87 | Invalid item parameter value | Please re-check the parameter rules or contact the Customer Support Team |
| 88 | Only one item can be active at a time in the same game | Please have the Player re-enter the corresponding game before sending again |
| 89 | The item has not been used yet, or the spinId does not exist | Please confirm whether the Item has already been used, or whether the Item has expired and no longer exists |
Error Response Example
Operator Card Parameter Combination Error
{
"code": 87,
"message": "Invalid item parameter value",
"logUUID": "c6a85c7b-6108-4c88-95fb-fd79a1bda0a1"
}
Operator Card ID Duplicate Usage
{
"code": 78,
"message": "The spinID was used",
"logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
Important Notes
- spinId Uniqueness: Each spinId must be unique and cannot be reused
- Immediate Effect: This API sends the FREE SPIN card so that it takes effect immediately upon sending
Frequently Asked Questions
Q1: Does the FREE SPIN card sent by this API have an expiration time?
A: Yes. After it is sent, if the Player does not log in to the game to use it, it will be automatically settled 12 hours after being sent.
Q2: Can the FREE SPIN card sent by this API be cancelled?
A: Yes, it can be cancelled via the Cancel Operator Card API. However, this must be done before the Player enters the game to use it, or before it is automatically settled — otherwise it cannot be cancelled.
Q3: Is the Player notified after automatic settlement?
A: When the Player logs in to the game, a reminder message about the reward will be displayed, but the win animation will not be replayed. If there are multiple settlement records, only the most recent settlement record will be displayed.
Q4: If the expiration time is reached, is the Operator Card automatically settled or cancelled?
A: It is cancelled. The spinId of that Operator Card can never be reused afterward, and there will be no record of it in the backend or bet history.
Q5: If the Player leaves the game while a FREE SPIN animation is playing, will it be automatically settled?
A: If the Player exits partway through and later returns to the game, the FREE SPIN card will continue from where it left off, and it is only settled once all spins have been used.
Q6: How does the card's expiration time ("expiredTime") interact with automatic settlement?
A: Automatic settlement is fixed to occur 12 hours after sending. Therefore, if the card's expiration time is set to less than 12 hours, automatic settlement will be triggered first. If the card's expiration time is set to more than 12 hours after the time it was sent, it will be capped at 12 hours, in order to avoid a jarring experience for the Player.