Qixol Promo Help > Gift Cards


Purchase and Redemption





Purchasing Gift Card Numbers


When a gift card number is purchased it must be Allocated or Activated before it can be used.   Whether the card number will be Allocated or Activated is dependant on the configuration of the Card Group to which the card number belongs.  An Activated card number is immediately available for redemption, whereas an Allocated card number must be Activated using the generated activation token.


When purchasing a gift card number, the Qixol Promo API provides the ability to retrieve the next Pending card number from a Card Group (using Api 80350).  Alternatively, an existing card number can be provided.


For integrated systems using the Qixol Promo basket validation APIs, gift card numbers included in the basket will be automatically Allocated or Activated when the basket is confirmed.  Alternatively, the Qixol Promo API provides the ability to Allocate or Activate a gift card number (using API 80500).



Testing Purchases in the Promo Portal


The Promo Portal provides the ability to purchase card numbers for testing and development.  To purchase a gift card, navigate to the Basket Builder, and from the Add Gift Card(s) select the required action:




Select Gift Card(s)

A browser will be presented allowing the user to select one or more gift card numbers to be added to the basket.


Enter Gift Card

A new line will be added to the basket, ready for a card number to be entered.


Next Pending Gift Card

A new line will be added to the basket with a card number assigned, where the card number is the next available with a status of Pending.




When the basket is validated, the lines in the basket which are for a gift card will be validated.  The quantity for gift lines will be ignored, and the price provided for the gift card number will become the card number balance.  If the basket has the Confirm Basket? option ticked, the gift cards that are valid to be Allocated or Activated will be actioned. 


To confirm the basket in the basket builder, the Confirm Code Use from Basket Builder setting must have a value of True.  After modifying the setting value, ensure the basket is cleared by selecting Clear All.  The Confirm Basket? option is then available on the Options tab.


The validation response will include details on the action taken for each gift card number.  To view the details, hover over (or select) the gift card status.  The validation response includes the following details:






The result of the gift card validation.  One of the following values:

Invalid  -  A problem was encountered, view the messages for more details.

Activated  -  The card number was activated.

Allocated  -  The card number was allocated.

ToActivateOnConfirm  -  The card number will be activated when the basket is confirmed.

ToAllocateOnConfirm  -  The card number will be allocated when the basket is confirmed.


Activation Token

Where the card number was allocated, the activation token to be provided to the gift card recipient, to be used when Activating the card number.


Expiry Date

The expiry date of the card number.


New Balance

For confirmation, the new balance of the card number.



Where the response Status is Allocated, the card number must be Activated before it can be redeemed.  The Activation Token should be communicated to the gift card recipient along with the card number.  The card number can be activated using the Promo API services (API 80500), or in the Promo Portal by selecting Activate from the Cards List.



Get more details on Activating a Card Number in the Promo Portal.



Redeeming Gift Card Number Balances


A card number balance can be redeemed where the status is Active.  The amount to be redeemed cannot exceed the balance of the card number.  The Qixol Promo API provides the ability to redeem an amount against a card number (using API 80800).



Testing Redemptions in the Promo Portal


The Promo Portal provides the ability to redeem against the balance of a card number, for testing and development.  Redemption of a balance is available within the Promo Portal from the basket validation response page. 


To begin, create a basket, adding basket lines as required, then select Validate Basket.  The basket validation response will then be presented.  To redeem a balance against the transaction, select Redeem Gift Card.  The following fields are available:






Card Number


The card number against which to redeem an amount.



The amount to redeem.

The amount entered cannot exceed the balance of the gift card number.

The amount entered must be greater than zero.


Redemption Reporting Code


The reporting code to be captured against the redemption transaction.

The reporting code will be mandatory based upon the Require reporting code for redemptions setting.


Transaction Reference


The reference to be captured against the transaction.




Comments to be captured against the transaction.




After redeeming an amount against a card number balance, the card number transactions will be displayed.



For further information on the API interactions to support Purchasing and Redemption, see API interactions and Settings.






Copyright © 2021 Qixol Ltd.