Awards

Overview

This chapter provides developers with message formats for award account requests sent to the Customer Engagement server. The following requests are supported:

Redeem Coupon

This request specifies which coupons to redeem and how much to redeem on each coupon. This information is selected by the customer/POS.

The redemption will be performed and the results displayed in whatever currency is specified in the request.

This message type cannot be used in a batch environment as it was designed for interactive use (that is, request-response).

Requirements/Restrictions

The <CurrencyID>, <CardNumber>, <AwardAccountID>, <Coupon id=" ">, and an <Amount> must be included in the request.

The <CurrencyID> must be valid and the exchange rate for the currency specified in the request must have been downloaded for the organization.

If both the <CardNumber> and <InstrumentID> (Serial Number) are included, both of them must be valid and for the same card.

If the physical card must be present as specified by the associated program, <CardSwiped> must equal true.

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.

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 Redeem Coupon request. The sample request message shows the placement of these elements/attributes. Not all of these elements/attributes must be used in a request.

XML Tag	Comments
`<CurrencyID>`	(required) The currency being used for the transaction.
`<TransactionID>`
`<UserID>`	POS User.
`<StoreID>`	Retail location where transaction is taking place.
`<RegisterID>`	POS register where transaction is taking place.
`<BusinessDate>`	Business date of the transaction (yyyy-mm-dd).
`<SequenceNumber>`	Sequential number for transaction assigned by POS.
`<Instrument>`
`<InstrumentID>`	This is the serial number of the card.
`<AuthenticationData>`	PIN.
`<CardNumber>`	(required) Card Number.
`<CardSwiped>`	Indicates whether the card was physically present (True) or not (False or empty)
`<AwardAccountID>`	(required) Award Account that contains coupons being redeemed.
`<Coupons>`	Coupons attached to the Award Account to be redeemed. Can have multiple coupons.
`<Coupon id=" ">`	(required) ID of the coupon to redeem.
`<RequestAmount>`
`<Amount>`	(required) Amount to redeem. Cannot exceed value of coupon.
`<Comments>`	User comments for transaction detail.
`<ReasonCode>`	ID code for the reason for redeeming the coupons.
<IgnoreExpirationDate>	Indicates whether the expiration date of the account should be ignored.
<FranchiseeName>	(required) Name of the franchisee.

Example

When generating a RedeemCoupons 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"?><Awards>  <AwardRequest Type="RedeemCoupons">    <CurrencyID>USD</CurrencyID>    <TransactionID>      <UserID><USERID></UserID>      <StoreID><STORE_ID></StoreID>      <RegisterID><REGISTER_ID></RegisterID>      <BusinessDate>2015-01-10</BusinessDate>      <SequenceNumber>12345678</SequenceNumber>    </TransactionID>    <Instrument>      <InstrumentID><INSTRUMENT_ID></InstrumentID>
      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>    </Instrument>    <AwardAccountID><ACCOUNT_ID></AwardAccountID>    <!-- Use multiple <Coupons></Coupons> blocks to redeem more than one coupon -->    <Coupons>      <Coupon id = "<COUPON<ID>">        <RequestAmount>          <Amount>15</Amount>        </RequestAmount>      </Coupon>    </Coupons>    <Comments>Special Comments</Comments>    <ReasonCode></ReasonCode>
    <IgnoreExpirationDate>false</IgnoreExpirationDate>    <FranchiseeName></FranchiseeName>
  </AwardRequest></Awards>

Multiple coupons can be redeemed by including multiple <Coupon> tags. The coupons included in the request can be partial or full redeems.

Batch Processing Errors

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

Error	Reasons
ACCOUNT_EXPIRED	There is an Expiry Date for the account and it is less than or equal to the current date.
ACCOUNT_NOT_FOUND	The account number specified in the request could not be found.
CARD_EXPIRED	There is an Expiration Date for the card and it is less than the current date.
CARD_INACTIVE	The card is not active (Active Flag = False).
CARD_NOT_FOUND	The card specified in the request could not be found.
CARD_NUMBER_REQUIRED	The card number was not provided.
COUPON_IDENTIFIED_INVALID_OR_EXPIRED	The requested coupon ID does not exist or has expired.
COUPON_REQUEST_AMOUNT_INVALID	There was no amount or an invalid amount was specified in the request.
COUPON_REQUEST_EXCEEDS_BALANCE	The amount in the request is greater than the coupon(s) balance.
COUPON_REQUEST_NEGATIVE_AMOUNT_INVALID	The amount in the request is less than or equal to zero.
CURRENCY_EXCHANGE_RATE_NOT_FOUND	The exchange rate for the specified currency code was not found.
CURRENCY_ID_MISSING_IN_REQUEST	The `<CurrencyID>` XML tags are not included in the request message.
FOREIGN_CURRENCY_NOT_ALLOWED	Foreign currencies are not allowed by the program. The request must use the base currency for the program.
ILLEGAL_RETAIL_TRANSACTION_ID	The retail transaction data specified does not match the organization's configured parameters.
INVALID_PIN	The PIN supplied in the request is not valid.
MISSING_PIN_ERROR	A PIN is required and was not provided in the request.
NO_PHYSICAL_CARD	The card is required to be present and it was not supplied (Card Swiped Flag = False).

