Cashback & Redemptions

Handle customer points by rewarding cashback, redeeming points, or issuing refunds. These APIs allow you to manage point balances based on purchases or other transactions.

Available APIs

• Reward Cashback

• Redeem

• Refund

---

POST - Reward Cashback

https://api.gameball.co/api/v4/integrations/transactions/cashback

This API is mainly responsible for rewarding loyalty points to your customers through a cashback program based on the actual amount they paid.

Security: Requires apikey and secretkey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

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.

---

transactionId string Required A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID is critical for managing transaction lifecycle events such as reversals, cancellations, or refunds in Gameball.

---

transactionTime dateTime Required The time of the transaction in your system (e.g., order datetime, invoice datetime).

---

amount number Required Monetary value of the transaction for which the customer will be rewarded, based on the Cashback program configuration.

---

merchant object Optional This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.

merchant object

uniqueId string Optional Unique identifier for the merchant.

---

name string Optional Name of the merchant.

---

branch.uniqueId string Required Unique identifier for the branch where the transaction took place.

---

branch.name string Optional Name of the branch where the transaction took place.

---

Sample Request

{
  "customerId": "cust_12345abc",
  "transactionId": "TXN987654321",
  "transactionTime": "2024-10-11T10:48:56.719Z",
  "amount": 150.75,
  "merchant": {
    "uniqueId": "MERCHANT001",
    "name": "TechGadgetStore",
    "branch": {
      "uniqueId": "BRANCH101",
      "name": "Downtown Branch"
    }
  }
}

---

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 Unique identifier for the transaction in the Gameball system.

---

rewardAmount number The monetary value equivalent of the points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase and each point is worth $0.10, the rewardAmount will be $5.

---

rewardEquivalentPoints number The number of points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase, the rewardEquivalentPoints will be 50.

---

Sample Response

{
    "customerId": "cust_12345abc",
    "gameballTransactionId": 11034733,
    "rewardAmount": 150.75,
    "rewardEquivalentPoints": 0
}

---

POST - Redeem

https://api.gameball.co/api/v4/integrations/transactions/redeem

The API call enables customers to redeem loyalty points as a payment method, allowing them to substitute points for monetary values during transactions.

Security: Requires apikey and secretkey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

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.

---

mobile string Optional Customer's mobile number .

---

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).

---

amount float Optional The actual monetary value the customer wants to redeem. This will be deducted from their points balance based on the redemption factor. For instance, if the customer wants to redeem $10 and the redemption factor is 0.1, then 100 points will be deducted from their balance to cover this amount.

Note: Only one of amount, points, or holdReference must be provided for the redemption.

---

points integer Optional The number of points the customer wants to redeem from their balance. This allows the customer to specify exactly how many points they wish to use.

Note: Only one of amount, points, or holdReference must be provided for the redemption.

---

holdReference string Optional A unique reference obtained from the Hold Points API. If provided, the points in the hold will be used. It is used when points have been reserved previously , allowing the system to redeem the points that are on hold.

Example: If you previously used the Hold Points API to hold 100 points, you would provide the holdReference obtained from that hold transaction to redeem the 100 points that were held

Note: Only one of amount, points, or holdReference must be provided for the redemption.

---

merchant object Optional This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.

merchant object

uniqueId string Optional Unique identifier for the merchant.

---

name string Optional Name of the merchant.

---

branch.uniqueId string Required Unique identifier for the branch where the transaction took place.

---

branch.name string Optional Name of the branch where the transaction took place.

---

hash string Optional A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. For more details on how the hash is generated and validated, refer to the Customer's Hash section.

---

otp string Optional One-time password (OTP) required if OTP is enabled for the customer. This OTP serves as an additional layer of security for verifying the redemption request. For more details on how OTP works and when it is required, refer to the Transaction Validation section.

---

Sample Request

{
  "customerId": "cust_12345abc",
  "transactionId": "txn98765",
  "transactionTime": "2024-10-11T10:57:43.382Z",
  "amount": 10,
  "points": 0,
  "holdReference": null,
  "merchant": {
    "uniqueId": "merch123",
    "name": "Merchant Store",
    "branch": {
      "uniqueId": "branch456",
      "name": "Main Branch"
    }
  },
  "hash": "HASH1234",
  "otp": "123456"
}

