Transactions
Transactions API is responsible for all the player's points transactions.
Transactions API Endpoints are used to reward a player, as well as redeem points, refund points and also view transactions history of a specific player.

Available Endpoints

Type
Description
Endpoint
POST
​Cashback​
/integrations/transaction/cashback
POST
​Redeem Points​
/integrations/transaction/redeem
POST
​Refund​
/integrations/transaction/refund
POST
​Hold Points​
/integrations/transaction/hold
DELETE
​Reverse Hold​
/integrations/transaction/hold/{holdReference}
POST
​Manual Transaction​
/integrations/transaction/manual
GET
​List Transaction​
/integrations/transaction/list

POST - Cashback

1
https://api.gameball.co/api/v3.0/integrations/transaction/cashback
Copied!
This API is used to reward your players for each unit currency they actually paid for your product or service. The Cashback API is mainly responsible for rewarding your player score and points through Cashback program based on the actual paid amount by your players.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.
Reward can be sent along with Events and Redemption using Actions Composite API endpoint.

Request

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
amount
number
Yes
Monetary value that the player will be rewarded for based on the Cashback program configurations.
(Note: Amount must be positive).
merchant
object
No
Merchant object as described in Object reference section
In case the player doesn't exist on Gameball before sending the Cashback API call, the player will be created automatically on Gameball and granted the points.

Sample Request Body

1
{
2
"playerUniqueId":"player123",
3
"amount":99.98,
4
"transactionId":"tra_123456789",
5
"transactionTime":"2019-09-19T16:14:09.895Z"
6
}
Copied!

Response

Attribute
Type
Description
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
gameballTransactionId
integer
Transaction ID on Gameball system.
rewardedPoints
integer
The number of points rewarded to the player for the specified amount.

Sample Response

1
{
2
"playerUniqueId": "player123",
3
"gameballTransactionId": 17178,
4
"rewardedPoints": 20
5
}
Copied!

Usage Example

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 Cashback program.
cURL
1
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
3
"playerUniqueId":"player123",
4
"amount":99.98,
5
"transactionId":"tra_123456789",
6
"transactionTime":"2019-09-19T16:14:09.895Z"
7
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/cashback'
Copied!

POST - Redeem Points

1
https://api.gameball.co/api/v3.0/integrations/transaction/redeem
Copied!
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.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball.
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
redeemedAmount
number
No
Monetary value in your system currency to be redeemed.
Note: - Amount must be positive.
- This field is required in case the holdReference is not provided.
holdReference
number
No
Hold reference ID received after calling Hold Points API.
Note: This field is required in case the redeemedPoints is not provided.

Sample Request Body

1
{
2
"playerUniqueId":"player456",
3
"transactionId":"tra_123456789",
4
"transactionTime":"2019-09-19T16:14:09.895Z",
5
"redeemedAmount": null,
6
"holdReference":"2342452352435234"
7
}
Copied!

Response

Attribute
Type
Description
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
gameballTransactionId
integer
Redeem Transaction ID on Gameball system.
redeemedPoints
integer
The total points redeemed equivalent to the redeemed monetary value.

Sample Response

1
{
2
"playerUniqueId": "player456",
3
"gameballTransactionId": 17179,
4
"redeemedPoints": 200,
5
}
Copied!

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
1
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
3
"playerUniqueId":"player456",
4
"transactionId":"tra_123456789",
5
"transactionTime":"2019-09-19T16:14:09.895Z",
6
"redeemedPoints": null,
7
"holdReference":"2342452352435234"
8
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/redeem'
Copied!
Redemption can be sent along with events and reward using Actions API endpoint.

POST - Refund

1
https://api.gameball.co/api/v3.0/integrations/transaction/refund
Copied!
The API is used to cancel a Cashback transaction or refund a points redemption transaction on Gameball. Using transactionId, Gameball will check if there is a cashback 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

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
reverseTransactionId
string
Yes
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.
amount
number
No
The amount to be refunded from the transaction. The whole order is cancelled if not provided.
Example: In case the total order value is 100 USD and you just need to return an item from this order with value 15 USD.

Sample Request Body

1
{
2
"playerUniqueId":"player456",
3
"transactionId":"1234567890",
4
"reverseTransactionId":"234567891",
5
"transactionTime":"2019-09-19T11:14:09.895Z",
6
"amount": null
7
}
Copied!

Response

Attribute
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball
gameballTransactionId
integer
Transaction ID on Gameball system.

Sample Response

1
{
2
"playerUniqueId": "player456",
3
"gameballTransactionId": 17178
4
}
Copied!

Usage Example

The example shown is a request sent to Gameball after canceling a transactionId β€œ234567891” on your system.
cURL
1
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
3
"playerUniqueId":"player456",
4
"transactionId":"1234567890",
5
"reverseTransactionId":"234567891",
6
"transactionTime":"2019-09-19T11:14:09.895Z",
7
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/refund'
Copied!

POST - Hold Points

1
https://api.gameball.co/api/v3.0/integrations/transaction/hold
Copied!
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 holdReference 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.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.
In case this API is used, to successfully redeem the points, it should be followed by a Redemption API Call with the same resulted holdReference provided from this endpoint.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
transactionTime
string
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
amount
number
Yes
Monetary value in the system currency to be held from the player points balance on Gameball.

Sample Request Body

