Skip to main content
POST
/
api
/
v4.0
/
integrations
/
transactions
/
hold
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/transactions/hold \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "cust_abc12345xyz67890",
  "transactionTime": "2024-10-11T16:15:15.071Z",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "otp": "654321",
  "ignoreOTP": false,
  "amountToHold": null,
  "pointsToHold": 50,
  "ruleId": null,
  "hash": "123456"
}
'
{
  "customerId": "cust_abc12345xyz67890",
  "holdAmount": "5",
  "holdEquivalentPoints": 50,
  "holdReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
}
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.
Security: Provide both apikey and secretkey headers.

Authorizations

​
apikey
string
header
required

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.

Example:

"cust_abc12345xyz67890"

​
transactionTime
string<date-time>
required

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

Example:

"2024-10-11T16:15:15.071Z"

​
email
string

Customer's email address. This is required if your account uses email-based channel merging.

Example:

"john.doe@example.com"

​
mobile
string

Customer's mobile number. This is required if your account uses mobile-based channel merging.

Example:

"+1234567890"

​
otp
string

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.

Example:

"654321"

​
ignoreOTP
boolean

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

Example:

false

​
amountToHold
number

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.

Example:

null

​
pointsToHold
integer

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.

Example:

50

​
ruleId
string

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.

Example:

null

​
hash
string

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.

Example:

"123456"

Response

200 - application/json

Points placed on hold successfully

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

Example:

"cust_abc12345xyz67890"

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

Example:

"5"

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

Example:

50

​
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. This hold reference can also be used in Order API to redeem the held points.

Example:

"a2a199ad-86f3-45c4-8253-7aaee50e4798"