Batch Send FreeSpin Operator Card

Sends a FREE SPIN Card to specified Players, supporting sending to multiple Players and multiple Games at once
Note: FREE SPIN Card: 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; if not provided, the system will generate it automatically
`round`	number	Yes	Number of rounds, upper limit is 100
`maxWinAmount`	number	No	Maximum win amount
`itemBet`	number	No	Operator Card Bet Amount; can be filled in by referencing the BetList, defaults to the minimum Bet if not provided
`multiple`	number	No	Free Spin Multiplier; can be set to 1/2/3/5x, defaults to 1x if not provided
`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 indicates success
`message`	string	Response message
`data.successList`	Object Array	List of items sent successfully
`data.failedList`	Object Array	List of items that failed to send
`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	Response code for the item send result
`message`	string	Response message for the item send result
`itemId`	string	System Operator Card ID; only generated in the successfully sent item list

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 the currency; please confirm whether the gameCode is correct
8	The User is not exist	Player does not exist; please create the Player first
78	Operator card spinId was used	Please use a different spinId; if you have any 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 recheck 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 and use the active item before sending again
89	The item has not been used yet, or the spinId does not exist	Please recheck whether the item has already been used, or whether the item has expired or 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 Matching: If spinId values are provided, their count must match the number of「Player Account」x「Game Code」combinations; otherwise, an error will be triggered
Immediate Effect: Every FREE SPIN Card sent successfully by this API takes effect immediately
Partial Sending: If some items fail to send, it will not cause the entire batch to fail

FAQ

Q1: Does the FREE SPIN Card sent by this API have an expiration time?

A: After sending, if the Player never logs in to the game to use it, the item will be automatically settled 12 hours after it was 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, but only 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 reminder message will be displayed, but the performance animation will not be replayed. If there are multiple settled records, only the most recent settlement record will be shown.

Q4: When 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 cannot be reused afterward; there will be no record of it in the backend or 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 midway and returns to the game, it will continue where it left off; settlement only occurs once all spins have been used.

Q6: What is the interaction logic between the Card's expiration time ("expiredTime") and automatic settlement?

A: Automatic settlement is fixed at 12 hours after sending. 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 send time, it will be capped at 12 hours, to avoid an inconsistent experience for the Player.

API Information​

request​

Request Headers​

Request Parameters​

Decrypted Request​

Parameters Before Encryption​

Response​

Success Response​

Error Response​

Error Codes​

Error Response Example​

Operator Card Parameter Combination Error​

Important Notes​

FAQ​

Q1: Does the FREE SPIN Card sent by this API have an expiration time?​

Q2: Can the FREE SPIN Card sent by this API be cancelled?​

Q3: Will the Player be notified after automatic settlement?​

Q4: When the expiration time is reached, will the Operator Card be automatically settled or cancelled?​

Q5: If the Player leaves the game while the FREE SPIN animation is playing, will it be automatically settled?​

Q6: What is the interaction logic between the Card's expiration time ("expiredTime") and automatic settlement?​

Related APIs​