---

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 string Unique identifier for the transaction in the Gameball system.

---

transactionId string A unique identifier for the 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.:

---

redeemAmount number The amount of money redeemed in the transaction, based on the points redeemed.

Example: If a customer redeems points equivalent to $10 off their purchase, the redeemAmount will be 10.0.

---

redeemEquivalentPoints number The number of points used to redeem the specified monetary value in the transaction.

Example: If a customer uses 100 points to redeem $10, the redeemEquivalentPoints will be 100.

---

Sample Response

{
    "customerId": "cust_12345abc",
    "gameballTransactionId": "11034734",
    "transactionId": "txn98765",
    "redeemAmount": 10,
    "redeemEquivalentPoints": 100
}

---

POST - Refund

https://api.gameball.co/api/v4/integrations/transactions/refund

The API call 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.

Security: Requires apikey and secretkey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

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.

---

mobile string Optional Customer's mobile number.

---

refundTransactionId string Required A unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself.

Example: If a refund is processed for an item, the refundTransactionId could be REFUND-98765, which refers to the specific new refund transaction.

---

reverseTransactionId string Required The unique transaction ID representing the original order being refunded, reversed, or canceled. This ID is sent as reverseTransactionId in the payload and links to the previous transaction.

Example: If a customer requests a refund for an order previously made with transaction ID ORDER-12345, the reverseTransactionId will be ORDER-12345 to indicate which order is being refunded.

---

transactionTime string Required The timestamp of the original transaction in your system (e.g., order datetime, invoice datetime).

---

refundAmount float Optional The amount to be refunded from the original transaction. The entire transaction is refunded if this field is not provided.

---

merchant object Optional This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.

merchant object

uniqueId string Optional Unique identifier for the merchant.

---

name string Optional Name of the merchant.

---

branch.uniqueId string Required Unique identifier for the branch where the transaction took place.

---

branch.name string Optional Name of the branch where the transaction took place.

---

lineItems array Optional An array of items from the original transaction that are being refunded. If provided, only the items listed in this array will be refunded from the reverseTransactionId. If this field is not provided, the entire transaction specified by the reverseTransactionId will be refunded.

lineItems object

productId string Optional Unique identifier for the product or service being purchased.

---

quantity float Optional Number of units purchased for this product or service.

---

price float Optional TThe original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.

Example: If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.

---

sku string Optional Stock Keeping Unit (SKU) for the product.

---

tags array Optional Tags associated with the product for categorization or promotional purposes.

---

category array Optional Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]

---

weight float Optional Weight of the product.

---

vendor string Optional Vendor or manufacturer of the product.

---

collection array Optional Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

---

title string Optional Product title or name.

---

taxes float Optional The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.

---

discount float Optional The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.

---

extra object Optional Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number.

---

Sample Request

{
  "customerId": "cust_12345abc",
  "refundTransactionId": "txn987657111",
  "reverseTransactionId": "txn6342347194477",
  "transactionTime": "2024-10-13T17:11:00.249Z",
  "refundAmount": 15.00,
  "merchant": null,
  "lineItems": []
}

---

Response

application/json

gameballTransactionId string Unique identifier for the refund transaction in the Gameball system.

---

refundTransactionId string Unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If the refund process for an order has a transaction ID REFUND-54321, this ID will be used to track the refund operation.

---

refundAmount number The amount refunded from the original transaction. Example: If a customer was originally charged $100 and you refunded $40, the refundAmount will be 40.

---

refundEquivalentPoints number The number of points equivalent to the monetary value refunded in the transaction. Example: If $40 is refunded and your points-to-currency ratio is 1 point = $0.10, then the refundEquivalentPoints would be 400 points.

---

Sample Response

{
    "gameballTransactionId": "11034735",
    "refundTransactionId": "txn987657111",
    "refundAmount": 15.00,
    "refundEquivalentPoints": 150
}

---