Rewards API

Rewards API is used for granting rewards, and reward campaigns to one or multiple users. First-time user's bonuses are supported by most suppliers, however, in some cases a user must interact with the game before a free reward can be granted.

Rewards API Reference

Create a reward


POST /operator/generic/v2/rewards/create HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 337

{
  "user": "john12345",
  "sub_partner_id": "my-platform-id",
  "start_time": "2017-11-05T13:15:30",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "operator_id": 1,
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
  "reward_value": 100500,
  "reward_count": 5,
  "operator_reference": "text"
}

The endpoint for creating one reward. You can create rewards of 2 types: Single-use and Campaign-related.

Creating a Single-use reward

Get a list of available prepaids via /prepaids/list endpoint and select a prepaid.
Add the prepaid_uuid to request.
If the reward_value and/or the reward_count in the prepaid's value is set to NULL, you can enter any values. Otherwise, the values from the prepaid will be used to create the reward.

Creating a Campaign-related reward

Create a campaign via POST campaigns/create.
Pass the campaign_uuid.
prepaid_uuid, reward_value, reward_count, start_time, and end_time values will be inherited from the campaign.

We strongly recommend that you set the start / end dates for individual rewards and campaigns. Otherwise, the rewards will automatically expire in several weeks.

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

user - string · min: 3 · required

The unique user ID in the Operator’s system. In case of DEMO gameplay, this parameter may be omitted.
Example: john12345

sub_partner_id - string · optional

ID of Operator's sub-partner (brand, whitelabel, site, etc.) which uses same integration and credentials as an Operator. Used for detailed reporting and integration type switching. Sites under the same Operator can use different integration types: TransferWallet or SeamlessWallet. A single site (sub_partner_id) can NOT have both kinds of integration at the same time.
Example: my-platform-id

start_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

prepaid_uuid - string · optional

Standard 16-byte unique user ID (UUID) on Nirova side referencing a prepaid reward.
Example: 0e6bde62-4713-4b85-b510-59f0d729d8f7

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

game_code - string · optional

The unique game identifier in Nirova system. game_code can be obtained from the /game/list endpoint.
Example: clt_softwareid

end_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

campaign_uuid - string · optional

The unique campaign ID in Nirova side, displayed in standard 16-byte UUID format.
Example: 7b5c8a93-4d3a-4bfb-8554-f923d46aa485

reward_value - integer · optional

The amount of money displayed in integer (Int64) format. To convert real float value to integer, it is multiplied by 100000. Example: $3.56 is represented as 356000
Example: 100500

reward_count - integer · optional

Example: 5

operator_reference - string · optional

The unique reference of reward on the Operator's side.

Responses

{
  "user": "john12345",
  "start_time": "2017-11-05T13:15:30",
  "reward_uuid": "a28f93f2-98c5-41f7-8fbb-967985acf8fe",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "currency": "EUR",
  "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
  "reward_value": 100500,
  "reward_count": 5
}

Create multiple rewards in bulk


POST /operator/generic/v2/rewards/create_bulk HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 349

{
  "users": [
    {
      "user": "john12345",
      "operator_reference": "text"
    }
  ],
  "sub_partner_id": "my-platform-id",
  "start_time": "2017-11-05T13:15:30",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "operator_id": 1,
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
  "reward_value": 100500,
  "reward_count": 5
}

The endpoint for creating multiple rewards.

The process is similar to creating one reward (see POST /operator/generic/v2/rewards/create), but instead of one user you need to provide a list of users. All user's items need to include user and a unique operator_reference per user.

operator_reference is a unique identifier of a reward from the Operator's side to ensure accuracy of the rewards.

The reward properties need to be provided once per request and they will be used to create all the rewards in the request.

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

users - object[] · required

The unique user ID in the Operator’s system. In case of DEMO gameplay, this parameter may be omitted.
Example: john12345

operator_reference - string · optional

The unique reference code for a reward on the Operator's side.

sub_partner_id - string · optional

ID of Operator's sub-partner (brand, whitelabel, site, etc.) which uses same integration and credentials as an Operator. Used for detailed reporting and integration type switching. Sites under the same Operator can use different integration types: TransferWallet or SeamlessWallet. A single site (sub_partner_id) can NOT have both kinds of integration at the same time.
Example: my-platform-id

start_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

prepaid_uuid - string · optional

Standard 16-byte unique user ID (UUID) on Nirova side referencing a prepaid reward.
Example: 0e6bde62-4713-4b85-b510-59f0d729d8f7

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

game_code - string · optional

The unique game identifier in Nirova system in the form of a string. game_code can be obtained from the /game/list endpoint.
Example: clt_softwareid

end_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

campaign_uuid - string · optional

The unique campaign ID in Nirova side, displayed in standard 16-byte UUID format.
Example: 7b5c8a93-4d3a-4bfb-8554-f923d46aa485

reward_value - integer · optional

The amount of money displayed in integer (Int64) format. To convert real float value to integer, it is multiplied by 100000. Example: $3.56 is represented as 356000
Example: 100500

reward_count - integer · optional

Example: 5

Responses

{
  "reward": {
    "start_time": "2017-11-05T13:15:30",
    "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
    "game_code": "clt_softwareid",
    "end_time": "2017-11-05T13:15:30",
    "currency": "EUR",
    "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
    "reward_value": 100500,
    "reward_count": 5
  },
  "success": [
    {
      "user": "john12345",
      "operator_reference": "9a049723-da79-42c6-b630-09509be86688",
      "reward_uuid": "379c1408-00bf-498a-8597-e98d081d0088"
    },
    {
      "user": "amy12345",
      "operator_reference": "1018a15b-2547-4c47-ad6f-252538b7da58",
      "reward_uuid": "80a83382-836b-4ed5-bef0-867d49ea87ab"
    }
  ],
  "failed": [
    {
      "user": "mark12345",
      "operator_reference": "72a70bac-5493-4cd3-95e8-80e3236f6d5e",
      "reason": "Operator refence was already used for different reward."
    }
  ],
  "error": true,
  "message": "Not all rewards were created successfully, please see specific reasons from failed."
}

Cancel a reward


POST /operator/generic/v2/rewards/cancel HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "reward_uuid": "a28f93f2-98c5-41f7-8fbb-967985acf8fe",
  "operator_id": 1,
  "operator_reference": "reward_001"
}

The endpoint for cancelling a granted reward. Note that a reward already claimed by a user cannot be canceled. Either reward_uuid or operator_reference must be specified.

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

reward_uuid - string · optional

The unique identifier for a reward on Nirova side in standard 16-byte UUID format.
Example: a28f93f2-98c5-41f7-8fbb-967985acf8fe

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

operator_reference - string · optional

The unique reference of reward on the Operator's side.
Example: reward_001

Responses

{
  "user": "john12345",
  "start_time": "2017-11-05T13:15:30",
  "reward_uuid": "a28f93f2-98c5-41f7-8fbb-967985acf8fe",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "currency": "EUR",
  "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
  "reward_value": 100500,
  "reward_count": 5
}

Get a list of available prepaids


POST /operator/generic/v2/reward/prepaids/list HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "operator_id": 1,
  "game_code": "clt_softwareid",
  "currency": "EUR"
}

Provides a list of all available prepaids. Prepaids with field bonus_buy set to true are meant to give a free bonus buy and are not suitable to be used for multiple (reward_count).

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

game_code - string · required

The unique game identifier in Nirova system in the form of a string. game_code can be obtained from the /game/list endpoint.
Example: clt_softwareid

currency - string · enum · required

The ISO 4217 currency code. The following list contains all currencies supported by our system. Note that native gameplay support for these currencies may vary per Provider. Please contact us to know which Provider supports which currencies.
Example: EUR
Available options: BSD, TTD, ZMW, BMD, USD, BYR, UGX, HKD, MGA, GIP, UZS, MKD, PTS, mLTC, EGP, AWG, CZK, ILS, MZN, TND, XPF, SOS, DOP, RUB, KRW, BTN, KGS, BAM, AOA, SOC, AMS, BND, RSD, FKP, PEN, EOS, GHS, JPY, TRY, SBD, UAH, LTL, FJD, GNF, MDL, AFN, ZAR, MOP, TJS, BOB, JMD, QAR, IRR, SYP, XXX, NAD, MYR, CUP, NOK, BGN, KPW, MNT, NZD, uETH, SGD, PYG, OMR, DZD, EUR, TMT, MMK, PTQ, ANG, TZS, CRC, CVE, SET, BTH, BZD, LYD, CHF, MVR, KES, CVE, LSL, KMF, SZL, KYD, BRL, AED, WST, YER, ALL, TRX, HUF, GTQ, uBTC, IDR, MWK, CUC, DKK, TWD, XCD, BBD, LRD, KZT, JOD, BYN, BIF, PLN, SDG, VUV, SEK, BDT, HNL, BWP, VND, ISK, SLL, BHD, HTG, USDt, ADA, MUR, ERN, uLTC, LKR, COP, GEL, AUD, GBP, CAD, PHP, PAB, DJF, GMD, PKR, NIO, AMD, RWF, RON, NGN, TOP, UYU, AZN, SRD, KWD, PGK, CDF, SAR, IQD, XRP, SCR, mETH, MAD, GYD, INR, LBP, ARS, MXN, CLP, BNB, CNY, KHR, LAK, HRK, BZD, SSP, XOF, XAF, MRU, NPR, mBTC

