Sign in

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

Changes

Changed in 5 of the 38 revisions of this API.3221

  • 78bbaf3a9ea52See the full diff
    • ○

      added the new optional request property reason

      new-optional-request-property

    • ○

      added the optional property reason to the response with the 200 status

      response-optional-property-added

  • 262228c134293See the full diff
    • ○

      the endpoint scheme security apiKey AND secretKey was added to the API

      api-security-added

    • ○

      the endpoint scheme security apiKey was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security secretKey was removed from the API

      api-security-removed

  • 7887186517672215See the full diff
    • ▲

      added the new required request property transactionTime

      new-required-request-property

    • ▲

      the points request property type/format changed from number/ to integer/

      request-property-type-changed

    • ●

      removed the optional property remainingPoints from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property success from the response with the 200 status

      response-optional-property-removed

    • ○

      added the new optional request property amount

      new-optional-request-property

    • ○

      added the new optional request property email

      new-optional-request-property

    • ○

      added the new optional request property hash

      new-optional-request-property

    • ○

      added the new optional request property holdReference

      new-optional-request-property

    • ○

      added the new optional request property ignoreOTP

      new-optional-request-property

    • ○

      added the new optional request property merchant

      new-optional-request-property

    • ○

      added the new optional request property mobile

      new-optional-request-property

    • ○

      added the new optional request property otp

      new-optional-request-property

    • ○

      the request property points became optional

      request-property-became-optional

    • ○

      removed the non-success response with the status 400

      response-non-success-status-removed

    • ○

      added the optional property customerId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property gameballTransactionId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property redeemAmount to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property redeemEquivalentPoints to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property transactionId to the response with the 200 status

      response-optional-property-added

  • 95e7f65e5afd1See the full diff
    • ○

      endpoint added

      endpoint-added

  • 919eb7a392aa1See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog