Appendix B - Suggested Element Credit Card Implementation

Element Credit Card tags cannot be used with the standard credit card tags. They are mutually exclusive.

Post anElementAccountSetuptransaction that includes the non-sensitive information gathered from the customer about their credit card. Along with a URL for the element session to return the user to and append the transaction results. Redirect the user to theElementSetupUrlreturned in the results and save/note theElementSetupIdfor later use. The returned session will be valid for 5 minutes.
On the return URL page “scrape” the document location to obtain theHostedPaymentStatusand check if it is set to “Cancelled”. If it is not “Cancelled” then scrape for the ExpressResponseCode. If theExpressResponsecode is “0” then the payment account creation was successful. PaymentAccountId is also available if you do not want to perform andElementSetupQuerytransaction next, however you will have to construct theCreditCardelement instead of receiving it from Eclipse.
Perform anElementSetupQueryusing the ElementSetupId returned in theElementAccountSetupResponse.If an Element payment account was created for that Element session aCreditCardelement and sub-elements will be returned (Note the new sub-elementElementPaymentAccountId). You must now take thisCreditCardelement and use it in 3 possible ways.

Associate the card to:

A customer by including the customer’s current cards as well as the new card in anEntityUpdateSubmit.
A contact by including the contact’s current cards as well as the new card in anContactUpdateSubmit.
An order by including theCreditCardin aSalesOrderSubmit. This card is now associated to this order and may not be added to a different order, a customer, nor a contact.

Note:The only updatable elements of an Element CreditCard are:CardHolder,ExpirationDate,StreetAddress, andPostalCode. The new XML element,ElementPaymentAccountIdis now required for all CreditCard XML blocks.

ElementAccountSetup

General

Purpose	This transaction is used to set up an Element payment account card capture session. A URL will be returned that should be used in an iframe or separate web page for the end user to enter their card information.
Request/Response	Request
Corresponding Transaction Tag	ElementAccountSetupResponse
Secure Transaction?	Yes
Security Details	Data will only be returned if the requestor’s login data is valid.

Field Summary

Security			(Required) The standardSecuritytag. It can contain either aLogintag or aSession IDtag.
	Login*		(Required) For the login type ofSecuritytag.
		LoginID	(Required) This is the login for the requesting user.
		Password	(Required) This is the password for the requesting user.
	SessionID*		(Required) Alternative toLogintag. You can use a pre-assigned session ID may be used.
ElementAccountSetupData			(Required)Session setup tag.
	CardHolder		(Required)The name on the credit card
	StreetAddress		(Required)Street address of the cardholder
	PostalCode		(Required)ZIP code of the card holder
	ReturnUrl		The URL that the user should be automatically redirected to after the Element session has been completed (successfully or not). Element will append parameters and values to this URL. Important parameters are: HostedPaymentStatus (if this is set to “Cancelled” then the user cancelled the card payment account creation), ExpressResponseCode (if this is not “0” then there was an error setting up the payment account), and PaymentAccountID is also available if you do not want to perform an ElementSetupQuery for this session.

* One or the other of theLoginandSessionIDtags is required

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE IDMS-XML SYSTEM "http://www.eclipseinc.com/dtd/IDMS-XML.dtd">

<IDMS-XML>

<Login>

<LoginID>LOGIN</LoginID>

<Password>PASSWORD</Password>

</Login>

</Security>

<CardHolder>John Q. Cardholder</CardHolder>

<StreetAddress>1948 Eclipse St.</StreetAddress>

<ReturnUrl>http://example.com/</ReturnUrl>

</ElementAccountSetupData>

</ElementAccountSetup>

</IDMS-XML>

ElementAccountSetupResponse

General

Purpose	A URL will be returned that should be used in an iframe or separate web page for the end user to enter their card information. A setup ID is also returned if you cannot scrape the forward URL for the paymentAccount and need to do an ElementSetupQuery. Important: If a payment account is successfully created from this Element session, the resulting payment account ID must be used in a ContactUpdateSubmit,ContactNewSubmit,EntityUpdateSubmit,EntityNewSubmit,SalesOrderSubmit, orInvoiceSubmit. Using the payment account ID ensures that the payment account is associated to a contact, customer, or order. Any payment account not associated to an Eclipse entity is considered orphaned. Customers are charged for each payment account created so keeping track of any payment accounts created is vital.
Request/Response	Response
Corresponding Transaction Tag	ElementAccountSetup
Secure Transaction?	Yes
Security Details	Data will only be returned if the requestor’s login data is valid.

