Transactions

Transactions API is responsible for all the player's wallet 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 external ID used by integrator to uniquely identify the player in Gameball
bodyHashed	string	eHashed body with SHA1 algorithm. As described in Hashing Transaction Messages section

200

{
  "response": {
    "pointsBalance": "1000",
    "pointsValue": "20",    
    "currency": "EGP"
},
  "success": true,
  "errorMsg": "",
  "errorCode": 0
}

Example

Send Gameball the following to get a player's balance with his playerUniqueId

{
  "playerUniqueId": "your_player_unique_id",
  "bodyHashed": "b9a6def42dbf3437e2919ab9f853c7ccde92f4f2"
}

Hold Points

POST /integrations/transaction/hold

The API call is used to hold a specific amount of points from the player’s points balance. This is used to guarantee availability of redemption points 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. A hold will be active in Gameball for 10 minutes and expires if Gameball did not receive a follow Redeem transaction

Headers

Name	Type	Description
APIKey	string	client API key

Request Body

Name	Type	Description
playerUniqueId	string	Player external ID used by integrator to uniquely identify the player in Gameball
amount	string	Monetary value that equivalent number of points to be set to hold in Gameball.
transactionTime	string	UTC transaction datetime
bodyHashed	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section
otp	string	One time password as received by user in case of redemption transaction (required if OTP is enabled)

200

{
“response”: 
{
“holdReference”: “string”,
},
“Success”: true,
“ErrorMsg”: “”,
“ErrorCode”: 0
}

401

{“error”:”Invalid API key.”}

403

{“error”:”API key is missing.”}

404

{“error”:”Invalid\Expired OTP “}

500

{“error”:”Something went wrong. Please try again later.”}

Examples

Hold player points with playerUniqueId equivalent to amount of "98.89" in case OTP is disabled

{
   "playerUniqueId":"your_player_unique_id",
   "amount":98.89,
   "transactionTime":"2019-09-21T16:53:28.190Z",
   "bodyHashed":"7090689dc127ddfbe4a7c2260060afe5e6fc3264"
}

Hold player points with external id playerUniqueId equivalent to amount of "99.99" in case OTP is enable

{
   "playerUniqueId":"your_player_unique_id",
   "amount":99.99,
   "otp":"67890",
   "transactionTime":"2019-09-21T16:53:28.190Z",
   "bodyHashed":"260060afe5e6fc32647090689dc127ddfbe4a7c2"
}

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 from received after calling Hold Points API
playerUniqueId	string	Player external ID used by integrator to uniquely identify the player in Gameball
amount	number	Monetary value that equivalent number of points to be set to hold in Gameball.
transactionOnClientSystemId	string	Correlation Id provided by integrator system used to map transaction on Gameball to a transaction at integrator system
transactionTime	string	UTC transaction datetime
bodyHashed	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section

200

{
“response”: {
“transactionOnGameballSystemId”: “string”,
},
“Success”: true,
“ErrorMsg”: “”,
“ErrorCode”: 0
}

401

{“error”:”Invalid API key.”}

403

{“error”:”API key is missing.”}

404

{“error”:”Invalid\Expired OTP “}

500

{“error”:”Something went wrong. Please try again later.”}

Examples

Sends Gameball to redeem an amount equivalent to "10" for player playerUniqueId.

{
   "playerUniqueId":"your_player_unique_id",
   "amount":10,
   "transactionOnClientSystemId":"234567890",
   "holdReference": "2342452352435234",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "bodyHashed":"ccde92f4ff3437e2919ab9f853c72b9a6def42db"
}

Sends Gameball to redeem an amount equivalent to "99.25" for player with external id playerUniqueId.

{
   "playerUniqueId":"your_player_unique_id",
   "amount":99.25,
   "transactionOnClientSystemId":"234567891",
   "holdReference": "2342452352435234",
   "transactionTime":"2019-09-19T18:14:09.895Z",
   "bodyHashed":"37e2919ab9ccde92f4ff34f853c72b9a6def42db"
}

