Grantify System
The grantify system refers to granting Free Spins or Features to specific users. The rewards generated from these spins can be either cash or bonus. If the reward is a bonus, the user must complete a certain wagering requirement before the bonus is converted to cash and credited to the user's account.
Interaction flow:
Note ⚠️: When distributing rewards, seamless wallet integration requires OP to provide a separate reward distribution API. Transfer wallet integration does not require this.
APIs Provided by 2J
| API Name | Description | Path |
|---|---|---|
| Query Grantify Config | Query grantify game configuration | /open2j/g/grantify/conf |
| Create Grantify | Create grantify | /open2j/g/grantify/create |
| Cancel Grantify | Cancel created grantify | /open2j/g/grantify/cancel |
| Query Grantify Status | Query status/progress of grantifies | /open2j/g/grantify/query |
1. Query Grantify Configuration
Method: POST
URI:: /open2j/g/grantify/conf
Description: Query bonus game configuration, including supported bonus game list and some default values.
Request Body:
Content-Type: application/json
{}Response Body:
Content-Type: application/json
{
"header": {
"code": 0, // Error code, 0 means success, non-0 means error
"msg": "",
"timestamp":1709716095516,
},
"result": {
"validaty_hours": 168, // Bonus validity period, in hours
"award_type": 1, // 1: Cash, 2: Bonus
"spin_type": 1, // 1: Free Spin, 2: Feature
"spin_times": 10, // Number of free spins
"mosaic_multiple": 8, // Wagering multiple required for bonus
"odds_limit": 1000, // Spin reward multiple limit
"game_ids": [1007, 1008, 1009], // Supported bonus game list
}
}2. Create Grantify
Method: POST
URI:: /open2j/g/grantify/create
Description: Create Grantify
Request Body:
Content-Type: application/json
{
"op_ids": [
"op123",
"op124",
], // User IDs
"game_id": 1007, // Bonus game ID
"bet": 1, // Bet amount per spin
"spin_type": 1, // Bonus type
"spin_times": 10, // Number of free spins
"award_type": 1, // Reward type
"mosaic_multiple": 8, // Wagering multiple for bonus
"validaty_hours": 168, // Bonus validity period (hours)
"odds_limit": 1000 // Spin reward multiple limit
}Parameter Description:
| Parameter | Type | Required | Description |
|---|---|---|---|
| op_ids | string[] | Yes | List of user IDs. Up to 100 per request |
| game_id | int | Yes | Bonus game ID, must be in game_ids returned by config API |
| bet | int | No | Bet amount per spin, default is game's minimum bet |
| spin_type | int | No | Bonus type, 1: Free Spin, 2: Feature, default from config API |
| spin_times | int | No | Number of free spins [1, 100], default from config API |
| award_type | int | No | Reward type, 1: Cash, 2: Bonus, default from config API |
| mosaic_multiple | int | No | Wagering multiple [1, 100], default from config API |
| validaty_hours | int | No | Bonus validity period (hours) [1, 168], default from config API |
| odds_limit | int | No | Spin reward multiple limit, default from config API |
Response Body:
Content-Type: application/json
{
"header": {
"code": 0, // Error code, 0 means success, non-0 means error
"msg": "",
"timestamp":1709716095516,
},
"result": [
{
"op_id": "op123", // OP side bonus ID
"grantify_id": "9995ed28d4e3882c", // Bonus ID
},
{
"op_id": "op124",
"grantify_id": "d03ba03818860d0a",
}
]
}3. Cancel Grantify
Method: POST
URI:: /open2j/g/grantify/cancel
Description: Cancel created grantify
Request Body:
Content-Type: application/json
{
"grantify_ids": [
"9995ed28d4e3882c",
"d03ba03818860d0a"
] // List of bonus IDs
}Parameter Description:
| Parameter | Type | Required | Description |
|---|---|---|---|
| grantify_ids | string[] | Yes | List of bonus IDs, up to 100 per request |
Response Body:
Content-Type: application/json
{
"header": {
"code": 0, // Error code, 0 means success, non-0 means error
"msg": "",
"timestamp":1709716095516,
},
"result": {
"grantify_ids": [
"9995ed28d4e3882c",
"d03ba03818860d0a"
] // Successfully cancelled bonus IDs
}4. Query Grantify Status/Progress
Method: POST
URI:: /open2j/g/grantify/query
Description: Query status/progress of created grantifies
Request Body:
Content-Type: application/json
{
"op_ids": [
"op123",
"op124"
], // List of user IDs
"grantify_ids": [
"9995ed28d4e3882c",
"d03ba03818860d0a"
], // List of bonus IDs
"game_id": 1007, // Bonus game ID
"created_from": 1, // Creation source: 1: OP API, 2: 2J backend, 3: 2J system
"state": 1, // Bonus status: 1: In progress, 2: Wagering, 3: Completed, 4: Cancelled, 5: Expired
"limit": 20, // Limit on number of results returned, default 20, max 100
"offset": 0 // Offset for results returned, default 0
}Parameter Description:
| Parameter | Type | Required | Description |
|---|---|---|---|
| op_ids | string[] | No | List of user IDs, up to 100 per request |
| grantify_ids | string[] | No | List of bonus IDs, up to 100 per request |
| game_id | int | No | Bonus game ID, must be in game_ids from config API. Default: all |
| created_from | int | No | Creation source: 1: OP API, 2: 2J backend, 3: 2J system. Default: all |
| state | int | No | Bonus status: 1: In progress, 2: Wagering, 3: Completed, 4: Cancelled, 5: Expired. Default: all |
| limit | int | No | Limit on number of results returned, default 20, max 100 |
| offset | int | No | Offset for results returned, default 0 |
Note ⚠️: op_ids and grantify_ids cannot both be empty; if both are provided, only their intersection is queried.
Response Body:
Content-Type: application/json
{
"header": {
"code": 0, // Error code, 0 means success, non-0 means error
"msg": "",
"timestamp":1709716095516,
},
"result": [
{
"grantify_id": "68bff8183377cc948464efb0", // Bonus ID
"op_id": "126012",
"game_id": 1066,
"left_hours": 1, // Remaining validity (if less than 1 hour, returns 1), in hours
"expired_at": 1758016152, // Expiry timestamp
"created_at": 1757411352, // Creation timestamp
"created_from": 1, // Creation source: 1: OP API, 2: 2J backend, 3: 2J system
"spin_type": 1, // Bonus type, 1: Free Spin, 2: Feature
"spin_times": 3, // Number of free spins
"award_type": 1, // Reward type
"award_amount": 0, // Reward amount
"odds_limit": 1000, // Reward Multiple limit
"mosaic_type": 1, // Wagering type, 1: Cash, 2: Bonus
"mosaic_multiple": 10, // Wagering multiple
"bet": 1000, // Bet amount per spin
"state": 3, // Bonus status: 1: In progress, 2: Wagering, 3: Completed, 4: Cancelled, 5: Expired
"activated": false // Activated or not
}
]
}APIs Provided by OP
If using seamless wallet integration, OP needs to provide a reward distribution API, which 2J will call when the user completes the bonus to credit the reward to the user's account.
| API Name | Description | Path |
|---|---|---|
| Reward API | Distribute reward to user | /grantify/reward |
1. Grantify Reward API
Method: POST
URI:: /grantify/reward
Description: Distribute grantify reward to OP merchant's user (for seamless wallet integration).
OP must ensure idempotency for this API to avoid duplicate rewards; if a duplicate request is received, return success (code = 0).
Request Body:
Content-Type: application/json
{
"op_id": "op123", // User ID
"timestamp": 1709716095, // Request timestamp, milliseconds
"award_amount": 100, // Reward amount
"grantify_id": "9995ed28d4e3882c", // Bonus ID
}Parameter Description:
| Parameter | Type | Required | Description |
|---|---|---|---|
| op_id | string | Yes | User ID |
| timestamp | int | Yes | Request timestamp, ms |
| amount | int | Yes | Reward amount |
| grantify_id | string | Yes | Bonus ID |
Response Body:
Content-Type: application/json
{
"header": {
"code": 0, // Error code, 0 means success, non-0 means error
"msg": "",
"timestamp":1709716095516,
},
"result": {
"op_id": "op123", // User ID
}
}