6 Cards
Overview
This chapter provides developers with the request format for card requests sent to the Customer Engagement server. The following request is supported:
Defined Versus Generated Card Series
It is important to note the difference between a defined card series and a generated card series.
A defined card series is exactly that, defined. Only the name, description, number of cards, and number of batches have been created and saved. Individual cards with card numbers and serial numbers have not been created at this time.
A generated card series is one where the individual cards with the card numbers, serial numbers, and PINs (if applicable), have been created. A card series must be defined before it can be generated.
Card Numbering
Serial Number
The serial number is a sixteen digit number that is generated and appended to the prefix number, series number, and batch number.
Prefix Number
The prefix number is the first five digits of the card serial number. The prefix number uniquely identifies a card as belonging to a specific merchant.
Card Series Number
This number is a two-digit sequential, system generated number that represents each card’s production run. The Series Number starts with zero-one (01) for each prefix number.
Batch Number
The batch Number is a 3-digit sequential, system generated number which defines how groups of cards are physically packaged together for distribution and storage. The batch number starts over at 001 for each Series Number.
Sequence Number
The sequence number is a 6-digit sequential, system generated number that allows the handler to quickly remove a required number of cards from a batch without necessarily counting each one (assuming the factory order is maintained). The sequence numbering resets with each series.
Generate Card
There are two ways that the Generate Card request can be used:
-
Generate a single card in a specified card series, create the appropriate accounts, activate the card and accounts, add any initial account balances specified in the request, and associate or link that card (and associated accounts) to a known customer.
-
Generate a single card in a specified card series, create the appropriate accounts, activate the card and accounts, and add any initial account balances specified in the request.
Note:
The accounts that are created depend upon whether a program of that type exists.
Requirements/Restrictions
Generate Card requests can be created with customer association or without.
-
The minimum data elements required for a valid Generate Card request without association is the <CardPrefix> and <CardSeriesSequence>. For this kind of request, the <Customer> block must be removed.
-
The minimum data elements required for a valid Generate Card request with association is <CardPrefix>, <CardSeriesSequence>, and either a <CustomerID> or an <AlternateID>.
-
If <AlternateID> is used, the <AlternateKey TypeCode=" "> must also be provided.
-
If both the <CustomerID> and <AlternateID> are provided, the <CustomerID> takes precedence.
-
Multiple association requests for the same card series can be made in a batch file by repeating <CardSeries> blocks.
Fields
The elements in the table below are the elements/attributes that may be used in a GenerateCard request. The sample request shows the placement of these elements/attributes. Not all of these elements/attributes must be used in a request.
| XML Tag | Comments |
|---|---|
|
<CardSeries Action="GenerateCard"> <UserName> |
Name of the individual/organization performing the generate |
|
<UserOrganization> |
User organization performing the generate |
|
<CardPrefix> |
(required) 5-digit card type |
|
<CardSeriesSequence> |
(required) 2-digit card series number |
|
<CardNumber> |
Card number of card generated (for generating cards while system is offline) |
|
<Customer> |
(Optional) |
|
<CustomerID> |
Customer Engagement customer ID number |
|
<AlternateKey TypeCode=" "> |
TypeCode - Type of alternate ID |
|
<AlternateID> |
Customer’s alternate ID |
|
<RTPTransaction> |
(Optional) The transaction performing the request |
|
<RTPTransactionID> |
ID of the card generate transaction |
|
<OperatorID> |
ID of the user performing the card generate |
|
<LocationID> |
ID of the generating location |
|
<TransactionDateTime> |
Date and time of the card generate |
|
<DeviceID> |
ID of the device performing the card generate |
|
<BusinessDate> |
Business date of the card generate |
|
<RTPAmount> |
Information about the card generate amount |
|
<CurrencyID> |
Currency used in the card generate |
|
<Amount> |
Tender amount to add to each card when generating a Tender Card sequence |
|
<AwardAmount> |
Award amount to add to each card when generating an Award Card sequence |
|
<LoyaltyAmount> |
Loyalty amount to add to each card when generating a Loyalty Card sequence |
Example
A GenerateCard request should appear similar to the example below. The card data included will vary according to each particular request. If you do not want to associate the card with a customer, remove the <Customer> block.
If multiple cards are being generated and associated in the same batch file with multiple <CardSeries> blocks, the <CardPrefix> and <CardSeriesSequence> must be the same for each <CardSeries> block.
<?xml version="1.0" encoding="UTF-8"?><CardSeriesMaintenance> <CardSeries Action="GenerateCard"> <UserName>TestUser</UserName> <UserOrganization>Test User Organization</UserOrganization> <CardPrefix>123456</CardPrefix> <CardSeriesSequence>01</CardSeriesSequence> <RTPTransaction> <RTPTransactionID><TRANS_ID></RTPTransactionID> <OperatorID><ID></OperatorID> <LocationID><LOCATION_ID></LocationID> <TransactionDateTime>2011-10-10T03:59:00</TransactionDateTime> <DeviceID><DEVICE_ID><DEVICE_ID></DeviceID> <BusinessDate>2011-10-10</BusinessDate> <RTPAmount> <CurrencyID>USD</CurrencyID> <Amount>100</Amount> <AwardAmount>25.50</AwardAmount> <LoyaltyAmount>50</LoyaltyAmount> </RTPAmount> </RTPTransaction> <!-- Associating a Customer to card is optional --> <Customer> <CustomerID><CUST_ID></CustomerID> <AlternateKey TypeCode="XSTORE_ID"> <AlternateID><ALTERNATE_ID></AlternateID> </AlternateKey> </Customer> </CardSeries></CardSeriesMaintenance>
The above request uses the <CustomerID> to identify the customer. If desired, you may use the customer’s <AlternateID> instead. An example of the <Customer> block that you would use is shown below.
... <Customer> <CustomerID></CustomerID> <AlternateKey TypeCode="TWCUSTID"> <AlternateID><ALTERNATE_ID></AlternateID> </AlternateKey> </Customer> ...
Batch Processing Errors
The following table contains a list of errors that may occur and possible causes:
| Error | Cause |
|---|---|
|
ACTIVATION_DATE_DOES_NOT_MEET_CARD_EXPIRATION_DATE |
The attempt to activate the card is occurring prior to the eligibility start date for the card. |
|
ALL_CARDS_GENERATED |
All cards in the specified series have been generated. |
|
CARD_SERIES_NOT_FOUND |
The card series specified in the request cannot be found. |
|
CARD_SERIES_PREFIX_UNSPECIFIED |
The card series prefix was not specified in the request. |
|
CARD_SERIES_UNSPECIFIED |
The card series was not specified in the request. |
|
CUSTOMER_NOT_FOUND |
No customers could be found based on the parameters provided. |
|
FOREIGN_CURRENCY_NOT_ALLOWED |
Foreign currencies are not allowed by the program. The request must use the base currency for the program. |
|
GENERAL_ERROR |
A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant. |
|
ILLEGAL_RETAIL_TRANSACTION_ID |
The retail transaction data specified does not match the organization's configured parameters. |
|
MIN_ACTIVATION_AMT_NOT_MET |
The activation amount is less than the minimum activation amount for the Tender Program. |
|
MIN_BALANCE_NOT_MET |
The requested amount plus the current account balance is less than the Minimum Balance requirements defined for the Tender Program. |
|
PROGRAM_EXPIRED |
The Expiry Date for the program (tender, award, and loyalty) has passed. |
|
PROGRAM_NOT_EFFECTIVE |
The tender account has never been activated before (Activation Date = null) and the tender program Effective Date is not null and it is greater than the current date. |
|
RELATE_SERVICES_GENERAL_CONFIGURATION_ERROR |
The card number prefix character in the configuration file is more than one character in length. Refer to the Customer Engagement Implementation Guide for more information on the card number prefix character. |
|
The numeric part of the card number is greater than the maximum length (16). |
|
|
The numeric part of the card number is less than the minimum length (10). |
|
|
CARD_BATCHES_UNSPECIFIED |
The Card Series specified does not contain any defined batches. |
|
CARD_BATCH_NOT_FOUND |
The Card Batch number within the generated or supplied Card Number cannot be found in the Card Series definition. |
|
ILLEGAL_PROGRAM_ACCOUNT_SETUP |
No card type found for the specified card prefix. |
|
CONFIGURATION_ERROR |
The account management default reason code (AccountManagementDefaultReasonCode) configuration setting is not set. This is required when activating a card. |
|
GENERATE_CARD_ERROR_DUPLICATES_FOUND |
Duplicate card numbers found in the system when generating the card number based on the information supplied and the configuration of the card type. |
Batch File Response
A complete copy of the incoming request is placed in the/complete/[Fileset Name]/archived directory.
Each <CardSeries> block in the request that was not successfully processed is placed in a file with _failures appended to the original filename in the /complete/[Fileset Name]/failed directory.
You may be able to determine the reason for the failure by using the Batch Import Review pages (see Batch Import Review).