1
{
2
"playerUniqueId":"player456",
3
"amount":98.89,
4
"transactionTime":"2019-09-21T16:53:28.190Z",
5
}
Copied!

Response

Attribute
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball
amount
number
Monetary value in the system currency to be held from the player points balance on Gameball.
holdReference
string
Hold reference ID to be used in points redemption.

Sample Response

1
{
2
"playerUniqueId":"player456",
3
"amount":98.89,
4
"holdReference":"ref_12343ds"
5
}
Copied!

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
1
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
3
"playerUniqueId":"player456",
4
"amount":98.89,
5
"transactionTime":"2019-09-21T16:53:28.190Z",
6
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/hold'
Copied!

Delete - Reverse Hold

1
https://api.gameball.co/api/v3.0/integrations/transaction/hold/{holdReference}
Copied!
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

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Path Parameters

Attribute
Type
Required
Description
holdReference
string
Yes
Hold reference number to be cancelled as received from Gameball.

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
1
curl -x DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703'
3
-v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/hold/9245fe4a-d402-451c-b9ed-9c1a04247482'
Copied!

POST - Manual Transaction

1
https://api.gameball.co/api/v3.0/integrations/transaction/manual
Copied!
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.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Body

Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
username
string
Yes
Represents the username of the user in your system that is performing the manual reward for the player.
reason
string
Yes
Represents the reason you wish to specify as to why the player is being rewarded.
points
integer
No
Number of points to be rewarded to or deducted from the player. a "+" value is accumulation while a "-" value is deduction.
amount
number
No
Monetary value that the player will be rewarded for (or deducted) based on the Cashback program configurations.
(Note: Amount must be positive).
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.

Sample Request Body

1
{
2
"playerUniqueId":"player123",
3
"amount":99.98,
4
"transactionId":"tra_123456789",
5
"transactionTime":"2019-09-19T16:14:09.895Z",
6
"username": "admin_storename",
7
"reason": "Thank You Gift"
8
}
Copied!

Response

Attribute
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball
gameballTransactionId
integer
Transaction ID on Gameball system.
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.
Example: "2019-09-19T16:14:09.895Z"
points
integer
The number of points rewarded to the player for the specified amount

Sample Response

1
{
2
"playerUniqueId": "player123",
3
"gameballTransactionId": 17178,
4
"amount": "99.98",
5
"transactionId": "tra_123456789",
6
"transactionTime": "2019-09-19T16:14:09.895Z"
7
}
Copied!

Usage Example

cURL
1
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
3
"playerUniqueId":"player123",
4
"amount":99.98,
5
"transactionId":"tra_123456789",
6
"transactionTime":"2019-09-19T16:14:09.895Z",
7
"username": "admin_storename",
8
"reason": "Thank You Gift"
9
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/manual'
Copied!

GET - List Transactions

1
https://api.gameball.co/api/v3.0/integrations/transaction/list
Copied!
This API is used to get transactions from Gameball. The result are paged and can be filtered.

Request

Header

Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key

Query Parameters

Attribute
Type
Required
Description
page
integer
No
Result page number. Starts from 1
limit
integer
No
Result page size. Default is 50 transactions and max is 200
direction
string
No
"+" or "-" to return deduction or addition transactions
from
date
No
from date
to
date
No
to date
transactionId
string
No
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.
status
enum
No
Transaction status. Possible values are:
    1 => Active
    2 => Pending
    3 => Blocked
    4 => Expired

Response

Attribute
Type
Description
transactions
object
array of paged transaction objects ordered by transactionTime desc.
count
integer
returned currently displayed transactions list count
total
integer
total number of transactions available matching the applied filters
Example:
"count": 50
"total": 200

transaction object

Attribute
Type
Description
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.
gameballTrasnactionId
integer
Transaction ID on Gameball system.
type
string
Transaction type string. Can be one of the following:
AchievementReward
PaymentReward
Refund
Redemption
Expiry
Cancel
Migration
ManualAccumulation
DiscountCode
ManualDeduction
ManualReward
direction
string
Either "+" or "-" indicating transaction was an addition or deduction
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
points
integer
Number of points involved in the transaction
amount
number
Monetary amount involved in the transaction
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.
Example: "2019-09-19T16:14:09.895Z"
status
enum
Transaction status. Possible values are:
    Active
    Pending
    Blocked
    Expired
merchantName
string
Merchant name for transaction
branchName
string
Branch Name for transaction

Sample Response

1
{
2
"transactions":[
3
{
4
"transactionId":"trx123",
5
"gameballTransactionId":"gbtrx123",
6
"transactionTime":"2019-09-21T16:53:28.190Z",
7
"type":"Cash Back",
8
"direction":"+",
9
"playerUniqueId":"1234",
10
"points":500,
11
"amount":10,
12
"status":"Active",
13
"merchantName":"merchant",
14
"branchName":"branch"
15
}
16
],
17
"count":50,
18
"total":344
19
}
Copied!

Usage Example

cURL
1
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -v -i
3
'https://api.gameball.co/api/v3.0/integrations/transactions/list'
Copied!

merchant object

Attribute
Type
Description
uniqueId
string
Merchant unique id or code
name
string
Merchant name
branch
object
Optional branch information
branch.uniqueId
string
Branch unique id or code
branch.name
string
Branch name
Last modified 20d ago