Skip to main content
POST
/
api
/
v4.0
/
integrations
/
transactions
/
redeem
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/transactions/redeem \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "cust_12345abc",
  "transactionId": "txn98765",
  "transactionTime": "2024-10-11T10:57:43.382Z",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "amount": 10,
  "points": 0,
  "holdReference": null,
  "merchant": {
    "uniqueId": "<string>",
    "name": "<string>",
    "branch": {
      "uniqueId": "<string>",
      "name": "<string>"
    }
  },
  "hash": "HASH1234",
  "otp": "123456",
  "ignoreOTP": false
}
'
{
  "customerId": "cust_12345abc",
  "gameballTransactionId": "11034734",
  "transactionId": "txn98765",
  "redeemAmount": 10,
  "redeemEquivalentPoints": 100
}
Redeem loyalty points as a payment method for customer transactions.

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_12345abc"

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

Example:

"txn98765"

​
transactionTime
string<date-time>
required

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

Example:

"2024-10-11T10:57:43.382Z"

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

​
amount
number

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.

Example:

10

​
points
integer

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.

Example:

0

​
holdReference
string

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.

Example:

null

​
merchant
object

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.

​
hash
string

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.

Example:

"HASH1234"

​
otp
string

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.

Example:

"123456"

​
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

Response

200 - application/json

Points redeemed 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_12345abc"

​
gameballTransactionId
string

Unique identifier for the transaction in the Gameball system.

Example:

"11034734"

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

Example:

"txn98765"

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

Example:

10

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

Example:

100