1. Batch Processing and Web Services Guide
  2. Stored Value

9 Stored Value

This chapter provides developers with formats for the Stored Value requests sent to the Customer Engagement server. The following types of requests are supported:

Each time one of the above message types is processed, successfully or unsuccessfully, an entry is added to an activity file.

Activate Instrument Request

This request will activate the specified card and all associated accounts: tender, loyalty, and award.

Additional actions taken by the system depend on whether the card has been active before. If the card has never been activated before, the program must be active.

Tasks

The following table lists the tasks that are performed as part of the Activate Instrument process.

Object Action

Tender Account (General)

Set the Active Flag to true.

Set the Last Activity Date to the current date/time.

Set the Account Status to Active.

Tender Account (Never Activated)

Set the activation amount to the initial account balance or the amount provided in the message (if any).

Set the initial activity date to the current date/time.

Set the activation date for the account to the current date/time.

Set the effective date for the account to the current date/time.

Set the expiry date for the account.

Set the initial balance to the activation amount.

Set the total credits to the activation amount.

Set the total debits to zero (0).

Set the report balance to the activation amount.

Set the Frozen Balance to zero (0).

Set the Usage Count to zero (0).

Tender Account (Previously Activated)

Set the Activation Amount to the message amount or zero (0) if there is no message amount.

Set the Balance to the Activation Amount plus the Current Balance.

Set the Report Balance to the current Report Balance plus the Activation Amount.

Set the Total Credits to the current Total Credits plus the Activation Amount.

Loyalty Account (General)

Set the Active Flag to true.

Set the Last Activity Date to the current date/time.

Set the Update Date to the current date/time.

Set the Update User ID to the User ID.

Set the Expiry Date to Null.

Loyalty Account (Never Activated)

Set the Initial Activity Date to the current date/time.

Set the Activation date to the current date/time.

Set the Effective Date to the current date/time.

Set the Loyalty Points Balance to the amount specified in the request message (if any). If the account was previously activated, the amount specified will be added to the current Points Balance.

If the Entitlement Deal definition for the loyalty level is defined as “Issue automatically when transaction posted,” then an Entitlement Coupon is issued.

Points will be issued for any eligible points promotions linked to the loyalty level associated with the account.

Award Account (General)

Set the Active Flag to true.

Set the Last Activity Date to the current date/time.

Set the Update Date to the current date/time.

Set the Update User ID to the User ID.

Set the Expiry Date for the account.

Award Account (Never Activated)

Set the Initial Activity Date to the current date/time.

Set the Activation date to the current date/time.

Set the Effective Date to the current date/time.

Set the Award Balance to the amount specified in the request message (if any). If account was previously activated, no additional award will be applied.

If the Entitlement Deal definition for the Award Program is defined as “Issue automatically when first activated,” then an Entitlement Coupon is issued at activation.

Card (General)

Set the Active Flag to True.

Set the Last Used Date to the current date/time.

Card (Never Activated)

Set the Activation Date to the current date/time.

Set the First Used Date to the current date/time.

Requirements/Restrictions

The minimum data element/attribute required for a valid Activate Instrument Request is the card number. Any other elements/attributes provided serve to further identify the proper card/account and must be correct and/or valid. If any of these additional elements/attributes are incorrect and/or invalid, an error message will be returned.

A PIN is required if:

  • The card definition always requires a PIN.

  • The card definition requires a PIN if a card is not physically present and the request message does not include a <CardSwiped> element set to true.

Tender and Account Awards

If there is an amount in the request, it is used as the activation amount.

  • If the amount in the message is $125 and the initial program balance is $100, the account is activated for $125.

  • If the amount in the message is $0 and the initial program balance is $100, the account is activated for $0.

  • If the amount in the message left blank, and the initial program balance is $100, the account is activated for $100.

Loyalty Accounts

If there is an amount in the request, it is used as the activation amount.

  • If the amount in the message is 100 points, the account is activated with 100 loyalty points.

  • If the amount in the message is 0 or empty, the account is activated with a zero points balance.

Fields

The elements in the table below are the elements/attributes that may be used in an ActivateInstrument request. The sample message shows the placement of these elements/attributes. Not all of these elements/attributes must be used in a request.

XML Tag Comments

<UserID>

ID of user making the request.

<UserOrganization>

ID of the Franchisee to which the user belongs.

<Instrument>

<AuthenticationData>

PIN.

<CardNumber>

Card Number.

<CardSwiped>

Indicates whether the card was physically present (True) or not (False or empty).

<RTPTransaction>

<RTPTransactionID>

POS transaction ID.

<OperatorID>

POS operator.

<LocationID>

POS location.

<TransactionDateTime>

Date and time of the transaction.

<DeviceID>

POS device ID.

<BusinessDate>

