Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-017439390.7 KB

This API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points in place of monetary value during transactions. By providing details such as customerId and amount, this endpoint facilitates point-based redemptions within the purchase process.

post/api/v4.0/integrations/transactions/redeem

Request body

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

emailstring

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

mobilestring

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

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

transactionTimestring date-time required

The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).

amountnumber

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.

pointsinteger

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.

holdReferencestring

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.

hashstring

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.

otpstring

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.

ignoreOTPboolean

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.

reasonstring

An optional reason for the redemption. This can be used to provide context about why the customer is redeeming points (e.g., 'Discount on order', 'Loyalty reward'). The reason will be stored with the transaction and displayed in the dashboard transaction details.

Example request

{
  "customerId": "cust_12345abc",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "transactionId": "txn98765",
  "transactionTime": "2024-10-11T10:57:43.382Z",
  "amount": 10,
  "hash": "HASH1234",
  "otp": "123456",
  "reason": "Discount on order #12345"
}

Response

Points redeemed successfully

customerIdstring

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.

gameballTransactionIdstring

Unique identifier for the transaction in the Gameball system.

transactionIdstring

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.

redeemAmountnumber

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.

redeemEquivalentPointsnumber

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.

reasonstring

The reason provided for the redemption, if one was included in the request.

Example response

{
  "customerId": "cust_12345abc",
  "gameballTransactionId": "11034734",
  "transactionId": "txn98765",
  "redeemAmount": 10,
  "redeemEquivalentPoints": 100,
  "reason": "Discount on order #12345"
}