Purchase Rewards

The purchase reward API is mainly responsible for rewarding your player score and points through Purchase Reward program based on the actual paid amount by your players.

Gameball allows you to reward your players with score, points, or both based on the configured settings on Gameball Purchase Reward program. To learn more about puchase rewards, check this article at our Help Center.

Reward can be sent along with Events and Redemption using Actions Composite API endpoint.

The following APIs use Hashing Function SHA1, check how hashing is done below.

Reward Points

POST /integrations/transaction/reward

Access reward points API to reward your players for each unit currency they actually paid for your product or service.

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
merchant	object	Merchant object as described in Object reference section
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
amount	number	Monetary value that the player will be rewarded for based on the Purchase Reward program configurations. (Amount must be positive).
transactionId	string	Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
transactionTime	string	Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.
hash	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hashing is automatically handled when using server-side SDKs.
playerAttributes	object	An object containing all of the attributes of the player. Player object is described in Object Reference section.

200 Success.

{
    "playerUniqueId": "player123",
    "playerAttributes": null,
    "gameballTransactionId": 17178,
    "amount": "99.98",
    "transactionId": "tra_123456789",
    "transactionTime": "2019-09-19T16:14:09.895Z"
}

400 JSON Body Invalid or missing required parameters. The response will include error description payload described in Errors section.

{
    "code": 4,
    "message": "The Amount field is required."
}

401 Invalid APIKey.

{}

402 Request failed. The response will include error description payload described in Errors section.

{
    "code": 305,
    "message": "Transaction with Id tra_123456789 has already been placed"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
playerAttributes	An object containing all of the attributes of the player. Player Object is described in Object Reference section.
gameballTransactionId	Transaction ID on Gameball system.
amount	Monetary value that the player will be rewarded for based on the Purchase Reward. (Amount must be positive)
transactionId	Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
transactionTime	Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note:transactionTime is automatically handled when using server-side SDKs.
points	The number of points rewarded to the player for the specified amount

In case the player doesn't exist on Gameball before sending the Purchase Reward API call, the player will be created automatically on Gameball and granted the points.

Usage Examples

Example One

The example shown is a request sent to Gameball when you want to reward a player ofplayerUniqueId"player123" with points equivalent to amount of 99.98. The points to be granted will be according to your points configurations on Purchase Reward program.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player123",
   "amount":99.98,
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "hash":"f3437e2919ab9f853c7ccde92f4f2b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/reward'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball-nodejs-sdk')
var Gameball = new gameball(apikey,transactionKey)
Gameball.rewardPoints({
        "playerUniqueId": "player123",
        "amount": 99.98,
        "transactionId" : "tra_123456789" 
    },
    function(err, res) {
        if (err) console.log(err)
        else console.log(res)
    })

Ruby

require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball.transaction_key = "90byuedhb7y37d2bd22ybshsn82"
Gameball::Transaction.reward_points({
  playerUniqueId: "player123",
  amount: 99.98,
  transactionId: "tra_123456789"
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
RewardPointsRequest request = new RewardPointsRequest() {
  PlayerUniqueId = "player123",
  Amount = 99.98,
  TransactionId = "tra_123456789"
};
var reward_points_response = Gameball.RewardPoints(request);

PHP

require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$transactionKey = "90byuedhb7y37d2bd22ybshsn82";
$gameball = new \Gameball\GameballClient(apiKey,transactionKey);
$playerRequest =new \Gameball\Models\PlayerRequest();
$playerRequest->playerUniqueId='player123';
$amount = '99.98';
$transactionId ='tra_123456789';

$rewardPointsResponse= $gameball->transaction->rewardPoints($playerRequest,$amount ,$transactionId);

Python

import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
transactionKey = "90byuedhb7y37d2bd22ybshsn82"
gameball.api_key = apiKey
gameball.transaction_key = transactionKey

request = gameball.rewardObject(player_unique_id= "player123", amount= 99.98, transaction_id= "tra_123456789")
reward_points_response = gameball.reward_points(request)

Example Two

The example shown is a request sent to Gameball when you want to reward a player ofplayerUniqueId"player456" with points equivalent to amount of 2500.

In addition to reward information, playerAttributes object is sent to Gameball to create or update player details in our system with any custom attributes.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "amount":2500,
   "transactionId":"tra_123456789",
   "playerAttributes":{
      "displayName":"Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1978-01-11T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "custom": {
            "location":"Miami",
            "graduationDate":"2018-07-04T21:06:29.158Z",
            "isMarried":false
        }
   },
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "hash":"f3437e2919ab9f853c7ccde92f4f2b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/reward'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.rewardPoints({
    "playerUniqueId": "player456",
    "amount": 2500,
    "transactionId": "tra_123456789",
    "playerAttributes": {
        "displayName": " Tyrion Lannister",
        "firstName": "Tyrion",
        "lastName": "Lannister",
        "email": "[e-mail]",
        "gender": "M",
        "dateOfBirth": "1978-01-11T00:00:00.000Z",
        "joinDate": "2019-09-19T21:06:29.158Z",
        "custom": {
            "location": "Miami",
            "graduationDate": "2018-07-04T21:06:29.158Z",
            "isMarried": false
        }
    }
})
},
function(err, res) {
    if (err) console.log(err)
    else console.log(res)
})