Automatic Redeem

This request specifies the amount to redeem. The system then determines which coupon(s) to redeem and for what amount.

The redemption will be performed and the results displayed in the currency specified in the request.

Requirements/Restrictions

The <CurrencyID>, <CardNumber>, <AwardAccountID>, and <Amount> must be included in the request.

The <CurrencyID> must be valid and the exchange rate for the currency specified in the request must have been downloaded for the organization.

If both the <CardNumber> and <InstrumentID> (Serial Number) are included, both of them must be valid and for the same card.

If the physical card must be present as specified by the associated program, <CardSwiped> must equal true.

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.

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 an Automatic Redeem 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
`<CurrencyID>`	(required) The currency being used for the transaction.
`<TransactionID>`
`<UserID>`	POS User.
`<StoreID>`	Retail location where transaction is taking place.
`<RegisterID>`	POS register where transaction is taking place.
`<BusinessDate>`	Business date of the transaction (yyyy-mm-dd).
`<SequenceNumber>`	Sequential number for transaction assigned by POS.
`<Instrument>`
`<InstrumentID>`	This is the serial number of the card.
`<AuthenticationData>`	PIN.
`<CardNumber>`	(required) Card Number.
`<CardSwiped>`	Indicates whether the card was physically present (True) or not (False or empty)
`<AwardAccountID>`	(required) Award Account that contains coupons being redeemed.
`<RequestAmount>`
`<Amount>`	(required) Amount to redeem. Cannot exceed value of coupon.
`<Comments>`	User comments for the transaction detail.
`<ReasonCode>`	ID code for the reason for the automatic redemption.

Example

When generating an AutomaticRedeem 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"?><Awards>  <AwardRequest Type="AutomaticRedeem">    <CurrencyID>USD</CurrencyID>    <TransactionID>      <UserID><USERID></UserID>      <StoreID><STORE_ID></StoreID>      <RegisterID><REGISTER_ID></RegisterID>      <BusinessDate>2015-01-10</BusinessDate>      <SequenceNumber>23456789</SequenceNumber>    </TransactionID>    <Instrument>      <InstrumentID><INSTRUMENT_ID></InstrumentID>      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>    </Instrument>    <AwardAccountID><ACCOUNT_ID></AwardAccountID>    <RequestAmount>      <Amount>80</Amount>    </RequestAmount>    <Comments>Special Comments</Comments>    <ReasonCode></ReasonCode>
  </AwardRequest></Awards>

Batch Processing Errors

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

Error	Reasons
ACCOUNT_EXPIRED	There is an Expiry Date for the account and it is less than or equal to the current date.
ACCOUNT_NOT_FOUND	The account number specified in the request could not be found.
CARD_EXPIRED	There is an Expiration Date for the card and it is less than the current date.
CARD_INACTIVE	The card is not active (Active Flag = False).
CARD_NOT_FOUND	The card specified in the request could not be found.
CARD_NUMBER_REQUIRED	The card number was not provided.
COUPON_REQUEST_AMOUNT_INVALID	There was no amount or an invalid amount was specified in the request.
COUPON_REQUEST_EXCEEDS_BALANCE	The amount in the request is greater than the coupon(s) balance.
COUPON_REQUEST_NEGATIVE_AMOUNT_INVALID	The amount in the request is less than or equal to zero.
CURRENCY_EXCHANGE_RATE_NOT_FOUND	The exchange rate for the specified currency code was not found.
CURRENCY_ID_MISSING_IN_REQUEST	The `<CurrencyID>` XML tags are not included in the request message.
FOREIGN_CURRENCY_NOT_ALLOWED	Foreign currencies are not allowed by the program. The request must use the base currency for the program.
ILLEGAL_RETAIL_TRANSACTION_ID	The retail transaction data specified does not match the organization's configured parameters.
INVALID_PIN	The PIN supplied in the request is not valid.
MISSING_PIN_ERROR	A PIN is required and was not provided in the request.
NO_PHYSICAL_CARD	The card is required to be present and it was not supplied (Card Swiped Flag = False).
REASON_CODE_REQUIRED	Request is missing the required reason code.

