Batch Send FreeSpin Operator Card

Send FREE SPIN cards to specified Players, supporting sending to multiple Players across 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, 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 according to BetList, if not provided, the minimum Bet will be used by default
multiple	number	No	Free Spin Multiplier, can be 1/2/3/5 times, if not provided, 1x will be used by default
expiredTime	string	No	Card Expiry 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	Item sending Success list
data.failedList	Object Array	Item sending failed list
logUUID	string	Request tracking ID for troubleshooting and log queries

• Item Sending 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, only generated in the Item Success sending 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 if 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 ask 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	Please ask the Player to re-enter the corresponding Game and use it before resending
89	The item has not been used yet, or the spinId does not exist	Reconfirm if the Item has been used or if the Item has expired/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

1. spinId Uniqueness: Each spinId must be unique and cannot be reused
2. spinId Completeness: If spinId is provided, it must match the quantity of "Player Account" x "Game Code", otherwise it will Trigger an error
3. Immediate Effect: Every FREE SPIN card successfully sent by this API takes immediate effect
4. Partial Sending: Failure to send some Items will not prevent the entire batch of Items from being sent

Common Q&A

Q1: Does the FREE SPIN card sent by this API have an expiry time?

A: It will automatically Settle 12 hours after sending, regardless of whether the Player logs in or uses the Card.

Q2: Can the FREE SPIN card sent by this API be canceled?

A: Yes, it can be canceled via the Cancel Operator Card API, but it must be done before the Player enters the Game to use it or before automatic Settlement. Otherwise, it cannot be canceled.

Q3: Will the Player be notified after automatic Settlement?

A: When the Player logs into the Game, a reward notification message will be displayed, but the performance animation will not be re-displayed. If there are multiple Settlement records, only the last Settlement record will be shown.

Q4: If the expiry time is reached, will the Operator Card automatically Settle or be canceled?

A: Canceled, and the Operator Card spinId cannot be reused. There will be no record of this transaction in the backend or bet logs.

Q5: If the Player leaves the Game during the Game animation, will the FREE SPIN automatically Settle?

A: If the Player exits midway and returns to the Game, it will continue to completion, and will only Settle once all uses are exhausted.

Q6: What is the interaction logic between "expiredTime" and automatic Settlement for the Card?

A: Expiry and invalidation times are always calculated from the moment of sending, regardless of whether the Player logs in or uses the Card. The default expiry time is 12 hours; even if expiredTime is set to more than 12 hours from the moment of sending, it will be reduced to 12 hours. If expiredTime is set to less than 12 hours, that set time will be the invalidation time, and the card will automatically expire when that time is reached.

Related APIs

• Cancel Operator Card
• Query Operator Card Status
• Batch Send FeatureGame Operator Card