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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| 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. |
| string | Yes | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| number | Yes | Monetary value that the customer will be rewarded for based on the Cashback program configurations. (Note: Amount must be positive) |
| 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 |
| string | Customer unique identifier used to uniquely identify the customer on Gameball. |
| integer | Transaction ID on Gameball system. |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| 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. |
| string | Yes | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| number | No | Monetary value in your system currency to be redeemed. Note: - Amount must be positive. - This field is required in case the |
| number | No | Hold reference ID received after calling Hold Points API. Note: This field is required in case the |
| object | No | Merchant object describes the merchant itself. |
| string | No | Customer one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a customer use OTP endpoint. |
Sample Request Body
Response
Attribute | Type | Description |
| string | Customer unique identifier used to uniquely identify the customer on Gameball. |
| integer | Redeem Transaction ID on Gameball system. |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| 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. |
| string | Yes | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| 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. |
| 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. |
| array | No | A list of line item objects, each containing information about an item in the order. |
| string | No | Customer one time password (OTP). (Sent in case your account has OTP configuration enabled), and is sent to the customer using the OTP endpoint. |
lineItems
Object
lineItems
ObjectAttribute | Type | Required | Description |
| string | No | The ID of the product that the line item belongs to |
| 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 |
| array | An array of |
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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| string | Yes | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| number | No | Monetary value in the system currency to be held from the customer points balance on Gameball. |
| number | No | Points to be held from the customer points balance on Gameball. |
| string | No | Customer one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a customer use OTP endpoint. |
| string | No |
Sample Request Body
Response
Attribute | Type | Description |
| string | Unique identifier for the customer at Gameball |
| number | Monetary value in the system currency to be held from the customer points balance on Gameball. |
| number | Points that were held from the customer points balance on Gameball. |
| 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
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Path Parameters
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Hold reference number to be cancelled as received from Gameball. |
Response
Attribute | Type | Description |
---|---|---|
| number | Points that has been held from the customer points balance on Gameball. |
| number | Monetary value in the system currency that has been held from the customer points balance on Gameball. |
| Date Time | The date time that the hold will be expired on. |
| string | Hold status. Possible values are:
|
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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Path Parameters
Attribute | Type | Required | Description |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| 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. |
| string | Yes | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| string | Yes | Represents the username of the user in your system that is performing the manual reward for the customer. |
| string | Yes | Represents the reason you wish to specify as to why the customer is being rewarded. |
| integer | No | Number of points to be rewarded to or deducted from the customer. a "+" value is accumulation while a "-" value is deduction. |
| number | No | Monetary value that the customer 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 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 |
| string | Unique identifier for the customer at Gameball |
| integer | Transaction ID on Gameball system. |
| number | Monetary value that the customer will be rewarded for based on the Redemption Rate. (Amount must be positive) |
| 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. |
| string | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Query Parameters
Attribute | Type | Required | Description |
| integer | No | Result page number. Starts from 1. |
| integer | No | Result page size. (The default result page size is 50 transactions, and the maximum limit is 200) |
| string | No | '+' to return addition transactions and '-' to return deduction transactions. |
| date | No | From date. |
| date | No | To date. |
| 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. |
| enum | No | Transaction status. Possible values are:
|
| string | No | Used to get a specific customer's transactions list. |
Response
Attribute | Type | Description |
transactions | object | array of paged transaction objects ordered by |
count | integer | currently displayed transactions list count, |
total | integer | total number of transactions available matching the applied filters Example:
|
transaction
object
transaction
objectAttribute | Type | Description |
| 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. |
| integer | Transaction ID on Gameball system. |
| string | Can be one of the following:
|
| string | Either "+" or "-" indicating transaction was an addition or deduction. |
| string | Customer unique identifier used to uniquely identify the customer on Gameball. |
| integer | Number of points involved in the transaction. |
| number | Monetary amount involved in the transaction. |
| string | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| enum | Transaction status. Possible values are:
|
| string | Code of the coupon (In case of |
| boolean | A Boolean flag indicating if the coupon was used or not. |
| string | Indicates the type of the coupon, the value of the string can be one of the following:
|
| string | Merchant name for transaction. |
| string | Branch Name for transaction. |
| string | Time of points expiry in UTC Example: |
| integer | The total points balance before the transaction. |
| integer | The total points balance after the transaction. |
| string | The name of the reward campaign that was achieved in case of transaction type |
| string | The reason of the transaction in case of transaction type |
Sample Response
Usage Example
merchant
object
merchant
objectAttribute | Type | Description |
| string | Merchant unique id or code |
| string | Merchant name |
| object | Optional branch information |
| string | Branch unique id or code |
| 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
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API Key |
| string | Yes | Client Secret Key |
Response
Body
Attribute | Type | Description |
---|---|---|
| array | An array of |
| integer | Total number of transactions available matching the applied filters Example:
|
| integer | Returned currently displayed transactions list count. |
orderTransaction Object
Attribute | Type | Description |
---|---|---|
| string | Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: Example: |
| integer | Transaction ID on Gameball system. |
| string | Transaction type string. Can be one of the following:
|
| number | Monetary amount involved in the transaction. |
| number | Equivalent points to the |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Body
Attribute | Type | Description |
| double | The monetary value to be redeemed. Only used with the general redemption rule. |
| string | Unique identifier for the customer at Gameball. |
| integer | The Id of the redemption rule that is being redeemed. You can get the Ids of all your redemption rules through the GET - Redemption Rules API. |
Sample Request
Response
Attribute | Type | Description |
| string | Code of the coupon that was created. |
| string | URL associated with the Coupon group, it could be null. (if you are not using predefined coupons) |
| DateTime | Date at which you can start using coupon. |
| DateTime | Date at which coupon expires and can no longer be used. |
Sample Response