This API is used to reward your players for each unit of currency they actually pay for your product or service. The Cashback API is mainly responsible for rewarding your players' scores and points through a Cashback program based on the actual amount paid 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.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Request
Header
Body
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.
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.
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.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
otp should be sent along with the request body in case (only if) your account has the OTP configuration enabled.
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".
The API is used to cancel a Cashback transaction or refund a points redemption transaction on Gameball. By providing the transactionId, Gameball checks for a corresponding cashback or redemption transaction and processes the request accordingly. After the request is successfully processed, the player's points balance is updated to reflect the canceled or refunded transaction.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
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. The hold is active at Gameball for 10 minutes and automatically expires afterward. 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.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Only one of the following attributes must be sent in the request bodyamountor holdPoints.
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
Path Parameters
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“.
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.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Request
Header
Body
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
{"playerUniqueId":"player123","amount":99.98,"transactionId":"tra_123456789","transactionTime":"2019-09-19T16:14:09.895Z","username": "admin_storename","reason": "Thank You Gift"}
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
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.
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.
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball.
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
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.
Player one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a player use OTP endpoint.
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.
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball.
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
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 cashback 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.
lineItems
array
No
A list of line itemobjects, each containing information about an item in the order.
otp
string
No
Player one time password (OTP). (Sent in case your account has OTP configuration enabled), and is sent to the player using the OTP endpoint.
Attribute
Type
Required
Description
productId
string
No
The ID of the product that the line item belongs to
quantity
number
No
Number of items purchased of this line item that needs to be returned. Must be positive.
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
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
No
Monetary value in the system currency to be held from the player points balance on Gameball.
holdPoints
number
No
Points to be held from the player points balance on Gameball.
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.
holdPoints
number
Points that were held from the player points balance on Gameball.
holdReference
string
Hold reference ID to be used in points redemption.
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Attribute
Type
Required
Description
holdReference
string
Yes
Hold reference number to be cancelled as received from Gameball.
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
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).
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
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Attribute
Type
Required
Description
page
integer
No
Result page number. Starts from 1.
limit
integer
No
Result page size. (The default result page size is 50 transactions, and the maximum limit is 200)
direction
string
No
'+' to return addition transactions and '-' to return deduction 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
playerUniqueId
string
No
Used to get a specific player's transactions list.
Attribute
Type
Description
transactions
object
array of paged transactionobjects ordered by transactionTime desc.
count
integer
currently displayed transactions list count,
total
integer
total number of transactions available matching the applied filters
Example:
"count": 50
"total": 200
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
Can be one of the following:
AchievementReward: Transaction captured by Gameball when a player achieves level/challenge/referral.
PaymentReward: Transaction captured by Gameball to reward a player for every placed order.
Refund: Transaction captured by Gameball that refunds player points that has been redeemedin a refunded order.
Redemption: Transaction captured by Gameball whenever a player redeems his points.
Expiry: Transaction captured by Gameball whenever a player's points expire, to signal that some of the player points have expired.
Cancel: Transaction Captured by Gameball whenever a player cancels a specific order, deducts the rewarded points from the player.
Migration: Transaction captured by Gameball after adding/deducting points during updating/migrating players using a csv file.
ManualAccumulation: Transaction captured by Gameball for any manually added points to a player's balance.
DiscountCode : Transaction captured by Gameball whenever a player creates a coupon code.
ManualDeduction : Transaction captured by Gameball for any manually removed points from a player's balance.
ManualReward : Same as AchievementReward but when the achievement is rewarded manually.
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
couponCode
string
Code of the coupon (In case of DiscountCode coupon type).
isCouponUsed
boolean
A Boolean flag indicating if the coupon was used or not.
couponType
string
Indicates the type of the coupon, the value of the string can be one of the following:
free_shipping
percentage_discount
fixed_discount
free_product
fixed_rate_discount
custom
merchantName
string
Merchant name for transaction.
branchName
string
Branch Name for transaction.
expiryDate
string
Time of points expiry in UTC
Example: "2019-09-19T16:14:09.895Z"
pointsBalanceBefore
integer
The total points balance before the transaction.
pointsBalanceAfter
integer
The total points balance after the transaction.
achievementName
string
The name of the challenge that was achieved in case of transaction type AchievementReward.
reason
string
The reason of the transaction in case of transaction type ManualAccumilation or ManualDeduction.