v4.0

Hold Management

Control points with hold actions, letting you place, view, or release held points before redemption. Useful for reserving points until a transaction is confirmed.

Available APIs

POST - Hold Points

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

The API call holds loyalty points for a specified time until a redeem request is made; otherwise, the points are released. The default hold duration is 10 minutes, but you can adjust it from the dashboard, with a maximum hold time of 15 days and a minimum of 1 minute.

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.

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

otp string Optional A one-time password (OTP) sent to the customer for authentication purposes. This is used only if your account has OTP configuration enabled.

For more details on how the OTP is generated and validated, refer to the OTP Generation and Validation section.

amountToHold float Optional The monetary value (in the system's currency) that will be held from the customer’s points balance. This allows you to reserve a specific monetary amount using the customer's points.

Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

pointsToHold integer Optional The number of points to be held from the customer’s points balance. This allows you to reserve a certain number of points for later use.

Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

ruleId string Optional The ID of a redemption rule configured within Gameball’s system. Clients can create custom redemption rules through the Gameball dashboard to specify different redemption options. For example, a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts.

You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API.

Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.

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

Sample Request

{
  "customerId": "cust_abc12345xyz67890",              
  "transactionTime": "2024-10-11T16:15:15.071Z", 
  "otp": "654321",                          
  "amountToHold": null,                     
  "pointsToHold": 50,                       
  "ruleId": null,                          
  "hash": "7a8b9c10-11d3-4f8e-a423-768ee4e9f789"
}

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.

holdAmount number

The monetary value that has been held from the customer’s points balance. This value represents the amount reserved based on the customer’s available points.

holdEquivalentPoints number

The number of points that have been held from the customer’s points balance. These points are reserved for future use or specific transactions.

holdReference string

A unique identifier for the hold transaction. This reference is used to track and manage the held points for future actions, such as redeeming the held points or canceling the hold.

Sample Response

{
    "customerId": "cust_abc12345xyz67890",
    "holdAmount": null,
    "holdEquivalentPoints": 20,
    "holdReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
}

GET - Hold Details

https://api.gameball.co/api/v4/integrations/transactions/hold/{holdReferenceId}

The API call retrieves the details of a hold using the specified holdReference, returning the amount of loyalty points held, their monetary value, the state of the hold (active, used, or expired), and the time remaining until expiration. This information aids in managing and tracking held loyalty points effectively.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

holdReferenceId string Required Unique identifier for the hold transaction, used to retrieve the details of the specific hold.

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.

holdAmount number The monetary value held from the customer’s points balance in this specific hold transaction. This is the amount that has been reserved and is associated with the holdReference provided.

Example: If a customer has reserved $50 worth of points, the holdAmount in the response would be 50, representing the monetary value currently held under the specified hold reference.

holdEquivalentPoints number The number of points held from the customer’s points balance for this specific hold transaction. This represents the exact quantity of points currently locked under the holdReference provided. Example: If the system has held 200 points from the customer’s balance, the holdEquivalentPoints in the response would be 200, indicating the points associated with the provided hold reference that are currently unavailable for redemption until further action is taken (e.g., redemption or expiration).

state string The current status of the hold:

  • Active : The hold is currently in effect and the points or amount are locked.

  • Expired : The hold has expired and the points or amount have been released.

  • Used : The hold has been used, meaning the points or amount have been redeemed.

dateToExpire datetime The date and time when the hold will expire. After this time, the hold reference will no longer be valid for usage.

Sample Response

{
    "customerId": "cust_abc12345xyz67890",
    "holdAmount": "2",
    "holdEquivalentPoints": 20,
    "state": "active",
    "dateToExpire": "2024-10-16T08:11:24.675401"
}

DELETE - Release Hold

https://api.gameball.co/api/v4/integrations/transactions/hold/{holdReferenceId}

The API call removes a specific hold using the provided holdReference. This allows for the cancellation of held loyalty points, ensuring they are released back into the customer's account.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

holdReferenceId string Required Unique identifier for the hold transaction, used to release the held points or amount.

PreviousCashback & RedemptionsNextTransaction Management

Last updated