Transactions

Transactions API is responsible for all the player's points transactions.

Transactions are player's points transactions, through which they earn and redeem points. Transactions have two types: accumulation and deduction. Learn more about Transactions through our Help Center.

The following APIs use Hashing Function SHA1, Check how Hashing is done below

Player Points Balance

POST /integrations/transaction/balance

The API call is used to retrieve player's current points balance available for redemption and the corresponding equivalent amount.

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
hash	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hashing is automatically handled when using server-side SDKs.

200 Success.

{
    "pointsBalance": 11500,
    "pointsValue": 115,
    "currency": "EGP",
    "pointsName": "Points"
}

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

{
    "code": 11,
    "message": "BodyHashed Invalid"
}

401 Invalid APIKey.

{}

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

{
    "code": 101,
    "message": "No Player with this External ID"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
pointsBalance	Player points
pointsValue	The actual value equivalent to player points.
currency	Store currency
pointsName	The custom name selected instead of points, which appears to players.

Usage Example

The example shown is a request sent to Gameball to get a player's balance with his playerUniqueId

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "hash":"7090689dc127ddfbe4a7c2260060afe5e6fc3264g"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/balance'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.getPlayerBalance({
        "playerUniqueId": "player456"
    },
    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.get_player_balance("player456")

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);

var get_balance_response = Gameball.GetPlayerBalance("player456");

PHP

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

$playerUniqueId = 'player456';

$getBalanceResponse= $gameball->transaction->getPlayerBalance($playerUniqueId);

Python

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

get_balance_response = gameball.get_player_balance(player_unique_id= "player456")

Hold Points

POST /integrations/transaction/hold

The API is used to hold a specific amount of points from the player’s points balance. This is used to guarantee the availability of the points to be redeemed until the checkout process is completed. After a successful call, the API returns a hold reference number that is used later in the redemption API. Hold is active at Gameball for 10 minutes and automatically expires afterwards.Once the hold expires, the points are returned back to the player balance if this hold was not followed by a Redeem transaction.

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
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.
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
amount	string	Monetary value in the system currency to be held from the player points balance on Gameball.
hash	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hash is automatically handled when using server-side SDKs.

200 Success.

{
    "playerUniqueId": "player456",
    "amount": "98.89",
    "holdReference": "ca84504a-edc3-4ff8-9aa1-e9cf186cf95c",
    "otp": null,
    "transactionTime":"2019-09-21T16:53:28.190Z"
}

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

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

401 Invalid APIKey.

{}

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

