Guides

Redeem Tokens

Suggest Edits

The Kigo API allows users to redeem tokens to access the associated value, such as discounts, gift cards, or other promotional offers. Redemption is a critical action within the Kigo ecosystem, enabling users to utilize their digital assets.

Prerequisites

Before performing the redeem action on a token, ensure that the necessary user-level session token has been obtained. This token is required to authenticate API requests and can be acquired by following the User Client Level Authentication.

Steps to Implement

  1. Redeeming a Token

    • Purpose: The redeem action allows users to convert their digital tokens into a tangible benefit, such as a discount or product. This action is essential for tokens designed to be used as part of promotional offers or stored value.
    • Usage: The application should present the redeem option when a token is eligible for redemption, as indicated by the flags.is_redeemable property in the Get Token By ID response.

  2. Determining If a Token Can Be Redeemed

    • flags.is_redeemable Property: The ability to redeem a token is determined by the flags.is_redeemable property in the Get Token By ID response. If this property is set to true, the token is eligible to be redeemed. If it is false, the token cannot be redeemed, and the redeem option should not be presented to the user.

  3. Handling Redemption Types and Configuration

    • When redeeming a token, a configuration object is provided that contains additional information on how the redemption should be displayed to the user. This object varies depending on the type of redemption being performed:

      Promo Code Redemption

      • Purpose: Promo codes can be applied online or in-store.
      • Configuration Object:
        • promo_code: The actual promo code that the user must enter during checkout.
        • call_to_action_label: A short prompt like "Redeem Now" or "Apply Code" that instructs the user on what to do next.
        • description: Additional details or instructions related to the promo code.

      Show and Save Redemption

      • Purpose: The user presents a barcode or QR code in-store to redeem the token.
      • Configuration Object:
        • description: Text explaining the offer or providing instructions on how to redeem it.
        • call_to_action_label: A concise action prompt like "Show This" or "Redeem Now."
        • redemption_code: The code that will be shown to the cashier.
        • redemption_url: URL that may be included to display the barcode or QR code.

      QR Connect and Save Redemption

      • Purpose: The user scans a QR code at a specific location to redeem the token.
      • Configuration Object:
        • description: Instructions on how to use the QR code.
        • call_to_action_label: A brief prompt such as "Scan Now" to direct the user's action.
        • form: A form object that may include fields that the user needs to fill out as part of the redemption process.

      Online Link Redemption

      • Purpose: The user redeems the token by clicking a link, which usually redirects to a merchant’s website.
      • Configuration Object:
        • content: Detailed information about the offer.
        • call_to_action_label: A short prompt like "Redeem Now" or "Click Here" to guide the user.
        • redemption_url: The URL that the user will visit to complete the redemption.

      Voucher Redemption

      • Purpose: Vouchers are redeemed by showing or entering a code, either digitally or in a printed form.
      • Configuration Object:
        • description: Instructions or details about the voucher.
        • disclaimer: Any important notes or legal disclaimers.
        • voucher_redemption_options: An array of redemption options, detailing how the voucher can be used.

API Call

To redeem a token, use the API endpoint associated with the specific type of redemption. Refer to the relevant API documentation for specific details on the API request and response structure for each redemption type:

Key Considerations

  1. Redemption Timing: Ensure that the redeem option is only available when the token is ready to be redeemed, as indicated by the flags.is_redeemable property.
  2. Redemption Security: Tokens are often valuable digital assets. Ensure that redemption actions are secure and that sensitive information, such as promo codes or QR codes, is handled appropriately.
  3. User Feedback: After redemption, provide the user with confirmation and details about the redeemed token, such as what was redeemed and any remaining balance if applicable.

Example Workflow

  1. User decides to redeem a token: The user selects a token from their wallet that they want to redeem.
  2. The application checks the token’s flags.is_redeemable property: The application checks this property in the Get Token By ID response to determine if the token can be redeemed.
  3. The token is redeemed: The application makes the appropriate redemption API call based on the token type (e.g., Redeem a Promo Code Token). The redemption details are returned and displayed to the user.
  4. User completes the redemption: The user follows the provided instructions (e.g., entering a promo code at checkout or showing a QR code in-store) to complete the redemption process.

Updated 8 months ago