Transaction Management
Manage customer transactions by listing all transaction details or manually adding points. Track all customer activities, including rewards and deductions.
Available APIs
GET - Transactions
https://api.gameball.co/api/v4/integrations/transactions
This API retrieves a paged list of transactions from Gameball, allowing for optional filtering. Each transaction record includes details such as type, direction, points, amount, transaction time, and balance changes, providing a comprehensive view of customer activity.
Security: Requires apikey and secretkey headers.
Request
Query Parameters
direction string
Optional
Direction of the transaction:
+
Accumulation (points or rewards added to the customer).-
Deduction (points or rewards removed from the customer).
status string
Optional
Represents the current status of the transaction. Possible values are:
Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.
startAfter long
Optional
Specifies the page will start after which transaction id. Defaults to 0.
limit integer
Optional
Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page.
customerId string
Optional
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. This is used to filter the transactions of the specified customer.
Response
application/json
transactions array
List of transactions.
count number
The total number of transactions on the current page.
hasMore boolean
Indicating whether there are additional transactions to be fetched beyond the current page.
Sample Response
{
"transactions": [
{
"transactionId": "txn123456",
"gameballTransactionId": "11034736",
"type": "Cancel",
"direction": "-",
"customerId": "cust_12345abc",
"points": 10,
"amount": 10.0,
"transactionTime": "2024-10-13T17:11:00.249",
"status": "Active",
"couponCode": null,
"isCouponUsed": false,
"couponType": null,
"merchantName": "MERCH1234",
"branchName": "BRANCH123",
"reason": "trx reason",
"achievementName": null,
"expiryDate": "2025-10-13T17:11:00.249",
"pointsBalanceBefore": 1164,
"pointsBalanceAfter": 1154,
"achievementType": null,
"achievedRewardCampaignId": null,
"achievedTierId": null
},
{
"transactionId": "txn987657111",
"gameballTransactionId": "11034735",
"type": "Refund",
"direction": "+",
"customerId": "cust_12345abc",
"points": 100,
"amount": 10.0,
"transactionTime": "2024-10-13T17:11:00.249",
"status": "Active",
"couponCode": null,
"isCouponUsed": false,
"couponType": null,
"merchantName": "MERCH1234",
"branchName": "BRANCH123",
"reason": "trx reason",
"achievementName": null,
"expiryDate": "2025-10-13T17:11:00.249",
"pointsBalanceBefore": 1064,
"pointsBalanceAfter": 1164,
"achievementType": null,
"achievedRewardCampaignId": null,
"achievedTierId": null
}
],
"count": 2,
"hasMore": true
}
GET - Transactions including Customer Data
https://api.gameball.co/api/v4/integrations/transactions/customer-view
This API retrieves a paged list of transactions from Gameball, with support for optional filtering. It provides the same comprehensive transaction data as the previous version — including type, direction, points, amount, transaction time, and balance changes — but with an important enhancement: Each transaction now includes associated customer details, such as:
Customer Name
Customer Email
Customer Deletion Status
This allows for better traceability and visibility into who performed each transaction, even if the customer has since been deleted.
Security: Requires apikey and secretkey headers.
Request
Query Parameters
direction string
Optional
Direction of the transaction:
+
Accumulation (points or rewards added to the customer).-
Deduction (points or rewards removed from the customer).
status string
Optional
Represents the current status of the transaction. Possible values are:
Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.
startAfter long
Optional
Specifies the page will start after which transaction id. Defaults to 0.
limit integer
Optional
Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page.
customerId string
Optional
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. This is used to filter the transactions of the specified customer.
Response
application/json
transactions array
List of transactions.
count number
The total number of transactions on the current page.
hasMore boolean
Indicating whether there are additional transactions to be fetched beyond the current page.
Sample Response
Sample Request
{
"customerId": "cust_12345abc",
"type": "All",
"page": 1,
"size": 10
}
Sample Response
{
"transactions": [
{
"transactionId": "txn123456",
"gameballTransactionId": "11034736",
"type": "Cancel",
"direction": "-",
"customerId": "cust_12345abc",
"customerName": "John Doe",
"customerEmail": "[email protected]",
"isCustomerDeleted": false,
"points": 10,
"amount": 10.0,
"transactionTime": "2024-10-13T17:11:00.249",
"status": "Active",
"couponCode": null,
"isCouponUsed": false,
"couponType": null,
"merchantName": "MERCH1234",
"branchName": "BRANCH123",
"reason": "trx reason",
"achievementName": null,
"expiryDate": "2025-10-13T17:11:00.249",
"pointsBalanceBefore": 1164,
"pointsBalanceAfter": 1154,
"achievementType": null,
"achievedRewardCampaignId": null,
"achievedTierId": null
},
{
"transactionId": "txn987657111",
"gameballTransactionId": "11034735",
"type": "Refund",
"direction": "+",
"customerId": "cust_12345abc",
"customerName": "Jane Smith",
"customerEmail": "[email protected]",
"isCustomerDeleted": true,
"points": 100,
"amount": 10.0,
"transactionTime": "2024-10-13T17:11:00.249",
"status": "Active",
"couponCode": null,
"isCouponUsed": false,
"couponType": null,
"merchantName": "MERCH1234",
"branchName": "BRANCH123",
"reason": "trx reason",
"achievementName": null,
"expiryDate": "2025-10-13T17:11:00.249",
"pointsBalanceBefore": 1064,
"pointsBalanceAfter": 1164,
"achievementType": null,
"achievedRewardCampaignId": null,
"achievedTierId": null
}
],
"count": 2,
"hasMore": true
}
GET - Transactions Count
https://api.gameball.co/api/v4/integrations/transactions/count
This API retrieves the total count of transactions from Gameball, allowing for optional filtering. It provides the number of transactions matching the specified criteria without returning detailed transaction records.
Security: Requires apikey and secretkey headers.
Request
Query Parameters
direction string
Optional
Direction of the transaction:
+
Accumulation (points or rewards added to the customer).-
Deduction (points or rewards removed from the customer).
status string
Optional
Represents the current status of the transaction. Possible values are:
Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.
customerId string
Optional
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. This is used to filter the transactions of the specified customer.
Response
application/json
count number
The total number of transactions available in Gameball system.
Sample Response
{
"count": 240
}
POST - Manual Transaction
https://api.gameball.co/api/v4/integrations/transactions/manual
This API allows for the manual addition or deduction of points for a customer in Gameball. It provides flexibility in managing loyalty points, enabling adjustments based on specific needs or circumstances.
Security: Requires apikey and secretkey headers.
Request
Body
application/json
customerId string
Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
email string
Optional
Customer's email address.
Note: This is required if your account uses email-based channel merging.
mobile string
Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
transactionId string
Required
A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.
transactionTime string
Required
The time of the transaction in your system (e.g., order datetime, invoice datetime).
username string
Required
The username of the admin performing the manual transaction.
reason string
Required
Reason for manually rewarding or deducting points (e.g., "Referral bonus").
points integer
Required
The number of points to be rewarded or deducted (should be positive for rewards and negative for deductions).
amount float
Optional
The monetary value (in system currency) associated with the transaction.
Sample Request
{
"customerId": "cust_abc12345xyz67890",
"transactionId": "txn543211",
"transactionTime": "2024-10-11T15:54:10.944Z",
"username": "admin_user",
"reason": "Referral bonus",
"points": 50,
"amount": 0
}
Response
application/json
customerId string
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
gameballTransactionId number
The unique identifier for the transaction within Gameball.
transactionId string
A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.
points number
The number of points rewarded or deducted in the transaction.
amount number
The monetary value processed in the transaction.
Sample Response
{
"customerId": "cust_abc12345xyz67890",
"gameballTransactionId": 11035201,
"transactionId": "txn54321221",
"points": 50,
"amount": 5.0
}
POST - Activate Transaction
https://api.gameball.co/api/v4/integrations/transactions/{transactionId}/activate
This API is used to immediately activate loyalty points that are currently in a pending state, bypassing the configured return window duration. This endpoint overrides that duration and activates the points immediately, making them available for use by the customer without waiting for the pending return window duration to elapse.
This API is especially useful for scenarios where the client determines that the order is confirmed and the points can be safely activated ahead of schedule.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
transactionId string
Required
The transaction id on your system which you want to activate.
Response
application/json
pointsActivated number
Number of points that has been successfully activated by the transaction
gameballTransactionId number
The unique identifier for the transaction within Gameball.
clientTransactionId string
A unique identifier for a transaction in your system (e.g., order number or invoice number).
Sample Response
{
"pointsActivated": 50,
"gameballTransactionId": 11035201,
"clientTransactionId": "txn54321221",
}
Last updated