{
    "code": 304,
    "message": "This not valid transaction"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
amount	Monetary value in the system currency to be held from the player points balance on Gameball.
holdReference	Hold reference ID to be used in points redemption.
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.

Usage Example

The example shown is a request sent to Gameball to hold player points with playerUniqueId"player456" equivalent to amount of "98.89".

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "amount":98.89,
   "transactionTime":"2019-09-21T16:53:28.190Z",
   "hash":"7090689dc127ddfbe4a7c2260060afe5e6fc3264g"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/hold'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.holdPoints({
        "playerUniqueId": "player456",
        "amount": 98.89
    },
    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.hold_points({
  playerUniqueId: "player456",
  amount: 98.89
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
HoldPointsRequest request = new HoldPointsRequest() {
  Amount = 98.89,
  PlayerUniqueId = "player456"
};
var hold_points_response = Gameball.HoldPoints(request);

PHP

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

$playerUniqueId ='player456';
$amount ='98.89';

$holdPointsResponse= $gameball->transaction->holdPoints($playerUniqueId,$amount);

Python

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

hold_points_response = gameball.hold_points(player_unique_id= "player456", amount= 98.89)

Redeem Points

POST /integrations/transaction/redeem

The API enables the player to use Gameball points as a payment method since it can be substituted for monetary values. A successful call will return the ID of the redeemed transaction reference created at Gameball.

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
holdReference	string	Hold reference ID received after calling Hold Points API.
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball.
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: hash is automatically handled when using server-side SDKs.

200 Success.

{
    "playerUniqueId": "player456",
    "playerAttributes": null,
    "gameballTransactionId": 17179,
    "transactionId": "tra_123456789",
    "holdReference": "ca84504a-edc3-4ff8-9aa1-e9cf186cf95c",
    "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 PlayerUniqueId field is required."
}

401 Invalid APIKey.

{}

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

{
    "code": 307,
    "message": "No Hold Points with this HoldReference and External ID"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
playerAttributes	Player attributes used to create/update the Player with unique Id in Gameball. Player Object is described in Object Reference section.
gameballTransactionId	Transaction ID on Gameball system.
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.
holdReference	Hold reference ID to be used in points redemption.
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.

Usage Example

The example shown is a request sent to Gameball to redeem an amount equivalent to the amount held in the holdReference for player with playerUniqueId"player456".

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "transactionId":"tra_123456789",
   "holdReference":"2342452352435234",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "hash":"ccde92f4ff3437e2919ab9f853c72b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/redeem'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.redeemPoints({
        "playerUniqueId": "player456",
        "transactionId": "tra_123456789",
        "holdReference": "2342452352435234"
    },
    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.redeem_points({
	playerUniqueId:"player456",
	transactionId:"tra_123456789",
	holdReference:"2342452352435234"
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
RedeemPointsRequest request = new RedeemPointsRequest() {
  PlayerUniqueId = "player456",
  TransactionId = "tra_123456789",
  HoldReference = "2342452352435234"
};
var redeem_points_response = Gameball.RedeemPoints(request);

PHP

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

$request = new \Gameball\Models\RedeemPointsRequest();
$request->playerUniqueId = 'player456';
$request->holdReference = '2342452352435234';
$request->transactionId = 'tra_123456789';


$redeemPointsResponse= $gameball->transaction->redeemPoints($request);

Python

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

redeem_points_response = gameball.redeem_points(player_unique_id = "player456",
  hold_reference = "2342452352435234", transaction_id = "tra_123456789")

Redemption can be sent along with events and reward using Actions Composite API endpoint.

Reverse Transaction

POST /integrations/transaction/cancel

The API is used to cancel a purchase reward transaction or refund a points redemption transaction on Gameball. Using transactionId, Gameball will check if there is a purchase reward transaction or a redemption transaction linked to this transactionId, then complete the process. After successful submission, the canceled or refunded transaction will update the player’s point balance accordingly.

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
amount	number	The amount to be refunded from the transaction. The whole order is cancelled if not provided
playerUniqueId	string	Player unique identifier used to uniquely identify the player on Gameball
transactionId	string	Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number.
reversedTransactionId	string	Unique transaction ID which identifies the underlying reversed transaction in your system, e.g. canceled order number, refunded 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. canceled order datetime, refunded 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.

200 Success.

{
 "playerUniqueId": "player456",
 "gameballTransactionId": 17178,
 "transactionId": "1234567890",
 "reversedTransactionId": "2345678901",
 "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": 5,
    "message": "JSON Body Invalid"
}

401 Invalid APIKey.

{}

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

{
    "code": 301,
    "message": "Transaction Type Non Reversable"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
gameballTransactionId	Transaction ID on Gameball system.
reversedTransactionId	Unique transaction ID which identifies the underlying reversed transaction in your system, e.g. canceled order number, refunded invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
transactionId	Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number.
transactionTime	Time of transaction in your system in UTC, e.g. canceled order datetime, refunded invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.

Usage Example

The example shown is a request sent to Gameball after canceling a transactionId “234567891” on your system.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "transactionId":"1234567890",
   "reversedTransactionId":"234567891",
   "transactionTime":"2019-09-19T11:14:09.895Z",
   "hash":"19ab9f853c7ccde9f3437e292f4f2b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/cancel'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.reverseTransaction({
        "playerUniqueId": "player456",
        "transactionId": "1234567890",
        "reversedTransactionId": "234567891"
    },
    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.reverse_transaction({
  playerUniqueId: "player456",
  transactionId: "1234567890",
  reversedTransactionId: "234567891"
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
ReverseTransactionRequest request = new ReverseTransactionRequest() {
  PlayerUniqueId = "player456",
  TransactionId = "1234567890",
  ReversedTransactionId = "234567891"
};
var reverse_transaction_response = Gameball.ReverseTransaction(request);

PHP

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

$playerUniqueId = 'player456';
$transactionId='1234567890';
$reversedTransactionId= '234567891';

$reverseTransactionResponse= $gameball->transaction->reverseTransaction($playerUniqueId,$transactionId,$reversedTransactionId);

Python

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

reverse_transaction_response = gameball.reverse_transaction(player_unique_id = "player456", transaction_id = "1234567890",
  reversed_transaction_id = '234567891')

Reverse Hold

POST /integrations/transaction/hold

The API call is used to cancel previously held points. It can be called to cancel non-expired hold requests within the 10 minutes validity period.

Headers

Name	Type	Description
API Key	string	Client API key

Request Body

Name	Type	Description
playerUniqueId	string	Player unique identifer used to uniquely identify the player on Gameball.
holdReference	string	Hold reference number to be cancelled as received from Gameball.
transactionTime	string	Time of transaction in your system in UTC, e.g. canceled hold 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: hash is automatically handled when using server-side SDKs.

200 Success.

{
   "playerUniqueId":" player456",
   "amount": null,
   "holdReference":"9245fe4a-d402-451c-b9ed-9c1a04247482",
   "transactionTime":"2019-09-21T16:53:28.190Z"
}

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

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

401 Invalid APIKey.

{}

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

{
    "code": 304,
    "message": "This not valid transaction"
}

403 APIKey missing.

{}

Response Description

Attribute	Description
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
amount	Monetary value equivalent to the number of points that was released from hold in Gameball.
holdReference	Hold reference ID cancelled/refunded.
transactionTime	Time of transaction in your system in UTC, e.g. canceled order datetime, refunded invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.

Usage Example

The example shown is a request sent to Gameball to remove held points with playerUniqueId"player456" an holdReference equals “9245fe4a-d402-451c-b9ed-9c1a04247482“.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":" player456",
   "holdReference":"9245fe4a-d402-451c-b9ed-9c1a04247482",
   "transactionTime":"2019-09-21T16:53:28.190Z",
   "hash":"7090689dc127d260060afe5e6fc3264dfbe4a7c2"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/hold'

Node.js

var apiKey = '807b041b7d35425988e354e1f6bce186'
var transactionKey = '90byuedhb7y37d2bd22ybshsn82'
var gameball = require('gameball')
var Gameball = new gameball(apikey,transactionKey)
Gameball.reverseHold({
        "playerUniqueId": "player456",
        "holdReference": "9245fe4a-d402-451c-b9ed-9c1a04247482"
    },
    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.reverse_hold({
  playerUniqueId: " player456",
  holdReference: "9245fe4a-d402-451c-b9ed-9c1a04247482"
})

.NET

using Gameball;
using Gameball.Models;
var apiKey = "807b041b7d35425988e354e1f6bce186";
var transactionKey = "90byuedhb7y37d2bd22ybshsn82";
var Gameball = new Gameball(apiKey,transactionKey);
ReverseHoldRequest request = new ReverseHoldRequest() {
  PlayerUniqueId = "player456",
  HoldReference = "9245fe4a-d402-451c-b9ed-9c1a04247482"
};
var reverse_hold_response = Gameball.ReverseHold(request);

PHP

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

$playerUniqueId = 'player456' ;
$holdReference ='9245fe4a-d402-451c-b9ed-9c1a04247482';

$reverseHoldResponse= $gameball->transaction->reverseHold($playerUniqueId,$holdReference);

Python

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

reverse_hold_response = gameball.reverse_hold(player_unique_id = "player456", hold_reference = "9245fe4a-d402-451c-b9ed-9c1a04247482")

Manual Transaction

POST /integrations/transaction/manual

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

Headers

Name	Type	Description
APIKey	string	Client API key

Request Body

Name	Type	Description
points	integer	Number of points to be rewarded to or deducted from the player. a "+" value is accumulation while a "-" value is deduction.
reason	string	Represents the reason you wish to specify as to why the player is being rewarded.
username	string	Represents the username of the user in your system that is performing the manual reward for the player.
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 Redemption Rate. (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."
}

{
    "code": 4,
    "message": "Username is required for manual rewarding."
}

{
    "code": 4,
    "message": "Reason is required for manual rewarding."
}

{
    "code": 4,
    "message": "Reason is required for manual rewarding."
}

{
    "code": 7,
    "message": "Only one method of rewarding should be specified. Please specify either points or amount."
}

{
    "code": 7,
    "message": "Points rewarded should not be equal to Zero."
}

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.

{}

Either the amount or the points should be sent along with the request.

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

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 Redemption Rate. (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

List Transactions

POST /integrations/transaction/list

Used to get transactions from Gameball. The result are paged and can be filtered.

Query Parameters

Name	Type	Description
page	string	result page number. Starts from 1
limit	string	result page size. Default is 50 transactions and max is 200

Headers

Name	Type	Description
APIKey	string	Client API Key

Request Body

Name	Type	Description
transactionId	string	ID of transaction to be retrieved. If provided, the details of the transaction and its related transactions are returned
direction	string	"+" or "-" to return deduction or addition transactions
from	object	from date
to	object	to date
hash	string	Hashed body with SH1 algorithm. As described in hashing transaction messages section

200

{
   "transactions":[
      {
         "transactionId":"trx123",
         "gameballTransactionId":"gbtrx123",
         "transactionTime":"2019-09-21T16:53:28.190Z",
         "type":"Cash Back",
         "direction":"+",
         "playerUniqueId":"1234",
         "points":500,
         "amount":10,
         "merchantName":"merchant",
         "branchName":"branch"
      }
   ],
   "count":50,
   "total":344
}

Response Description

Attribute	Description
transactions	array of paged transactions ordered by date desc.
count	returned transactions list count
total	total number of transactions avialable matching the applied filters

transaction object

Attribute	Description
transactionId	Transaction ID as recieved from external system
gameballTrasnactionId	Transaction ID on Gameball system.
type	Transaction type string. Can be one of the following AchievementReward PaymentReward Refund Redemption Expiry Cancel Migration ManualAccumulation DiscountCode ManualDeduction ManualReward
direction	string "+" or "-" indicating transaction was an addition or deduction
playerUniqueId	Player unique identifier used to uniquely identify the player on Gameball.
points	Number of points involved in the transaction
amount	Monetary amount involved in the transaction
transactionTime	Time of transaction in UTC
merchantName	Merchant name for transaction
branchName	Branch Name for transaction