Issue Coupon

This request issues a coupon to a customer.

This message type cannot be used in a batch environment as it was designed for interactive use (that is, request-response).

Requirements/Restrictions

The <CardNumber> and <AwardAccountID> must be included in the request.

If both the <CardNumber> and <InstrumentID> (Serial Number) are included, both of them must be valid and for the same card.

If the physical card must be present as specified by the associated program, <CardSwiped> must equal true.

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.

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 an IssueCoupon 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
`<CurrencyID>`	The currency being used for the transaction.
`<TransactionID>`
`<UserID>`	POS User.
`<StoreID>`	Retail location where transaction is taking place.
`<RegisterID>`	POS register where transaction is taking place.
`<BusinessDate>`	Business date of the transaction (yyyy-mm-dd).
`<SequenceNumber>`	Sequential number for transaction assigned by POS.
`<Instrument>`
`<InstrumentID>`	This is the serial number of the card.
`<AuthenticationData>`	PIN.
`<CardNumber>`	(required) Card Number.
`<CardSwiped>`	Indicates whether the card was physically present (True) or not (False or empty)
`<AwardAccountID>`	(required) Award Account that will contain the coupon being issued.
`<RequestAmount>`
`<Amount>`	Amount of the coupon being issued.
<EffectiveDate>	Date the coupon is valid from.
`<ExpirationDate>`	Date the coupon is no longer valid.
`<Comments>`	User comments.
`<ReasonCode>`	ID code for the reason for issuing the coupon.
<IgnoreExpirationDate>	Indicates whether the expiration date of the account should be ignored.
<FranchiseeName>	(required) Name of the franchisee.
<IssueAwardCouponType>	Type of award to issue (E-Award or Entitlement Coupon).
<AnnivAwardType>	Type of anniversary award (Birthday, Signup or PromoAward).
<DealId>	Entitlement coupon deal id.

Example

When generating an IssueCoupon 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"?><Awards>  <AwardRequest Type="IssueCoupon">    <CurrencyID>USD</CurrencyID>    <TransactionID>      <UserID>WPL</UserID>      <StoreID><STORE_ID></StoreID>      <RegisterID><REGISTER_ID></RegisterID>      <BusinessDate>2009-02-20</BusinessDate>      <SequenceNumber>23456789</SequenceNumber>    </TransactionID>    <Instrument>      <InstrumentID><INSTRUMENT_ID></InstrumentID>      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>
    </Instrument>    <AwardAccountID><ACCOUNT_ID></AwardAccountID>    <RequestAmount>      <Amount>100</Amount>      <ExpirationDate>2015-12-31</ExpirationDate>    </RequestAmount>    <Comments>Issue Coupon Message</Comments>    <ReasonCode></ReasonCode>  </AwardRequest></Awards>

Batch Processing Errors

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

Error	Reasons
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.
ACCOUNT_NOT_FOUND	The account number specified in the request could not be found.
CARD_EXPIRED	There is an Expiration Date for the card and it is less than the current date.
CARD_INACTIVE	The card is not active (Active Flag = False).
CARD_NOT_FOUND	The card specified in the request could not be found.
CARD_NUMBER_REQUIRED	The card number was not provided.
COUPON_REQUEST_AMOUNT_INVALID	There was no amount or an invalid amount was specified in the request.
COUPON_REQUEST_DATE_INVALID	The Expiration Date has passed or is in an invalid format.
COUPON_REQUEST_NEGATIVE_AMOUNT_INVALID	The amount in the request is less than or equal to zero.
CURRENCY_EXCHANGE_RATE_NOT_FOUND	The exchange rate for the specified currency code was not found.
CURRENCY_ID_MISSING_IN_REQUEST	The `<CurrencyID>` XML tags are not included in the request message.
FOREIGN_CURRENCY_NOT_ALLOWED	Foreign currencies are not allowed by the program. The request must use the base currency for the program.
ILLEGAL_RETAIL_TRANSACTION_ID	The retail transaction data specified does not match the organization's configured parameters.
INVALID_PIN	The PIN supplied in the request is not valid.
MISSING_PIN_ERROR	A PIN is required and was not provided in the request.
NO_PHYSICAL_CARD	The card is required to be present and it was not supplied (Card Swiped Flag = False).
REASON_CODE_REQUIRED	Request is missing the required reason code.
RELOADS_NOT_PERMITTED	Reloads (Recharges) are not permitted by the program.

