Award Account Services, Version 3.1

25 Award Account Services, Version 3.1

This chapter provides the information necessary to send messages contained in Version 3.1 of the Award Account Services API. Information can be obtained using the Web Service Description Language (WSDL) in conjunction with a Simple Object Access Protocol (SOAP), XML Schema, and various methods contained in the classes of the API to provide the web service described above.

The URL for the Award Account Services WSDL is:

https://<servername>:<portNumber>/ws/v3_1/AwardAccountServices?wsdl

where <servername> is the name or address of the server. For a cloud installation, the default port number is 443.

The information presented below describes the methods and classes.

The format of the method and any arguments is shown along with an explanation of what the method does and any other information that is necessary to use the method properly. If an argument is shown in dark blue, it is a class and the class name is a link to a description of the class and its attributes.

The class section shows the attributes of the classes along with an explanation of each attribute and when necessary, when they are used

Note:

Authentication is required. See Introduction for information on creating and implementing an authentication key

Methods

This section presents the methods used in Version 3.1 of the Award Account Services API.

automaticRedeem

AwardResponseType automaticRedeem (
                 string awardAccountId,
                 AwardTransactionRequestInfo tranInfo,
                 AwardInstrumentData instrumentData,
                 string currencyId,
                 decimal amount,
                 string comments,
                 string reasonCode,
                 boolean ignoreExpirationDate,
                 string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
awardAccountId	Optional	ID of the award account.
tranInfo	Optional	Information about the transaction requesting the redemption.
instrumentData	Optional	Data describing the instrument associated with the award account.
currencyId	Optional	ID code for the currency used in the redemption request.
amount	Optional	Amount of the redemption request.
comments	Optional	Additional comments.
reasonCode	Optional	Reason code for the redemption.
ignoreExpirationDate	Required	Indicates whether to ignore the expiration date on the card.
securityUserId	Required	ID of the Customer Engagement user performing the redemption.

The automaticRedeem function automatically redeems coupons issued to a customer for the required amounts. Coupon values are redeemed so that the coupons closest to expiration are redeemed first.

For example, say that a customer has three $10 coupons, which expire in August 2015, September 2015, and October 2015. The customer then purchases a shirt for $27. The automaticRedeem method will first apply the August 2015 coupon for $10 toward the cost, then the September 2015 coupon for $10, then the October 2015 coupon to the remaining $7. The first two coupons are now entirely redeemed and the October 2015 coupon still has $3 available to be redeemed.

Entitlement coupons cannot be redeemed through the automaticRedeem function.

This method returns an AwardResponseType object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

expireCoupons

AwardResponseType expireCoupons (
                 string awardAccountId,
                 AwardTransactionRequestInfo tranInfo,
                 AwardInstrumentData instrumentData,
                 string currencyId,
                 string[] couponList,
                 string comments,
                 string reasonCode,
                 string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
awardAccountId	Required	ID of the award account.
tranInfo	Optional	Information about the issuing transaction.
instrumentData	Required	Data describing the instrument associated with the award account.
currencyId	Required	ID code for the currency.
couponList	Required	The coupon ID(s) to expire.
comments	Optional	Additional comments.
reasonCode	Optional	Reason code for the redemption.
securityUserId	Required	ID of the Customer Engagement user issuing the coupon.

The expireCoupons method sets the expiration date for each coupon ID specified in the couponList to the previous date, rendering the coupon expired. The coupon ID can specify an e-award or an entitlement deal.

This method returns the AwardResponseType value.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

getAwardAccountHistory

CardInquiryResponse getAwardAccountHistory (
                        string cardNumber,
                        boolean cardSwiped,
                        string authenticationData,
                        string currencyCode,
                        dateTime historyStartDate,
                        dateTime historyEndDate,
                        string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
cardNumber	Optional	Card number associated with the award account.
cardSwiped	Required	Indicates whether card was swiped.
authenticationData	Optional	Authentication information.
currencyCode	Optional	ID code for the currency to be used.
historyStartDate	Optional	Start date for the history search range.
historyEndDate	Optional	End date for the history search range.
securityUserId	Required	ID of the Customer Engagement user performing the request.

The getAwardAccountHistory method retrieves award account activity information for all award accounts attached to the specified card. This method also returns detail information for each award account and the card.

If there is no activity for an account, the account and card information is returned.

This method returns a CardInquiryResponse class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

inquiry

AwardResponseType inquiry (
            AwardTransactionRequestInfo tranInfo,
            AwardInstrumentData instrumentData,
            string currencyId,
            boolean ignoreExpirationDate,
            string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
tranInfo	Optional	Information about the transaction making the inquiry.
instrumentData	Optional	Data describing the instrument associated with the award account.
currencyId	Optional	ID code for the currency.
ignoreExpirationDate	Required	Indicates whether to ignore the expiration date on the card.
securityUserID	Required	ID of the Customer Engagement user performing the inquiry.

The inquiry method retrieves award transaction information for all transactions that match all search criteria included in the tranInfo, instrumentData, and currencyId variables.

This method returns an AwardResponseType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

issueCoupon

AwardResponseType issueCoupon (
                string awardAccountId,
                AwardTransactionRequestInfo tranInfo,
                AwardInstrumentData instrumentData,
                string currencyId,
                decimal amount,
                dateTime expirationDate,
                string comments,
                string reasonCode,
                string couponPrefix,
                IssueAwardCouponType couponType,
                long dealId)
                string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
awardAccountId	Required	ID of the award account.
tranInfo	Optional	Information about the issuing transaction.
instrumentData	Required	Data describing the instrument associated with the award account.
currencyId	Optional	ID code for the currency.
amount	Optional	Amount of the coupon.
expirationDate	Optional	Expiration date for the coupon.
comments	Optional	Additional comments.
reasonCode	Optional	Reason code for the redemption.
couponPrefix	Optional	Prefix for the coupon.
couponType	Optional	Indicates whether the coupon is an e-award or an entitlement coupon.
dealId	Optional	ID of the deal.
securityUserId	Required	ID of the Customer Engagement user issuing the coupon.

The issueCoupon method requests that a transaction issue an award coupon to a customer through an award account.This method returns an AwardResponseType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

redeemCoupons

AwardResponseType redeemCoupons (
                 string awardAccountId,
                 AwardTransactionRequestInfo tranInfo,
                 AwardInstrumentData instrumentData,
                 string currencyId,
                 AwardCoupon[] couponList,
                 string comments,
                 string reasonCode,
                 boolean ignoreExpirationDate,
                 string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
awardAccountId	Optional	ID of the award account.
tranInfo	Optional	Information about the transaction.
instrumentData	Optional	Data describing the instrument associated with the award account.
currencyId	Optional	ID code for the currency.
couponList	Optional	Array of coupons being submitted for redemptions.
comments	Optional	Additional comments.
reasonCode	Optional	Reason code for the redemption.
ignoreExpirationDate	Required	Indicates whether to ignore the expiration date on the card.
securityUserId	Required	ID of the Customer Engagement user performing the redemption.

The redeemCoupons method submits a list of award coupons for redemption in a transaction. These award coupons are issued to customers as part of an award account.

This method returns an AwardResponseType class object.

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

reverse

AwardResponseType reverse (
             string awardAccountId,
             AwardTransactionRequestInfo tranInfo,
             AwardInstrumentData instrumentData,
             string comments,
             string reasonCode,
             string securityUserId)
     throws RelateProcessingException

Variable	Required	Description
awardAccountId	Optional	ID of the award account.
tranInfo	Optional	Information about the transaction being reversed.
instrumentData	Optional	Data describing the instrument associated with the award account.
comments	Optional	Additional comments.
reasonCode	Optional	Reason code for the redemption.
securityUserID	Required	ID of the Customer Engagement user performing the reverse.

The reverse method cancels a previously performed award account activity.

This method returns an AwardResponseType class object

Note:

The securityUserId provided within this message must be assigned the proper Security Group permission for this operation to be performed successfully.

Classes

This section presents the classes used in Version 3.1 of the Award Account Services API.

AwardAccountType

The AwardAccountType class includes the following elements:

Type	Element	Description
string	AwardAccountID	Identifier for the award account.
AwardRespProgramType	awardProgram	The name of the award program.
CouponListType[]	CouponList	The list of e-award coupons.
EntitlementCouponListType[]	EntitlementCouponList	The list of entitlement coupons.

AwardCoupon

The AwardCoupon class contains the following elements.

Type	Element	Description
Decimal	amount	Balance remaining on the coupon.
String	couponId	Identifier for the coupon.
DateTime	expirationDate	Date and time when the coupon expires.

AwardInstrumentData

The AwardInstrumentData class contains the following elements

Type	Element	Description
String	authenticationData	PIN number.
String	cardNumber	Card number.
Boolean	cardSwiped	Whether the card was swiped.

AwardProgramType

For a description of this class, see "AwardProgramType" in Chapter 29.

AwardResponseType

The AwardResponseType class includes the following elements:

Type	Element	Description
ResponseStatusType	AwardAccountID	Date and time, plus response status.
AwardAccountType	awardProgram	Information on the award program.

AwardRespProgramType

The AwardRespProgramType class contains the following attribute

Type	Element	Description
String	ID	Identifier for the award program.

AwardTransactionRequestInfo

The awardTransactionRequestInfo class contains the following elements:

Type	Element	Description
Date	businessDate	Date of the transaction.
String	awardTranId	Identifier for the transaction.
String	registerId	Identifier for the register that processed the transaction.
String	sequenceNumber	Identifier for the sequence number of the transaction.
String	userId	User who performed the transaction.
String	storeId	Location where the transaction occurred.

CardInquiryResponse

For a description of this class, see Introduction.

CouponListType

The CouponListType class includes the following element:

Type	Element	Description
CouponType	Coupon	Information on each e-award coupon.

The CouponListType class includes the following attribute:

Type	Attribute	Description
String	Type	The type of e-award coupons included in the list, such as balance amounts.

CouponType

The CouponType class includes the following elements:

Type	Element	Description
String	Amount	The amount of the e-award coupon.
String	ExpirationDate	The expiration date of the e-award coupon.

The CouponType class includes the following attribute:

Type	Attribute	Description
String	ID	Identifier of the generated coupon.

EntitlementCouponListType

The EntitlementCouponListType class includes the following element:

Type	Element	Description
EntitlementCouponType[]	EntitlementCoupon	Information on each entitlement coupon.

The EntitlementCouponListType class includes the following attribute:

Type	Attribute	Description
String	Type	The type of entitlement coupons included in the list, such as available coupons.

EntitlementCouponType

The EntitlementCouponType class includes the following elements:

Type	Element	Description
int	RedeemCount	The number of times the entitlement deal has been redeemed.
String	EffectiveDate	The date the entitlement deal is valid from.
String	ExpiryDate	The date the entitlement deal expires.
Boolean	Redeemable	Indicates whether the entitlement deal is redeemable
EntitlementType	EntitlementDeal	Information about the entitlement deal type.

EntitlementDealType

The EntitlementDealType class includes the following elements:

Type	Element	Description
String	Name	The name of the entitlement deal.
String	Description	The description of the entitlement deal.
Boolean	UnlimitedRedeemFlag	Indicates whether redemption of the entitlement deal is unlimited (true) or is limited (false).
Boolean	ActiveFlag	Indicates whether the entitlement deal is active (true) or inactive (false).
String	MaxRedeemCount	Indicates the maximum number of times theentitlement deal can be redeemed by the customer.
ReferencedDealType	Deal	Information about the entitlement deal type included in the program.

ReferencedDealType

The ReferencedDealType class includes the following elements:

Type	Element	Description
String	DealId	Identifier for the deal.
String	DealName	Name of the deal.
String	DealType	Type of deal.
String	Comments	Any comments defined for the deal.
String	ExternalDealId	External identifier of the deal.

ResponseStatusType

The ResponseStatusType class includes the following elements:

Type	Element	Description
String	AwardTransactionID	Identifier for the transaction.
String	DateTime	The date and time when the response was generated.
ErrorType	Error	The type of error that occurred.

The ResponseStatusType class includes the following attribute:

Type	Attribute	Description
String	Status	Indicates whether the response was processed successfully (OK).

Exception

For a description of this class, see Introduction.

RelateProcessingException

For a description of this class, see Introduction.