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.

post
Player Points Balance

/integrations/transaction/balance
The API call is used to retrieve player's current points balance available for redemption and the corresponding equivalent amount.
Request
Response
Request
Headers
APIKey
required
string
Client API key
Body Parameters
playerUniqueId
required
string
Player unique identifier used to uniquely identify the player on Gameball.
hash
required
string
Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hashing is automatically handled when using server-side SDKs.
Response
200: OK
Success.
{
"pointsBalance": 11500,
"pointsValue": 115,
"currency": "EGP",
"pointsName": "Points"
}
400: Bad Request
JSON Body Invalid or missing required parameters. The response will include error description payload described in Errors section.
{
"code": 11,
"message": "BodyHashed Invalid"
}
401: Unauthorized
Invalid APIKey.
{}
402: Payment Required
Request failed. The response will include error description payload described in Errors section.
{
"code": 101,
"message": "No Player with this External ID"
}
403: Forbidden
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
Node.js
Ruby
.NET
PHP
Python
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")

post
Hold Points

/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.
Request
Response
Request
Headers
APIKey
required
string
Client API key
Body Parameters
transactionTime
required
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
required
string
Player unique identifier used to uniquely identify the player on Gameball.
amount
required
string
Monetary value in the system currency to be held from the player points balance on Gameball.
hash
required
string
Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hash is automatically handled when using server-side SDKs.
Response
200: OK
Success.
{
"playerUniqueId": "player456",
"amount": "98.89",
"holdReference": "ca84504a-edc3-4ff8-9aa1-e9cf186cf95c",
"otp": null,
"transactionTime":"2019-09-21T16:53:28.190Z"
}
400: Bad Request
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: Unauthorized
Invalid APIKey.
{}
402: Payment Required
Request failed. The response will include error description payload described in Errors section.
{
"code": 304,
"message": "This not valid transaction"
}
403: Forbidden
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
Node.js
Ruby
.NET
PHP
Python
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)

post
Redeem Points

/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.
Request
Response
Request
Headers
APIKey
required
string
Client API key
Body Parameters
holdReference
required
string
Hold reference ID received after calling Hold Points API.
playerUniqueId
required
string
Player unique identifier used to uniquely identify the player on Gameball.
transactionId
required
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
required
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
required
string
Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hash is automatically handled when using server-side SDKs.
Response
200: OK
Success.
{
"playerUniqueId": "player456",
"playerAttributes": null,
"gameballTransactionId": 17179,
"transactionId": "tra_123456789",
"holdReference": "ca84504a-edc3-4ff8-9aa1-e9cf186cf95c",
"transactionTime": "2019-09-19T16:14:09.895Z"
}
400: Bad Request
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: Unauthorized
Invalid APIKey.
{}
402: Payment Required
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: Forbidden
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
Node.js
Ruby
.NET
PHP
Python
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.

post
Reverse Transaction

/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.
Request
Response
Request
Headers
APIKey
required
string
Client API key
Body Parameters
playerUniqueId
required
string
Player unique identifier used to uniquely identify the player on Gameball
transactionId
required
string
Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number.
reversedTransactionId
required
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
required
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
required
string
Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hashing is automatically handled when using server-side SDKs.
Response
200: OK
Success.
{
"playerUniqueId": "player456",
"gameballTransactionId": 17178,
"transactionId": "1234567890",
"reversedTransactionId": "2345678901",
"transactionTime": "2019-09-19T16:14:09.895Z"
}
400: Bad Request
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: Unauthorized
Invalid APIKey.
{}
402: Payment Required
Request failed. The response will include error description payload described in Errors section.
{
"code": 301,
"message": "Transaction Type Non Reversable"
}
403: Forbidden
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
Node.js
Ruby
.NET
PHP
Python
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')

post
Reverse Hold

/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.
Request
Response
Request
Headers
API Key
required
string
Client API key
Body Parameters
playerUniqueId
required
string
Player unique identifer used to uniquely identify the player on Gameball.
holdReference
required
string
Hold reference number to be cancelled as received from Gameball.
transactionTime
required
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
required
string
Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hash is automatically handled when using server-side SDKs.
Response
200: OK
Success.
{
"playerUniqueId":" player456",
"amount": null,
"holdReference":"9245fe4a-d402-451c-b9ed-9c1a04247482",
"transactionTime":"2019-09-21T16:53:28.190Z"
}
400: Bad Request
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: Unauthorized
Invalid APIKey.
{}
402: Payment Required
Request failed. The response will include error description payload described in Errors section.
{
"code": 304,
"message": "This not valid transaction"
}
403: Forbidden
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
Node.js
Ruby
.NET
PHP
Python
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")