Transactions
Transactions API is responsible for all the customer's points transactions.
The Transactions API endpoints are used to reward a customer, redeem points, refund points, and view the transaction history of a specific customer.
Available Endpoints
Type
Description
Endpoint
POST
/integrations/transaction/cashback
POST
/integrations/transaction/redeem
POST
/integrations/transaction/refund
POST
/integrations/transaction/hold
GET
/integrations/transaction/hold/{holdReference}
DELETE
/integrations/transaction/hold/{holdReference}
POST
/integrations/transaction/manual
GET
/integrations/transaction/list
GET
/integrations/order/{orderId}/transactions
POST
/integrations/transactions/coupon
POST - Cashback
This API is used to reward your customers for each unit of currency they actually pay for your product or service. The Cashback API is mainly responsible for rewarding your customers' scores and points through a Cashback program based on the actual amount paid by your customers.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your customer 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
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 customer at Gameball.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer'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
(Note: Amount must be positive)
merchant
object
No
Merchant object as described in Object reference section.
In case the customer doesn't exist on Gameball before sending the Cashback API call, the customer will be created automatically on Gameball and granted the points.
Sample Request Body
Response
Attribute
Type
Description
playerUniqueId
string
Customer unique identifier used to uniquely identify the customer on Gameball.
gameballTransactionId
integer
Transaction ID on Gameball system.
rewardedPoints
integer
The number of points rewarded to the customer for the specified amount.
Sample Response
Usage Example
The example shown is a request sent to Gameball when you want to reward a customer 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.
POST - Redeem Points
The API enables the customer 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 customer 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.
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 customer at Gameball.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer'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.
merchant
object
No
otp
string
No
ignoreOTP
boolean
No
The ignoreOTP
attribute allows you to skip OTP verification when set to true
. If not provided or set to false
, OTP verification will be required for accounts configured to use OTP.
Sample Request Body
Response
Attribute
Type
Description
playerUniqueId
string
Customer unique identifier used to uniquely identify the customer on Gameball.
gameballTransactionId
integer
Redeem Transaction ID on Gameball system.
redeemedPoints
integer
The total points redeemed equivalent to the redeemed monetary value.
Sample Response
Usage Example
The example shown is a request sent to Gameball to redeem an amount
equivalent to the amount held in the holdReference
for the customer with playerUniqueId
"player456".
Redemption can be sent along with events and reward using Actions API endpoint.
POST - Refund
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 customer'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.
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 customer at Gameball.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer'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
otp
string
No
lineItems
Object
lineItems
ObjectAttribute
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.
Sample Request Body
Sample Request Body (With LineItems)
Response
Attribute
Type
Description
orderTransactions
array
Sample Response
Usage Example
The example shown is a request sent to Gameball after canceling a transactionId
“234567891” on your system.
POST - Hold Points
The API is used to hold a specific amount of points from the customer'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 (default configurations) and automatically expires afterward. Once the hold expires, the points are returned back to the customer 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 customer 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 bodyamount
or holdPoints.
otp should be sent along with the request body in case (only if) your account has the OTP configuration enabled.
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 customer at Gameball.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer'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 customer points balance on Gameball.
holdPoints
number
No
Points to be held from the customer points balance on Gameball.
otp
string
No
ignoreOTP
boolean
No
The ignoreOTP
attribute allows you to skip OTP verification when set to true
. If not provided or set to false
, OTP verification will be required for accounts configured to use OTP.
hash
string
No
Sample Request Body
Response
Attribute
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball
amount
number
Monetary value in the system currency to be held from the customer points balance on Gameball.
holdPoints
number
Points that were held from the customer points balance on Gameball.
holdReference
string
Hold reference ID to be used in points redemption.
Sample Response
Usage Example
The example shown is a request sent to Gameball to hold customer points with playerUniqueId
"player456" equivalent to amount
of "98.89".
GET - Hold Details
The API call is used to retrieves hold details for a specified hold reference.
Request
Header
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
holdReference
string
Yes
Hold reference number to be cancelled as received from Gameball.
Response
holdPoints
number
Points that has been held from the customer points balance on Gameball.
amount
number
Monetary value in the system currency that has been held from the customer points balance on Gameball.
expirationDate
Date Time
The date time that the hold will be expired on.
state
string
Hold status. Possible values are:
Active
Used
Expired
Sample Response
Usage Example
Delete - Reverse Hold
The API call is used to cancel previously held points. It can be called to cancel non-expired hold requests within the hold 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“.
POST - Manual Transaction
Access manual points reward API to reward your customers 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
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 customer at Gameball
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer'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 customer.
reason
string
Yes
Represents the reason you wish to specify as to why the customer is being rewarded.
points
integer
No
Number of points to be rewarded to or deducted from the customer. a "+" value is accumulation while a "-" value is deduction.
amount
number
No
(Note: Amount must be positive).
Either the amount or the points should be sent along with the request.
In case the customer doesn't exist on Gameball before sending the Manual Transaction API call, the customer will be created automatically on Gameball and granted the points.
Sample Request Body
Response
Attribute
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball
gameballTransactionId
integer
Transaction ID on Gameball system.
amount
number
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 customer for the specified amount
Sample Response
Usage Example
GET - List Transactions
This API is used to get transactions from Gameball. The result is 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. (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
=> Active2
=> Pending3
=> Blocked4
=> Expired
playerUniqueId
string
No
Used to get a specific customer's transactions list.
Response
Attribute
Type
Description
transactions
object
count
integer
currently displayed transactions list count,
total
integer
total number of transactions available matching the applied filters
Example:
"count": 50
"total": 200
transaction
object
transaction
objectAttribute
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 customer achieves VIP tier/reward campaign/referral.
PaymentReward
: Transaction captured by Gameball to reward a customer for every placed order.
Refund
: Transaction captured by Gameball that refunds customer points that has been redeemedin a refunded order.
Redemption
: Transaction captured by Gameball whenever a customer redeems his points.
Expiry
: Transaction captured by Gameball whenever a customer's points expire, to signal that some of the customer points have expired.
Cancel
: Transaction Captured by Gameball whenever a customer cancels a specific order, deducts the rewarded points from the customer.
Migration
: Transaction captured by Gameball after adding/deducting points during updating/migrating customers using a csv file.
ManualAccumulation
: Transaction captured by Gameball for any manually added points to a customer's balance.
DiscountCode
: Transaction captured by Gameball whenever a customer creates a coupon code.
ManualDeduction
: Transaction captured by Gameball for any manually removed points from a customer's balance.
ManualReward
: Same asAchievementReward
but when the achievement is rewarded manually.
direction
string
Either "+" or "-" indicating transaction was an addition or deduction.
playerUniqueId
string
Customer unique identifier used to uniquely identify the customer 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 reward campaign that was achieved in case of transaction type AchievementReward.
reason
string
The reason of the transaction in case of transaction type ManualAccumilation
or ManualDeduction.
Sample Response
Usage Example
merchant
object
merchant
objectAttribute
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
Get - List Order Transactions
This endpoint is used to list all the transactions (such as refunds) relating to an order.
Request
Header
APIKey
string
Yes
Client API Key
secretkey
string
Yes
Client Secret Key
Response
Body
orderTransactions
array
total
integer
Total number of transactions available matching the applied filters
Example:
"count": 50
"total": 20
count
integer
Returned currently displayed transactions list count.
orderTransaction Object
transactionDate
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"
gameballTransactionId
integer
Transaction ID on Gameball system.
transactionType
string
Transaction type string. Can be one of the following:
AchievementReward
Payment
Refund
Redemption
Expiry
Cancel
Migration
ManualAccumulation
DiscountCode
ManualDeduction
ManualReward
amount
number
Monetary amount involved in the transaction.
equivalentPoints
number
Equivalent points to the amount.
transactionId
string
Transaction ID that was sent from the client's system.
Response Example
POST - Create Coupon
This endpoint is used to create coupons for a specific customer.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Description
value
double
The monetary value to be redeemed. Only used with the general redemption rule.
playerUniqueId
string
Unique identifier for the customer at Gameball.
ruleId
integer
Sample Request
Response
Attribute
Type
Description
code
string
Code of the coupon that was created.
url
string
URL associated with the Coupon group, it could be null. (if you are not using predefined coupons)
startDate
DateTime
Date at which you can start using coupon.
expiryDate
DateTime
Date at which coupon expires and can no longer be used.
Sample Response
Last updated