29 Card Services Version 3.0

This chapter provides the information necessary to send messages contained in Version 3.0 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/v3_0/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. SeeIntroduction for information on creating and implementing an authentication key.

Methods

This section presents the methods used in Version 3.0 of the Card Services API.

extendExpirationDate

string extendExpirationDate (
           string cardNumber,
           dateTime expirationDate,
           string updateUserId,
           string securityUserId)
      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.
securityUserId	required	ID of the Customer Engagement user performing the action.

The extendExpirationDate method changes the expiration date for a card to a newdate.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.

getCardInquiryData

CardInquiryResponse getCardInquiryData (
                         string cardNumber,
                         boolean cardSwiped,
                         string authenticationData,
                         string currencyCode,
                         string transactionStoreId,
                         string transactionRegisterNumber,
                         dateTime transactionBusinessDate,
                         string transactionSequenceNumber,
                         string updateUserId,
                         string securityUserId)
    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 POS user making the request
securityUserId	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 securityUserId 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.

updateCustomerCardsInquiryData

CardInquiryResponse[] getCustomerCardsInquiryData(                         string customerId,                         AlterKeyLookupType altKey,                         string cardNumber,                         boolean cardSwiped,                         string authenticationData,                         string currencyCode,                         string transactionStoreId,                         string transactionRegisterNumber,                         dateTime transactionBusinessDate,                         string transactionSequenceNumber,                         string updateUserId,                         string securityUserId)throws RelateProcessingException

Variable	Required?	Description
customerId	optional	ID of the customer
altKey	optional	Array of alternate keys for the customer.
cardNumber	optional	Card number. Note: customerId, altKey, or cardNumber is required
cardSwiped	required	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.
transactionRegisterNumber	optional	Number of the register where the transaction was performed.
transactionBusinessDate	optional	Business date of the transaction.
transactionSequenceNumber	optional	Sequence number of the transaction.
updateUserId	optional	ID of the POS user making the request.
securityUserId	required	ID of the Customer Engagement user making the request.

The getCustomerCardsInquiryData method retrieves account activity information for all accounts assigned to a customer.

This method returns a list of CardInquiryResponse class objects.

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.0 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.
string	ReasonCode	Code identifying the reason for the activity.
string	ExpirationDate	Expiration date for the award account.
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.

CardInqEntitlementAccount

The CCardInqEntitlementAccount class contains the following elements:

Type	Element	Description
string	EntitlementAccountID	ID of the entitlement account.
EntitlementProgramType	EntitlementProgram	Entitlement program associated with the account.
EntitlementDealListType	EntitlementDeals	Deprecated.
EntitlementAccountActivityListType	EntitlementAccountActivityList	Deprecated.

CardInqError

The CardInqError class contains the following elements:

Type	Element	Description
string	CardNumber	Card number of the card.
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.
AttributeResponseType[]	Attribute	Array of attributes assigned to the card.
CardInqLoyaltyAccount[]	LoyaltyAccount	Array of loyalty accounts associated with the card.
CardInqAwardAccount[]	AwardAccount	Array of award accounts associated with the card.
CardInqTenderAccount	TenderAccount	Tender account 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.

CardInqTenderAccount

The CardInqResponseStatus class contains the following elements:

Type	Element	Description
string	TenderAccountID	ID of the tender account.
string	AccountStatusCode	Code identifying the status of the account.
TenderBalanceType	Balance	Balance on the account.
string	ExpirationDate	Expiration date of the account.
string	EffectiveDate	Date on which the account is first effective.
TenderProgramType	Program	Program with which the account is associated.
CardInqTenderAccountActivityListType	TenderAccountActivity List	Actions performed on the account.
string	ReasonCode	Code identifying the reason for the activity.
string	FranchiseeID	ID of the franchisee associated with the activity.
string	CardSwiped	Indicates whether the card was.
string	RtlTransSeq	Sequence number of the activity.

CardInqTenderAccountActivityListType

The CardInqTenderAccountActivityListType class contains the following elements:

Type	Attribute	Description
CardInqTenderAccountActivityListType	TenderAccountActivity	Array of activities on the tender account.

CardInqTenderAccountActivityType

The CardInqTenderAccountActivityType class contains the following elements:

Type	Element	Description
string	TransactionType	Type of transaction.
string	TenderTranId	ID of the transaction.
string	LocationId	ID of the location.
string	CreateUser	ID of the user who created/performed the transaction.
string	UpdateUser	ID of the user who last updated the transaction.
string	VoidFlag	Indicates whether the transaction was voided.
string	CardSwipedFlag	Indicates whether the card was swiped.
string	BusinessDate	Business date of the transaction.
string	ReferencedTranId	ID of the transaction referred to by the transaction.
string	RetailTransactionId	ID of the transaction in the POS.
string	UpdateDate	Date on which the transaction was last updated.
string	ActivityDateTime	Date and time of the activity.
string	ActivityAmount	Amount of the activity.
string	OperatorId	POS ID of the use who performed the transaction.
string	WorkstationId	ID of the workstation were the activity was performed.
string	RequestedAmount	Amount requested by the activity.
string	RequestedCurrencyCode	Code identifying the currency used in the amount request.
string	ExchangeRate	Exchange rate between the request currency and the currency used in the transaction.
string	ReasonCode	Code identifying the reason for the activity.
string	ErrorCode	Code identifying an error associated with the activity.
string	Comments	Comments on the activity.
date	ExpirationDate	Date on which the activity expires.
string	SequenceNumber	Sequence number of the activity.
string	FranchiseeId	ID of the franchisee associated with the activity.

CardInqTypeAttribute

The CardInqTypeAttribute class contains the following elements:

Type	Attribute	Description
string	AttrName	Name of the attribute.
string	AttrDataType	Data type of the attribute.
string	AttrValue	Value of the attribute.

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.
PageResultType	PageResultType	Paged result information.

The CardInquiryResponse class includes the following attributes:

Type	Attribute	Description
int	startIndex	Number of the record starting the page.
boolean	morePages	Indicates whether there are more pages to the response.
int	pageSize	Number of records in the page.

EntitlementProgramType

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

The EntitlementProgramType class includes the following attribute:

Type	Attribute	Description
string	Id	Identifier for the entitlement program.

Exception

The Exception class contains the following elements:

Type	Element	Description
string	message	Message associated with the exception.

PageResultType

The PageResultType class contains the following elements:

Type	Element	Description
string	StartIndex	ID of the first record in the page.
string	MorePages	Indicates whether there are more pages.
string	PageSize	Number of records in the page.

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.

TenderBalanceType

The TenderBalanceType element contains the following elements:

Type	Element	Description
string	Amount	Balance amount.
string	Currency	ID of the currency used for the balance.

TenderProgramType

The TenderProgramType element contains no elements.

The TenderProgramType class includes the following attributes:

Type	Attribute	Description
string	Id	ID of the tender program.
string	Name	Name of the tender program.
string	Rechargeable	Indicates whether the cards in the program can be recharged.