Void

This request voids or cancels a previous transaction. The transactions that can be voided are: Redeem Coupon, Automatic Redeem, and an Issue Coupon request unless it has been redeemed (individual or automatic).

Requirements/Restrictions

The <CardNumber>, <AwardAccountID>, and <AwardTransactionID> must be included in the request.

If both the <CardNumber> and <InstrumentID> (Serial Number) are included, both of them must be valid and for the same card.

If the physical card must be present as specified by the associated program, <CardSwiped> must equal true.

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.

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 Void 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
`<CurrencyID>`	(required) The currency being used for the transaction.
`<TransactionID>`
`<UserID>`	POS User.
`<StoreID>`	Retail location where transaction is taking place.
`<RegisterID>`	POS register where transaction is taking place.
`<BusinessDate>`	Business date of the transaction (yyyy-mm-dd).
`<SequenceNumber>`	Sequential number for transaction assigned by POS.
`<AwardTransactionID>`	(required) Transaction ID of the transaction being voided.
`<Instrument>`
`<InstrumentID>`	This is the serial number of the card.
`<AuthenticationData>`	PIN.
`<CardNumber>`	(required) Card Number.
`<CardSwiped>`	Indicates whether the card was physically present (True) or not (False or empty)
`<AwardAccountID>`	(required) Award Account against which the transaction being voided was processed.
`<Comments>`	User comments for the transaction detail.
`<ReasonCode>`	ID code for the reason for the automatic redemption.
<IgnoreExpirationDate>	Indicates whether the expiration date of the account should be ignored.
<FranchiseeName>	(required) Name of the franchisee.

Example

When generating an Void 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"?><Awards>  <AwardRequest Type="Void">    <CurrencyID>USD</CurrencyID>    <TransactionID>      <UserID><USERID></UserID>      <StoreID><STORE_ID></StoreID>      <RegisterID><REGISTER_ID></RegisterID>      <BusinessDate>2009-01-10</BusinessDate>      <SequenceNumber>23456789</SequenceNumber>      <AwardTransactionID><TRANS_ID></AwardTransactionID>    </TransactionID>    <Instrument>      <InstrumentID><INSTRUMENT_ID></InstrumentID>      <AuthenticationData><AUTH_DATA></AuthenticationData>      <CardNumber><CARD_NUMBER></CardNumber>      <CardSwiped>true</CardSwiped>    </Instrument>    <AwardAccountID><ACCOUNT_ID></AwardAccountID>
    <Comments>Special Comments</Comments>    <ReasonCode></ReasonCode>  </AwardRequest></Awards>

Batch Processing Errors

Error	Reasons
ACCOUNT_EXPIRED	There is an Expiry Date for the account and it is less than or equal to the current date.
ACCOUNT_NOT_FOUND	The account number specified in the request could not be found.
ACTIVATION_NOT_VOIDABLE_ WHEN_ACCT_HAS_ACTIVITY	The original activate transaction was not the last transaction performed on a coupon (excluding Inquiry transactions).
CAN_NOT_VOID_TRAN_TYPE	The original transaction is not a Redeem Coupon, Automatic Redeem, or an Issue Coupon. The transaction cannot be voided.
CARD_EXPIRED	There is an Expiration Date for the card and it is less than the current date.
CARD_INACTIVE	The card is not active (Active Flag = False).
CARD_NOT_FOUND	The card specified in the request could not be found.
CARD_NUMBER_REQUIRED	The card number was not provided.
ILLEGAL_RETAIL_TRANSACTION_ID	The retail transaction data specified does not match the organization's configured parameters.
INVALID_PIN	The PIN supplied in the request is not valid.
MISSING_PIN_ERROR	A PIN is required and was not provided in the request.
NO_PHYSICAL_CARD	The card is required to be present and it was not supplied (Card Swiped Flag = False).
ORIG_AWARD_TRAN_NOT_FOUND	The original award transaction cannot be found.
ORIGINAL_TRANSACTION_VOIDED	The original transaction has already been voided.
REASON_CODE_REQUIRED	Request is missing the required reason code.
VALID_ORIGINAL_TRAN_REQUIRED	The original Transaction ID was not included in the request.