Business date of transaction.

<RTPAmount>

<CurrencyID>

3-character currency type.

<Amount>

Initial amount for the tender account. Cannot be negative.

<AwardAmount>

Initial amount for the award account. Cannot be negative.

<LoyaltyAmount>

Initial amount for the loyalty account. Cannot be negative.

<Comments>

User comments (up to 1000 characters).

<UnblockAccount>

Special case to unblock a tender account instead of activating (True). If the tender account status is Blocked, it will be set to Inactive.

<ReasonCode>

Code identifying the reason for the transaction.

Example

When generating an ActivateInstrument request, the XML message should appear similar to the example below. The data included will vary according to each particular request.

<?xml version="1.0" encoding="UTF-8"?><ARTSData>  <ActivateInstrumentRequest>    <UserID><USERID></UserID>    <UserOrganization><FRANCHISEE_ID></UserOrganization>    <Instrument>      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>    </Instrument>    <RTPTransaction>      <RTPTransactionID><TRANS_ID></RTPTransactionID>      <OperatorID><OPERATOR_ID></OperatorID>      <LocationID><LOC_ID></LocationID>      <TransactionDateTime>2009-02-11T03:59:00</TransactionDateTime>      <DeviceID><DEVICE_ID></DeviceID>      <BusinessDate>2009-02-11</BusinessDate>      <RTPAmount>        <CurrencyID>USD</CurrencyID>        <Amount>200</Amount>        <AwardAmount>50</AwardAmount>        <LoyaltyAmount>50</LoyaltyAmount>      </RTPAmount>    </RTPTransaction>    <Comments>Activate comment</Comments>    <ReasonCode></ReasonCode>  </ActivateInstrumentRequest></ARTSData>

Batch Processing Errors

The following table contains a list of errors that may occur and possible reasons they occurred:

Error Reasons

ACCOUNT_ALREADY_ACTIVE

The account Active Flag is True, or the Account Status for the account is Active.

ACCOUNT_BLOCKED

The associated tender account is blocked.

Note: You must first unblock the account using the Card/Account Admin GUI (see Customer Engagement User Guide).

ACCOUNT_NOT_BLOCKED

The associated tender account is not blocked when the UnblockAccount flag is True.

ACCOUNT_ALREADY_MERGED_CAN_NOT_PERFORM

The associated tender account has been merged

ACCOUNT_EXPIRED

An account has previously been activated (Activation Date not Null) and there is an Expiry Date for the account and the Expiry Date is less than the current date.

ACCOUNT_SETUP_ERROR

The account has an unexpected, invalid state.

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.

AWARD_PROGRAM_EXPIRED

The award account has never been activated (Activation date = null) and the award program Expiry Date is not null and it is less than the current date.

AWARD_PROGRAM_NOT_EFFECTIVE

The award account has never been activated (Activation Date is null) and there is an award program Effective Date and it is greater than the current date.

CARD_EXPIRED

There is an Expiration Date for the card and it is less than the current date.

CARD_NOT_FOUND

The card specified in the request could not be found.

CURRENCY_CODE_INVALID

Request contains an invalid Currency Code.

CURRENCY_EXCHANGE_RATE_NOT_FOUND

The exchange rate for the specified currency code was not found.

FOREIGN_CURRENCY_NOT_ALLOWED

Foreign currencies are not allowed by the program. The request must use the base currency for the program.

FRANCHISEE_NOT_FOUND

The franchisee organization was not found.

GENERAL_ERROR

A general, non-specific error. If you cannot determine the cause of the problem, contact your Project Consultant.

INVALID_DATA_FOR_REQUEST

Request is missing data or contains invalid data.

LYL_ACCOUNT_ALREADY_ACTIVE

The loyalty account Active Flag is True.

LYL_PROGRAM_EXPIRED

The loyalty account has never been activated (Activation Date = null) and the loyalty program Expiry Date is not null and it is less than the current date.

LYL_PROGRAM_NOT_EFFECTIVE

The loyalty account has never been activated (Activation Date is null) and there is a loyalty program Effective Date and it is greater than the current date.

MAX_BALANCE_EXCEEDED

There is a Maximum Balance and the message amount plus the current account Balance plus the Frozen Balance is greater than the Maximum Balance.

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.

NEGATIVE_AMOUNT_ERROR

The amount in the request is less than zero.

PROGRAM_EXPIRED

The tender account has never been activated (Activation Date = null) and the tender program Expiry Date is not null and it is less than the current date.

PROGRAM_INACTIVE

The program has been deactivated (inactive).

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.

REASON_CODE_REQUIRED

Request is missing the required reason code.

RETAIL_TRANSACTION_ID_ILLEGAL

Retail transaction data in request invalid, based on organization’s configuration.

Deactivate Instrument Request

