|
|
A Card Number is a unique gift card identifier. It can contain alphanumeric, numeric and special characters. For generated card numbers, the number will either be a Guid, Short Guid, Masked random value or masked number series value. The card number type to be used when generating is defined against the Card Group.
Statuses
Each card number has a status. The card number status indicates which actions are permitted:
|
Status
|
Description
|
Permitted Actions
|
|
Pending
|
The card number is available for purchase/allocate/activate.
|
Purchase
Allocate/Activate
Delete
|
|
Allocated
|
The card number has been purchased by a customer and is waiting to be Activated by the gift recipient.
|
Activate
Withdraw
|
|
Active
|
The card number is available for redemption.
|
Redeem against balance
Adjust balance (add/subtract)
Withdraw
|
|
Withdrawn
|
The card number has been withdrawn.
|
-
|
|
Redeemed
|
The card number balance has been fully redeemed.
|
Adjust balance (add)
|
|
Expired
|
The card number has expired.
|
-
|
Creating Card Numbers
Card numbers may be generated as part of a batch, where the card numbers are generated using the configuration of the Card Group. Alternatively, card numbers can be imported to facilitate batch creation for existing card numbers, or for performing bulk operations against card numbers.
Card numbers may also be individually created manually, where the number is entered by the user. Card numbers can be added via the API services, or by using the Card Numbers Import, or in the Qixol Promo Portal by selecting Add New from the Cards List, where the following fields are available:
|
Field
|
Editable?
|
Description
|
|
Group
|
|
The group within which to create the card number. The selected group will indicate the available options for Status and Card Expiry Date.
|
|
Card Number
|
|
The card number to be added.
|
|
Status
|
*
|
The status of the new card number. Available dependant upon the Card Group configuration option Use Activation Tokens?
Where cards are created with a status of Allocated, they must be Activated before they can be redeemed against.
Where cards are created with a status of Active, they are immediately available to be redeemed against.
|
|
Balance
|
|
The new balance of the card number. A value greater than zero must be specified. The value must be less than the Maximum Card Balance defined against the selected Group.
|
|
Currency Code
|
|
The currency code for the balance. The currency code for a card number cannot be changed after it is Allocated/Activated with a balance.
|
|
Card Expiry Date
|
*
|
The expiration date of the new card number. The card expiry date will be calculated based on the selected Group, and will be editable where the selected group has the option Permit expiry override? enabled.
|
|
Customer Reference
|
|
Where available the customer reference for the card number.
|
|
Transaction Reporting Code
|
|
When the new card number is Allocated or Activated, a transaction will be captured for the new balance. Where required, a reporting code can be provided for the transaction.
|
|
Transaction Reference
|
|
Where available the transaction reference for the card number.
|
|
Comments
|
|
Comments relating to the card number creation.
|
Generating Card Numbers
Card numbers can be generated by selecting Generate Card Numbers from the Cards List. The group within which to generate the card numbers must be selected, and then the number of card numbers to generate. Generated cards will be created with a status of Pending, ready to be Activated or Allocated.
A maximum of 100,000 card numbers can be generated at a time. The generate request will be queued and processed in the background. It can take a few minutes to generate card numbers, especially for high volumes. When generating a large number of card number, it is recommended to perform this action outside of business hours where possible. To check on the progress of a queued generate request, view the Import Log from Configuration.
Importing Card Numbers
The import of card numbers allows the bulk creation and bulk update of card numbers. To begin select Import from the Cards List. On the page displayed, browse to the file to be imported. The file can contain either XML, JSON or CSV (comma separated values) content. The name of the file is used to establish the content type, where a file with an extension of .XML is assumed to contain XML import data, and similarly .JSON for JSON content and .CSV or .TXT for CSV content.
When importing CSV content there are additional options available for field separator and a text qualifier.
|
Field
|
Description
|
|
First Row Contains Field Names?
|
Flag indicating that the first row in the CSV will contain the field names - the value is always true.
The cardnumber, group code, status and balance fields are required.
|
|
Field Separator
|
The separator used in the file between files. The default is a comma.
|
|
Text Qualifier
|
Where required, specify a qualifier which will be used to wrap text. Typically this would be double quotes and all text in the CSV file supplied must then have the text wrapped in double quotes. The default is blank, meaning no qualifier is in use.
|
Samples and Schemas are available for XML, JSON and CSV from the menu bar.
Where the import content contains an unknown Card Number it will be created. Where the content contains a known card number, and where the balance or status has changed the card number will be updated and where applicable a transaction will be created. A maximum of 1000 card numbers can imported in any one file.
To view the progress and results of the card number import, view the Import Log from Configuration.
Activating a Card Number
Card numbers which have a status of Pending or Allocated must be Activated before their balance is available to be redeemed against. A card number can be activated via the API services, or in the Qixol Promo Portal by selecting Activate from the Cards List, where the following fields are available:
|
Field
|
Editable?
|
Description
|
|
Group
|
|
The group which contains the card number.
|
|
Card Number
|
|
The card number to be activated.
|
|
Status
|
*
|
The new status of the card number.
Available dependant upon the current status of the card number, and the Card Group configuration option Use Activation Tokens?
Where Use Activation Tokens? is selected on the Card Group:
Where the card number has a status of Pending, it may have a new status of either Allocated or Active.
Where the card number has a status of Allocated, it may have a new status of Active.
Where Use Activation Tokens? is not selected on the Card Group:
Where the card number has a status of Pending, it may have a new status of Active.
|
|
Balance
|
*
|
The new balance of the card number. Available where the card status is currently Pending. Where available, a value greater than zero must be specified and the value must be less than the Maximum Card Balance defined against the card number Group.
|
|
Currency Code
|
|
The currency code for the balance. Available where the card status is currently Pending. The currency code for a card number cannot be changed after it is Allocated/Activated with a balance.
|
|
Card Expiry Date
|
*
|
The expiration date of the card number. The card expiry date will be calculated based on the Card Group, and will be editable where the Card Group has the option Permit expiry override? enabled.
|
|
Customer Reference
|
|
Where available the customer reference for the card number.
|
|
Transaction Reporting Code
|
|
When the new card number is Allocated or Activated, a transaction will be captured for the new balance. Where required, a reporting code can be provided for the transaction.
|
|
Transaction Reference
|
|
Where available the transaction reference for the card number.
|
|
Comments
|
|
Comments relating to the card number creation.
|
Deleting a Card Number
Card numbers with a status of Pending can be deleted. Card numbers can be deleted via the API services, or by using the Card Numbers Import, or in the Qixol Promo Portal by selecting Delete from the Cards List.
Withdrawing a Card Number
Card numbers can be withdrawn where the status is Allocated or Active. Card numbers can be withdrawn via the API services, or by using the Card Numbers Import, or in the Qixol Promo Portal by selecting Withdraw from the Cards List, where the following fields are available:
|
Field
|
Editable?
|
Description
|
|
Card Number
|
|
The card number to be withdrawn.
|
|
Withdrawal Reporting Code
|
|
The reporting code to be assigned to the Withdrawal transaction for the card number.
|
|
Comments
|
|
The comments to be captured against the Withdrawal transaction for the card number.
|
Adjusting the Balance of a Card Number
The balance of a card number can be adjusted, where the status is Active or Redeemed. Balance adjustments can be actioned via the API services, or by using the Card Numbers Import, or in the Qixol Promo Portal by selecting Adjust Balance from the Cards List, where the following fields are available:
|
Field
|
Editable?
|
Description
|
|
Card Number
|
|
The card number against which to apply the balance adjustment.
|
|
Adjustment Type
|
|
The type of adjustment to apply. Select either Add Amount or Subtract Amount.
|
|
Amount
|
|
The amount to adjust the balance by. Values entered must always be positive. The amount, combined with the current balance of the card number, must not exceed the defined Maximum Card Balance defined against the card number Group.
|
|
Adjustment Reporting Code
|
|
The reporting code to be captured against the adjustment transaction.
|
|
Transaction Reference
|
|
The reference to be captured against the adjustment transaction.
|
|
Comments
|
|
The comments to be captured against the adjustment transaction.
|
Card Number Transactions
Each activity against a card number will create a transaction. Transactions can be extracted via the API services, or can be viewed in the Qixol Promo Portal by selecting Transactions from the Cards List.
For further information about details available with each transaction, view Transactions.
|
|