Field Summary

SessionID			The assigned session ID
ElementSetupURL			The URL to direct the user to in order for them to enter their sensitive credit card information.
ElementSetupId			The Element setup session GUID
StatusResult*			(Required)This tag describes the status of the response side of this transaction
	(Attributes)		The following are the attributes for this tag
		SuccessID*	(Required)Was the transaction successful? Valid choices: “Yes” or “No”
	Description		(Required)Free-form text field describing the status
	ErrorMessageList**		A list of any errors encountered in the transaction.
		ErrorMessage	(Required)Description specific errors encountered are given in one or more of these tags here.

**ErrorMessageListis required, however, if there are any errors, i.e., whenSuccessis “No”

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE IDMS-XML SYSTEM "http://www.eclipseinc.com/dtd/IDMS-XML.dtd">

<IDMS-XML>

<ElementSetupUrl>https://testtransaction.hostedpayments.com/?TransactionSetupID=AC3F0F84-97FC-4276-ADA2-A8EA4116872D</ElementSetupUrl>

<Description>Element PASS Account session setup successfully.</Description>

</StatusResult>

</ElementAccountSetupResponse>

</IDMS-XML>

ElementSetupQuery

General

Purpose	This transaction queries the Element session using the ElementSetupId.
Request/Response	Request
Corresponding Transaction Tag	ElementSetupQueryResponse
Secure Transaction?	Yes
Security Details	Data will only be returned if the requestor’s login data is valid.

Field Summary

Security			(Required) The standardSecuritytag. It can contain either aLogintag or aSession IDtag.
	Login*		(Required) For the login type ofSecuritytag.
		LoginID	(Required) This is the login for the requesting user.
		Password	(Required) This is the password for the requesting user.
	SessionID*		(Required) Alternative toLogintag. You can use a pre-assigned session ID may be used.
ElementSetupID			(Required)The Element session GUID returned in theElementAccountSetupResponse.
	CardHolder		(Required)The name on the credit card

* One or the other of theLoginandSessionIDtags is required

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE IDMS-XML SYSTEM "http://www.eclipseinc.com/dtd/IDMS-XML.dtd">

<IDMS-XML>

<Login>

<LoginID>LOGIN</LoginID>

<Password>PASSWORD</Password>

</Login>

</Security>

<ElementSetupId>AC3F0F84-97FC-4276-ADA2-A8EA4116872D

</ElementSetupId>

</ElementSetupQuery>

</IDMS-XML>

ElementSetupQueryResponse

General

Purpose	This transaction will return a credit card if a payment account was set up in the Element session.
Request/Response	Response
Corresponding Transaction Tag	ElementSetupQuery
Secure Transaction?	Yes
Security Details	Data will only be returned if the requestor’s login data is valid.

Field Summary

SessionID				The assigned session ID.
	CreditCard			This is the Credit Card tag
	CreditCardType			(Required)Card Brand
	CreditCardNumber			(Required)The last 4 digits of the credit card. Full PANs are no longer available with Element.
	ExpirationDate			(Required)Expiration Date.
		Date		(Required) Expiration Date of the card.
	CardHolder			(Required)Name on the credit card.
	StreetAddress			(Required)Billing Address of card.
	PostalCode			(Required)Billing ZIP/Postal code of card.
	ElementPaymentAccountID			(Required)This is the payment account GUID that identifies this card.
	StatusResult			(Required)This tag describes the status of the response side of this transaction.
		(Attributes)		The following are the attributes for this tag.
			Success	Was the transaction successful?Valid choices: “Yes” or “No”
	Description			(Required)Free-form text field describing the status.
		ErrorMessageList**		A list of any errors encountered in the transaction.
			ErrorMessage	(Required)Description specific errors encountered are given in one or more of these tags here.

**ErrorMessageListis required, however, if there are any errors, i.e., whenSuccessis “No”

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE IDMS-XML SYSTEM "http://www.eclipseinc.com/dtd/IDMS-XML.dtd">

<IDMS-XML>

</ExpirationDate>

<CardHolder>John Q. Cardholder</CardHolder>

<StreetAddress>1948 Eclipse St.</StreetAddress>

</CreditCard>

<Description>Element PASS Account session setup successfully.</Description>

</StatusResult>

</ElementSetupQueryResponse>

</IDMS-XML>