This request will deactivate the specified card and all associated accounts.

Tasks

The system performs the following tasks as part of the Deactivate Instrument process.

Object Action

Tender Account

Set the Active Flag to False.

Set the Last Activity Date to the current date/time.

Set the Account Status to Blocked.

Loyalty Account

Set the Active Flag to False.

Set the Last Activity Date to the current date/time.

Set the Update Date to the current date/time.

Set the Update User ID to the User ID.

Award Account

Set Active Flag to False.

Card

Set the Active Flag to False.

Set the Last Used Date to the current date/time.

If the tender account is blocked, an error is generated and the process stopped.

Requirements/Restrictions

The minimum data element/attribute required for a valid Deactivate Instrument Request is the card number. Any other elements/attributes provided serve to further identify the proper card/account and must be correct and/or valid. If any of these additional elements/attributes are incorrect and/or invalid, an error message will be returned.

Fields

The elements in the table below are the elements/attributes that may be used in a DeactivateInstrument request. The sample message shows the placement of these elements/attributes. Not all of these elements/attributes must be used in a request.

XML Tag Comments

<UserID>

ID of user making the request.

<UserOrganization>

ID of the Franchisee to which the user belongs.

<Instrument>

<AuthenticationData>

PIN.

<CardNumber>

Card Number.

<RTPTransaction>

<RTPTransactionID>

POS transaction ID.

<OperatorID>

POS operator.

<LocationID>

POS location.

<TransactionDateTime>

Date and time of the transaction.

<DeviceID>

POS device ID.

<BusinessDate>

Business date of transaction.

<Comments>

User comments (up to 1000 characters).

<ReasonCode>

Code identifying the reason for the transaction.

Example

When generating a DeactivateInstrument request, the XML message should appear similar to the example below. The data included will vary according to each particular request.

<?xml version="1.0" encoding="UTF-8"?><ARTSData>  <DeactivateInstrumentRequest>    <UserID><USERID></UserID>    <UserOrganization><FRANCHISEE></UserOrganization>    <Instrument>      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>    </Instrument>    <RTPTransaction>      <RTPTransactionID><TRANS_ID></RTPTransactionID>      <OperatorID><OPERATOR_ID></OperatorID>      <LocationID><LOC_ID></LocationID>      <TransactionDateTime>2011-10-10T03:59:00</TransactionDateTime>      <DeviceID><DEVICE_ID></DeviceID>      <BusinessDate>2011-10-10</BusinessDate>    </RTPTransaction>    <Comments>Special Comments</Comments>    <ReasonCode></ReasonCode>  </DeactivateInstrumentRequest></ARTSData>

Batch Processing Errors

The following table contains a list of errors that may occur and possible reasons they occurred:

Error Reason

ACCOUNT_BLOCKED

The associated tender account is blocked.

Note: You must first unblock the account using the Card/Account Admin GUI (see Customer Engagement User Guide).

CARD_NOT_FOUND

The card specified in the request could not be found.

FRANCHISEE_NOT_FOUND

The franchisee organization was not found.

ILLEGAL_RETAIL_TRANSACTION_ID

The retail transaction data specified does not match the organization's configured parameters.

INVALID_DATA_FOR_REQUEST

Request is missing data or contains invalid data.

LYL_ACCOUNT_ALREADY_INACTIVE

The loyalty account Active Flag is False.

REASON_CODE_REQUIRED

Request is missing the required reason code.

Replace Request

This request is used to consolidate the balances and transaction histories of multiple accounts into a single account. This request acts at the card level. The source or original card is the card containing the account that will be consolidated into the other. The target or destination/replacement card is the one that will receive the balance from the source.

Tasks

The system will perform the following tasks for the source and target cards/accounts:

Source

  • Deactivate the accounts.

  • If there is a Tender account, it sets the status to Blocked.

  • Deactivates the card.

  • All Source activities for Tender accounts will remain on the original source account. All Source loyalty or award account activities will be moved to the new Target card.

  • Set the tender account balances to zero.

  • When possible, a Merge activity is created on the accounts and any merge dates or flags are updated.

  • Loyalty and award account Inquiry activities are deleted from the source and are not moved to the target accounts.

Target

  • Activates the card and accounts (if necessary).

  • All account balances (Source and Target) are summed and stored in the Target account.

  • The most recent activity dates are set for the Target card, where possible.

  • When possible, a Merge activity is created for the accounts, and any merge dates or flags will be updated.

Requirements/Restrictions