Ruby

require 'gameball'
Gameball.api_key = "807b041b7d35425988e354e1f6bce186"
Gameball.transaction_key = "90byuedhb7y37d2bd22ybshsn82"
Gameball::Transaction.reward_points({
	playerUniqueId:"player456",
	amount:2500,
	transactionId:"tra_123456789",
	playerAttributes:{
		displayName:" Tyrion Lannister",
		firstName:"Tyrion",
		lastName:"Lannister",
		email:"[e-mail]",
		gender:"M",
		dateOfBirth:"1978-01-11T00:00:00.000Z",
		joinDate:"2019-09-19T21:06:29.158Z",
		custom:{
			location:"Miami",
			graduationDate:"2018-07-04T21:06:29.158Z",
			isMarried:false
		}
	}
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
RewardPointsRequest request = new RewardPointsRequest()
	{
		PlayerUniqueId = "player456",
		Amount = 2500,
		TransactionId = "tra_123456789",
		PlayerAttributes = new PlayerAttributes()
		{
		 DisplayName = "Tyrion Lannister",
		 FirstName = "Tyrion",
		 LastName = "Lannister",
		 Email = "[e-mail]",
		 Gender = "M",
		 DateOfBirth = new DateTime(1978,1,11),
	     JoinDate = new DateTime (2019,9,19,21,6,29,158)
		 
		}
	};
//Adding Custom Attributes
request.PlayerAttributes.AddCustomAttribute("location", "Miami");
request.PlayerAttributes.AddCustomAttribute("graduationDate", new DateTime(2018, 7, 4, 21, 6, 29, 158));
request.PlayerAttributes.AddCustomAttribute("isMarried", false);

var reward_points_response = Gameball.RewardPoints(request);

PHP

require_once('vendor/autoload.php');
$apiKey = "807b041b7d35425988e354e1f6bce186";
$transactionKey = "90byuedhb7y37d2bd22ybshsn82";
$gameball = new \Gameball\GameballClient(apiKey,transactionKey);

//All are optional
//displayName, firstName, lastName, email, gender, mobileNumber, dateOfBirth
$playerAttributes = new \Gameball\Models\PlayerAttributes();

$playerAttributes->displayName ='Tyrion Lannister';
$playerAttributes->firstName ='Tyrion';
$playerAttributes->lastName ='Lannister';
$playerAttributes->email ='[e-mail]';
$playerAttributes->gender ='M';
$playerAttributes->dateOfBirth ='1978-01-11T00:00:00.000Z';

//custom attributes <Key => Value>
$playerAttributes->addCustomAttribute('location','Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');
$playerAttributes->addCustomAttribute('isMarried' , false);

$playerRequest =new \Gameball\Models\PlayerRequest();
$playerRequest->playerUniqueId='player456';
$playerRequest->playerAttributes= $playerAttributes;
$amount = '2500';
$transactionId ='tra_123456789';

$rewardPointsResponse= $gameball->transaction->rewardPoints($playerRequest,$amount ,$transactionId);

Python

import gameball
apiKey = "807b041b7d35425988e354e1f6bce186"
transactionKey = "90byuedhb7y37d2bd22ybshsn82"
gameball.api_key = apiKey
gameball.transaction_key = transactionKey

request = gameball.rewardObject(player_unique_id= "player456", amount= 2500, transaction_id= "tra_123456789")
request.add_player_attribute("displayName", " Tyrion Lannister")
request.add_player_attribute("firstName", "Tyrion")
request.add_player_attribute("lastName", "Lannister")
request.add_player_attribute("email", "[e-mail]")
request.add_player_attribute("gender", "M")
request.add_player_attribute("dateOfBirth", "1978-01-11T00:00:00.000Z")
request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
request.add_custom_player_attribute("location", "Miami")
request.add_custom_player_attribute("graduationDate", "2018-07-04T21:06:29.158Z")
request.add_custom_player_attribute("isMarried", False)
reward_points_response = gameball.reward_points(request)