Award Account Services, Version 1.0

21 Award Account Services, Version 1.0

This chapter provides the information necessary to send messages contained in Version 1.0 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/v1_0/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 1.0 of the Award Account Services API.

automaticRedeem

AwardResponseType automaticRedeem (
                 string awardAccountId,
                 AwardTransactionRequestInfo tranInfo,
                 AwardInstrumentData instrumentData,
                 string currencyId,
                 decimal amount,
                 string comments)
     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.

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.

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 CardInquiryResponseclass 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)
     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.

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.

issueCoupon

AwardResponseType issueCoupon (
                string awardAccountId,
                AwardTransactionRequestInfo tranInfo,
                AwardInstrumentData instrumentData,
                string currencyId,
                decimal amount,
                dateTime expirationDate,
                string comments)
     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.

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.

redeemCoupons

AwardResponseType redeemCoupons (
                 string awardAccountId,
                 AwardTransactionRequestInfo tranInfo,
                 AwardInstrumentData instrumentData,
                 string currencyId,
                 AwardCoupon[] couponList,
                 string comments)
     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.

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.

reverse

AwardResponseType reverse (
             string awardAccountId,
             AwardTransactionRequestInfo tranInfo,
             AwardInstrumentData instrumentData,
             string comments)
     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.

The reverse method cancels a previously performed award account activity.

This method returns an AwardResponseType class object

Classes

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

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.

awardTransactedAccount

The awardTransactedAccount class contains the following elements:

Type	Element	Description
String	accountId	Identifier for the award account used in the transaction.
AwardCoupon	couponBalances	Remaining balances on coupons used on the transaction.
AwardCoupon	transactedCoupons	Coupons used up in the transaction.

awardTransactionResult

The awardTransactionResult class contains the following elements:

Type	Element	Description
String	awardTransactionId	Identifier for the transaction.
awardTransactedAccount	transactedAccounts	Array of award accounts used in the transaction.
DateTime	transactionDateTime	Date and time the transaction occurred.

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.

RelateProcessingException

For a description of this class, see Introduction.