Send FreeSpin Operator Card
Send a FREE SPIN card to a specified Player.
Note: FREE SPIN cards include: Free Spin Card, Multiplied 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 | Round Count, with an Upper Limit of 100 |
maxWinAmount | number | No | Maximum Win Amount |
itemBet | number | No | Operator Card Bet Amount. Refer to the BetList for valid values; 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 change the spinId. If you have any questions, contact Customer Support. |
| 86 | Game is restricted | Please refer to the Game List documentation or contact 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 re-check 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
Frequently Asked Questions
Q1: Does the FREE SPIN card sent by this API have an expiration time?
A: 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: Will the Player be notified after automatic settlement?
A: When the Player logs in to the game, a reward notification message 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 shown.
Q4: If the expiration time is reached, will the Operator Card be automatically settled or cancelled?
A: It will be cancelled, and that Operator Card's spinId can no longer be reused. There will be no record of it in the backend or in the bet history.
Q5: If the Player leaves the game while the FREE SPIN animation is playing, will it be automatically settled?
A: If the Player exits partway through and returns to the game, the free spins will continue until fully used, at which point it will be settled.
Q6: How does the card's expiration time ("expiredTime") interact with automatic settlement?
A: Automatic settlement always occurs 12 hours after the card is sent. Therefore, if the card's expiration time parameter 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 to avoid an inconsistent experience for the Player.