Responses

[
  {
    "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
    "game_code": "clt_softwareid",
    "currency": "EUR",
    "reward_value": 100500,
    "reward_count": 5,
    "bonus_buy": true,
    "meta": {}
  }
]

The prepaid object defines the format and size of the rewards set by the game Supplier. If reward_count is set as null, there are no constraints applied to it. Reward size (reward_value) is defined by the number of lines, minimum and maximum reward limits and other in-game math.

Create a campaign


POST /operator/generic/v2/reward/campaigns/create HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 272

{
  "start_time": "2017-11-05T13:15:30",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "operator_id": 1,
  "name": "st. patrick 5 x 1.005 EUR",
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "reward_value": 100500,
  "reward_count": 5,
  "operator_reference": "reward_001"
}

Creating a campaign:

Get a list of available prepaids via /prepaids/list and select a prepaid.
Add the prepaid_uuid to request..
If reward_value and/or reward_count in the prepaid is NULL, you can enter any values. Otherwise, the values from the prepaid will be used to create the reward.
Submit /campaigns/create request.

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

start_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

prepaid_uuid - string · required

Standard 16-byte unique user ID (UUID) on Nirova side referencing a prepaid reward.
Example: 0e6bde62-4713-4b85-b510-59f0d729d8f7

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

name - string · required

The name of the campaign.
Example: st. patrick 5 x 1.005 EUR

game_code - string · optional

The unique game identifier in Nirova system in the form of a string. game_code can be obtained from the /game/list endpoint.
Example: clt_softwareid

end_time - string · ISO-8601 · optional

The date and time combination in ISO 8601 Extended format (YYYY-MM-DDThh:mm:ss).
Example: 2017-11-05T13:15:30

reward_value - integer · optional

The amount of money displayed in integer (Int64) format. To convert real float value to integer, it is multiplied by 100000. Example: $3.56 is represented as 356000
Example: 100500

reward_count - integer · optional

Example: 5

operator_reference - string

The unique reference of a campaign on the Operator's side.
Example: reward_001

Responses

{
  "start_time": "2017-11-05T13:15:30",
  "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
  "name": "st. patrick 5 x 1.005 EUR",
  "game_code": "clt_softwareid",
  "end_time": "2017-11-05T13:15:30",
  "currency": "EUR",
  "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
  "reward_value": 100500,
  "reward_count": 5
}

Nirova campaign item. Campaign is a form of grouping many rewards by common fields. Example: 'Christmas Campaign'

Get a list of campaigns


POST /operator/generic/v2/reward/campaigns/list HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "operator_id": 1
}

Provides a list of available campaigns.

Header parameters

uX-Nirova-Signature - any · required

RSA-SHA256 is used to sign the request body using the private key. The signature is validated using the public key associated with the provided operator_id.

Body

operator_id - integer · required

Unique identifier for the Operator in Nirova system. Used to authorize incoming requests. You can obtain your operator_id from the Nirova BackOffice after your Operator entity is registered and set up in the Nirova system by the internal teams.
Example: 1

Responses

[
  {
    "start_time": "2017-11-05T13:15:30",
    "prepaid_uuid": "0e6bde62-4713-4b85-b510-59f0d729d8f7",
    "name": "st. patrick 5 x 1.005 EUR",
    "game_code": "clt_softwareid",
    "end_time": "2017-11-05T13:15:30",
    "currency": "EUR",
    "campaign_uuid": "7b5c8a93-4d3a-4bfb-8554-f923d46aa485",
    "reward_value": 100500,
    "reward_count": 5
  }
]

Nirova campaign item. Campaign is a form of grouping many rewards by common fields. Example: 'Christmas Campaign'