Card Services Version 2.1

28 Card Services Version 2.1

This chapter provides the information necessary to send messages contained in Version 2.1 of the Card 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.

The URL for the Card Services WSDL is:

https://<servername>:<portNumber>/ws/v2_1/CardServices?wsdl

where <servername> is the name or address of the server The default port number is 443.

The information presented 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 2.1 of the Card Services API.

extendExpirationDate

string extendExpirationDate (
           string cardNumber,
           dateTime expirationDate,
           string updateUserId)
      throws RelateProcessingException

Variable	Required?	Description
cardNumber	required	Card number
expirationDate	required	New expiration date for the card
updateUserId	optional	ID of the POS user performing the action.

The extendExpirationDate method changes the expiration date for a card to a newdate.This method returns a string value.

getCardInquiryData

CardInquiryResponse getCardInquiryData (
                         string cardNumber,
                         boolean cardSwiped,
                         string authenticationData,
                         string currencyCode,
                         string transactionStoreId,
                         string transactionRegisterNumber,
                         dateTime transactionBusinessDate,
                         string transactionSequenceNumber,
                         string updateUserId)
    throws RelateProcessingException

Variable	Required?	Description
cardNumber	required	Card number.
cardSwiped	optional	Indicates whether the card was swiped.
authenticationData	optional	Authentication information.
currencyCode	required	ID for the currency.
transactionStoreId	optional	ID of the location where the transaction was performed.
transactionRegister Number	optional	Number of the register where the transaction was performed.
transactionBusiness Date	optional	Business date of the transaction.
transactionSequence Number	optional	Sequence number of the transaction.
updateUserId	optional	ID of the user who performed the transaction.

The getCardInquiry method retrieves account activity information for all accounts attached to the specified card.

This method returns a CardInquiryResponse class object.

Note:

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

updateCardToCustomerAssociations

string updateCardToCustomerAssociations (
        CardCustAssociationType[] cardCustAssociation,
        string cardNumber,
        string updateUserId,
        string securityUserId)
    throws RelateProcessingException

Variable	Required?	Description
cardCustAssociation	required	Array of customers to associate with the card.
cardNumber	required	Card number.
updateUserId	required	ID of the POS user performing the action.
securityUserId	required	ID of the Customer Engagement user performing the action.

The updateCardToCustomerAssociations method sets updates a card with a new set of customers with which to be associated.

This method returns a string value.

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 2.1 of the Card Services API.

AlternateKeyLookupType

For information about this class, see Introduction.

AwardProgramType

The getValue() function for the AwardProgramType class returns a string value.

AwardProgramType includes the following attribute:

Type	Attribute	Description
string	Id	Identifier for the award program.

CardCustAssociationType

The CardCustAssociationType class contains the following elements:

Type	Element	Description
string	CustomerID	ID of the customer.
string	Action	Possible actions are ASSOCIATE, DISASSOCIATE, and SET AS PRIMARY. Case-sensitive.
AlternateKeyLookupType[]	AlternateKey	Array of alternate keys for customer lookup.
RTPTransactionType	TransactionInfo	Information about the transaction in which the action is being performed.

CardInqAssocCustomer

The CardInqAssocCustomer class contains the following elements:

Type	Element	Description
string[]	CustomerID	Array of customer IDs.

CardInqAwardAccount

The CardInqAwardAccount class contains the following elements:

Type	Element	Description
string	AwardAccountId	Identifier for the award account inquired about.
AwardProgramType	awardProgram	Award program used.
CardInqCouponList	CouponList	A list of all the coupons associated with the award account.
CardInqAwardAccountActivityList	AwardAccountActivityList	A list of the activities performed on the award account.

CardInqAwardAccountActivity

The CardInqAwardAccountActivity class contains the following elements:

Type	Element	Description
string	TransactionType	Identifier for the type of transaction.
string	AwardTranId	Identifier for the transaction.
string	LocationId	Identifier for the location where the transaction was performed.
string	CreateUser	User who initiated the activity.
string	UpdateUser	User who updated the activity.
boolean	VoidFlag	Indicates whether the transaction was voided.
string	ErrorCode	Code representing error if activity resulted in an error.
string	Comments	User-entered comments.
date	BusinessDate	Business date for the transaction.
string	ReferencedTranId	ID for a transaction referred to by this transaction.
string	RetailTransactionId	The retail transaction ID (if any) associated with the activity.
dateTime	UpdateDate	Date and time the transaction was updated.
dateTime	ActivityDateTime	Date and time the transaction was performed.
decimal	ActivityAmount	The amount of the award.
string	OperatorId	ID of employee who handled the transaction.
string	WorkstationId	Identifier for the workstation where the transaction was performed.
decimal	RequestedAmount	Used in authorizations, the amount requested for authorization.
string	RequestedCurrencyCode	The currency of the amount in the request.
decimal	ExchangeRate	Exchange rate between the requested currency and the program currency.
string	CouponId	ID for the issued coupon.
string	ReasonCode	Reason code for the activity.
date	ExpirationDate	Expiration date.
string	SequenceNumber	Sequence number of the activity.

CardInqAwardAccountActivityList

The CardInqAwardAccountActivityList class contains the following elements:

Type	Element	Description
CardInqAwardAccountActivity[]	AwardAccountActivity	Array of activities performed on an award account.

CardInqAwardCoupon

The CardInqAwardCoupon class contains the following elements:

Type	Element	Description
decimal	Amount	Amount of the coupon.
date	ExpirationDate	The date on which the coupon expires.

The CardInqAwardCoupon class includes the following attribute:

Type	Attribute	Description
string[]	id	Award coupon ID.

CardInqCouponList

The CardInqCouponList class contains the following elements:

Type	Element	Description
CardInqAwardCoupon[]	Coupon	Array of award coupons.

The CardInqCouponList class includes the following attribute:

Type	Attribute	Description
string[]	Type	Type of award coupons in the list.

CardInqCustomer

The CardInqCustomer class contains the following elements:

Type	Element	Description
string	CustomerID	Identifier for the customer inquired about.

CardInqError

The CardInqError class contains the following elements:

Type	Element	Description
string	Code	Error code.
string	Description	Text describing the type of error.
string	FaultDetail	Details about the error, including debugging information.

CardInqInstrument

The CardInqInstrument class contains the following elements:

Type	Element	Description
string	CardNumber	Card number.
string	CardSerialNumber	Card serial number.
date	CardExpirationDate	Card expiration date.
CardInqLoyaltyAccount[]	LoyaltyAccount	Array of loyalty accounts associated with the card.
CardInqAwardAccount[]	AwardAccount	Array of award accounts associated with the card.

CardInqLoyaltyAccount

The CardInqLoyaltyAccount class contains the following elements:

Type	Element	Description
string	LoyaltyAccountID	ID for the loyalty account.
CardInqLoyaltyProgram	LoyaltyProgram	Loyalty program associated with the account.
CardInqLoyaltyProgramLevel	LoyaltyProgramLevel	The current level of the loyalty program to which the loyalty account belongs.
CardInqPointsBalance	PointsBalance	The current points balance for the account.
CardInqLoyaltyActivityList	LoyaltyActivityList	List of the Loyalty Account activities performed.

The CardInqLoyaltyAccount class includes the following attribute:

Type	Attribute	Description
string[]	TypeCode	The type of loyalty account.

CardInqLoyaltyActivity

The CardInqLoyaltyActivity class contains the following elements:

Type	Element	Description
string	TransactionType	Identifier for the transaction type.
decimal	NumPoints	Number of points involved in the activity.
boolean	PendingFlag	Indicates whether the points in the activity are escrow (1) or not (0).
string	AccountActivityId	Identifier for the activity.
string	LocationId	ID for the location where the activity was performed.
string	CreateUser	ID for the user who performed the activity.
string	UpdateUser	ID for the user who updated the activity.
boolean	VoidFlag	Indicates whether the activity has been voided.
decimal	EscrowPointsBalance	Escrow points balance for the account at the time of the activity.
decimal	EarnedPointsBalance	Earned points balance for the account at the time of the activity.
decimal	BonusPointsBalance	Bonus points total for the account at the time of the activity.
string	ErrorCode	Code representing error if activity resulted in an error.
string	Comments	User-added comments.
date	BusinessDate	Business date on which the activity occurred.
string	RuleName	The rule that governed the points in the activity.
string	ReferencedTranId	ID for the transaction referred to by this activity.
date	EarnDate	If the points in the activity are escrow (pending), the date when these points become earned.
string	RetailTransactionId	The retail transaction ID (if any) associated with the activity.
dateTime	UpdateDate	Date and time at which the activity was updated.
string	RequestedAmount	Amount of requested award.
string	RequestedCurrencyCode	Currency in which the award was requested.
string	ExchangeRate	Exchange rate between the requested currency and the organization’s base currency.
string	ConvertedAmount	Amount of the award converted to the organization’s base currency.

CardInqLoyaltyActivityList

The CardInqLoyaltyActivityList class contains the following elements:

Type	Element	Description
CardInqLoyaltyActivity[]	LoyaltyActivity	Array of loyalty activities.

CardInqLoyaltyProgram

The getValue() function for the CardInqLoyaltyProgram class returns a string value.

CardInqLoyaltyProgram includes the following attribute:

Type	Attribute	Description
string	Id	Identifier for the loyalty program.

CardInqLoyaltyProgramLevel

The getValue() function for the CardInqLoyaltyProgramLevel class returns a string value.

CardInqLoyaltyProgramLevel includes the following attribute:

Type	Attribute	Description
string	Id	Identifier for the loyalty program level.

CardInqPointsBalance

The CardInqPointsBalance class contains the following element:

Type	Element	Description
CardInqPointsEntry[]	Points	Array of points entries for the loyalty account.

CardInqPointsEntry

The getValue() function for the CardInqPointsEntry class returns a decimal value.

CardInqPointsEntry includes the following attribute:

Type	Attribute	Description
CardInqPoints	Type	Type of points in the entry.

CardInqResponseStatus

The CardInqResponseStatus class contains the following elements:

Type	Element	Description
dateTime	DateTime	Date and time of the inquiry.
CardInqError	Error	Error returned by the inquiry.

The CardInqResponseStatus class includes the following attribute:

Type	Attribute	Description
string	Type	Type of error.

CardInquiryResponse

The CardInquiryResponse class contains the following elements:

Type	Attribute	Description
CardInqResponseStatus	ResponseStatus	Status of the inquiry response.
CardInqInstrument	Instrument	Card information.
CardInqCustomer	Customer	Primary customer associated with the card.
CardInqAssocCustomer	OtherAssociated Customers	Other customer associated with the card.

Exception

The Exception class contains the following elements:

Type	Element	Description
string	message	Message associated with the exception.

RelateProcessingException

For a description of this class, see Introduction.

RTPTransactionType

The RTPTransactionType element contains the following elements:

Type	Element	Description
string	RTPTransactionID	ID of the transaction.
string	OperatorID	ID of the employee who performed the transaction.
string	LocationID	ID of the location where the transaction was performed.
string	TransactionDateTime	Date and time of the transaction.
string	DeviceID	ID of the device on which the transaction was performed.
string	BusinessDate	Business date of the transaction.
RTPAmountType	RTPAmount	Amount of the transaction.
string	CurrencyID	ID of the currency.
string	Amount	Amount applied to the currency.

RTPAmountType

The RTPAmountType element contains the following elements:

Type	Element	Description
string	CurrencyID	ID of the currency.
string	Amount	Amount applied to the currency.