This request has the following restrictions and requirements:

  • The minimum data element/attribute required for a valid Replace Request is both card numbers.

    Any other elements/attributes provided serve to further identify the proper card/account and must be correct and/or valid. If any of these additional elements/attributes are incorrect or invalid, an error message will be returned.

  • Both accounts must share the same program.

  • A merge cannot happen if the source card or any of its accounts are inactive or blocked.

  • The Target card and accounts can be inactive, but not blocked. An activation will be performed on the Target card, if necessary.

  • The Source and Target cards cannot be associated to different customers.

  • Tender accounts cannot have any unsettled Preauthorizations.

Fields

The elements in the table below are the elements/attributes that may be used in a Replace request. The sample message shows the placement of these elements/attributes. Not all of these elements/attributes must be used in a request.

XML Tag Comments

<UserID>

ID of user making the request.

<UserOrganization>

ID of the Franchisee to which the user belongs.

<OrginalInstrument>

The source card.

<AuthenticationData>

PIN.

<CardNumber>

(required) Card Number for the source card.

<CardSwiped>

Indicates whether the card was physically present (True) or not (False or empty)

<ReplacementInstrument>

The Target card

<AuthenticationData>

PIN

<CardNumber>

(required) Card Number for the target card

<RTPTransaction>

<RTPTransactionID>

POS transaction ID.

<OperatorID>

POS operator.

<LocationID>

POS location.

<TransactionDateTime>

Date and time of the transaction.

<DeviceID>

POS device ID.

<BusinessDate>

Business date of transaction.

<Comments>

User comments (up to 1000 characters).

<ReasonCode>

Code identifying the reason for the transaction.

Example

When generating a Replace request, the XML message should appear similar to the example below. The search parameters will vary according to each particular request.

<?xml version="1.0" encoding="UTF-8"?><ARTSData>  <ReplaceRequest>    <UserID>TestUser</UserID>
    <UserOrganization><FRANCHISEE></UserOrganization>
    <OriginalInstrument>      <AuthenticationData></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>    </OriginalInstrument>    <ReplacementInstrument>      <AuthenticationData></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>
    </ReplacementInst0ment>    <RTPTransaction>      <RTPTransactionID><TRANS_ID></RTPTransactionID>      <OperatorID><OPERATOR_ID></OperatorID>      <LocationID><LOCATION_ID></LocationID>      <TransactionDateTime>2011-10-10T03:59:00</TransactionDateTime>      <DeviceID><DEVICE_ID></DeviceID>      <BusinessDate>2011-10-10</BusinessDate>    </RTPTransaction>    <Comments>Special Comments</Comments>    <ReasonCode></ReasonCode>  </ReplaceRequest></ARTSData>

Batch Processing Errors

The following table contains a list of errors that may occur and possible reasons they occurred:

Error Reasons

ACCOUNT_ALREADY_MERGED

The original account has already been merged.

ACCOUNT_BLOCKED

The associated tender account is blocked.

Note: You must first unblock the account using the Card/Account Admin GUI (see Customer Engagement User Guide).

ACCOUNT_EXPIRED

There is an Expiry Date for the account and it is less than or equal to the current date.

ACCOUNT_NOT_EFFECTIVE

The account's effective date is greater than the current date.

CANNOT_MERGE_CARDS_PROGRAM_BLOCKED_MERGE

Card merge is not permitted, based on the program definition.

CANNOT_MERGE_CARDS_WITH_DIFFERENT_OWNERS

Source and target cards are associated with different customers.

CANNOT_MERGE_FROM_INACTIVE_TENDER_ACCOUNT

Source account is inactive.

CARD_EXPIRED

There is an Expiration Date for the card and it is less than the current date.

CARD_NOT_FOUND

The card specified in the request could not be found.

CARD_NUMBER_REQUIRED

The card number was not provided.

CARD_SETUP_ERROR

Source and target cards from different programs.

CONTAINS_OUTSTANDING_PREAUTHS

The original tender account has outstanding preauths (Frozen Balance > 0).

EXCEEDED_DAILY_USES

This request plus the number of times the card was used on this Business Date is greater than or equal to the Maximum Daily Uses specified in the program.

EXCEEDED_LIFETIME_USES

The tender account Usage Count is greater than or equal to the Maximum Lifetime Uses in the program.

FRANCHISEE_NOT_FOUND

The franchisee organization was not found.

ILLEGAL_RETAIL_TRANSACTION_ID

The retail transaction data specified does not match the organization's configured parameters.

INVALID_DATA_FOR_REQUEST

Request is missing data or contains invalid data.

INVALID_PIN

The PIN supplied in the request is not valid.

MAX_BALANCE_EXCEEDED

There is a Maximum Balance and the message amount plus the current account Balance plus the Frozen Balance is greater than the Maximum Balance.

MISSING_NEW_PIN_ERROR

A new PIN number is required and the new PIN number was not provided in the request message.

MISSING_PIN_ERROR

A PIN is required and was not provided in the request.

REASON_CODE_REQUIRED

Request is missing the required reason code.