Reverse Transaction

POST /integrations/transaction/cancel

The API is used to cancel a purchase reward transaction or refund a points redemption transaction in Gameball. After successful submission the cancelled 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
playerUniqueId	string	Player external ID used by integrator to uniquely identify the player in Gameball
transactionOnClientSystemId	string	Correlation Id provided by integrator system used to map transaction on Gameball to a transaction at integrator system
reversedTransactionOnClientSystemId	string	Integrator system transaction ID of the transaction to be cancelled\refunded
transactionTime	string	UTC transaction datetime
bodyHashed	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section

200

{
“response”: {
“transactionOnGameballSystemId”: “string”,
},
“Success”: true,
“ErrorMsg”: “”,
“ErrorCode”: 0
}

401

{“error”:”Invalid API key.”}

403

{“error”:”API key is missing.”}

404

{“error”:”Invalid\Expired OTP “}

500

{“error”:”Something went wrong. Please try again later.”}

Examples

Sends Gameball to cancelled a transactionwith id equals “234567891”

{
   "playerUniqueId":"your_player_unique_id",
   "transactionOnClientSystemId":"1234567890",
   "reversedTransactionOnClientSystemId":"234567891",
   "transactionTime":"2019-09-19T11:14:09.895Z",
   "bodyHashed":"19ab9f853c7ccde9f3437e292f4f2b9a6def42db"
}

Reverse Hold

POST /integrations/transaction/hold

The API call is used to cancel previously held points . It can be called against non-expired previous hold requests within the 5 minutes life cycle or against any unused held unredeemed points.

Headers

Name	Type	Description
API Key	string	client API key

Request Body

Name	Type	Description
playerUniqueId	string	Player external ID used by integrator to uniquely identify the player in Gameball
holdReference	string	Hold reference number to be cancelled as received from Gameball
transactionTime	string	UTC transaction datetime
bodyHashed	string	Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section

200

Success

401

{“error”:”Invalid API key.”}

403

{“error”:”API key is missing.”}

404

{“error”:”Invalid\Expired OTP “}

500

{“error”:”Something went wrong. Please try again later.”}

Example

Remove hold player points with external id playerUniqueId with holdReference equals “9245fe4a-d402-451c-b9ed-9c1a04247482“

{
   "playerUniqueId":"your_player_unique_id",
   "holdReference":"9245fe4a-d402-451c-b9ed-9c1a04247482",
   "transactionTime":"2019-09-21T16:53:28.190Z",
   "bodyHashed":"7090689dc127d260060afe5e6fc3264dfbe4a7c2"
}

Hashing Transaction Messages

All transactions endpoints requires a digital signature BodyHashed to be sent with the body payload. This digital signature is used to verify and guarantee the authenticity of the request.

BodyHashed is SH1 hashing of body payload parameters and secure TransactionKey encoded with base64 encoding. When Gameball receives a transactions request, it computes the BodyHashed value and compares it against the one sent with the request. If the two hashes match then the request processed otherwise its blocked.

BodyHashed is computed according to the below algorithm. Variables found in this algorithm must be equal to their equivalent values in the request payload.

BodyHashed = Base64.encode(
    sha1.ComputeHash(PlayerUniqueId+":"+yyMMddHHmmss+":"+
    Amount+":"+transactionkey))

Variable	Value
playerUniqueId	PlayerUniqueIdas sent in the request payload
yyMMddHHmmss	This is extracted from request payload parameter transaction time without any separator. Time must be 24 format. For example: 200430163519
Amount	Amountas sent in the request payload
transactionKey	Client salt key, provided by Gameball

For request that have no Amount or transaction time parameters. They are substituted in the algorithm by empty string. Below is an example showing the hashing of a request with no Amount.

BodyHashed = Base64.encode(
    sha1.ComputeHash(PlayerUniqueId+":"+yyMMddHHmmss+":"+
    ""+":"+transactionkey))

Note: In case Amount value is 0, it is sent with a value of 0, not as an empty string.