You are on page 1of 118

Hosted Checkout

TM

for eCommerce
Integration Guide

With Integrated MToken
TM
Technology







03.26.2014

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 2014 Mercury

Hosted Checkout for eCommerce Integration Guide
Disclaimer, Terms of Use and Compliance Representations

Disclaimer
This Hosted Checkout for eCommerce Integration Guide and all specifications and documentation contained herein
or provided to you hereunder (the Specifications) are licensed by Mercury Payment Systems, LLC (Mercury) on
an AS IS basis. No representations or warranties are expressed or implied, including, but not limited to,
warranties of suitability, quality, merchantability, or fitness for a particular purpose (irrespective of any course of
dealing, custom or usage of trade), and all such warranties are expressly and specifically disclaimed. Mercury shall
have no liability or responsibility to you or any other person or entity with respect to any liability, loss, or damage,
including lost profits whether foreseeable or not, or other obligation for any cause whatsoever, caused or alleged
to be caused directly or indirectly by the Specifications. Use of the Specifications signifies agreement with the
disclaimer set forth in this paragraph and the below license and restricted use terms and conditions.
Ownership and Restricted Terms of Use
Ownership of all Specifications, related documentation and all intellectual property rights therein and thereto shall
remain at all times with Mercury. All rights not expressly granted to you herein are reserved to Mercury. Mercury
grants you the right to use the Specification for the sole purpose of transmitting transactions directly to Mercury
from a merchant transaction originating device. Under no circumstances may you reverse engineer, translate, re-
direct, emulate, disseminate to other entities, decompile, adapt, or disassemble the information contained in the
Specifications nor shall you attempt to create source code/object code to emulate the Mercury Platform. You
agree that the Specifications and the printed materials and documentation that accompany these Specifications
are the confidential information of Mercury and may not be used except as otherwise expressly permitted herein.
Compliance Representations
You represent, warrant and agree:
To comply with the card brand operating regulations and all applicable PCI Data Security Standards (PCI
DSS) and Payment Application Data Security Standards (PA-DSS) and all requirements applicable to the
distribution and use of these Specifications, Mercury products, and your payment application.
To comply with all applicable federal, state and local laws, rules and regulations, including those related
or pertaining to privacy and truncating and masking cardholder account information and data.
To follow and abide by this integration guide and any modifications made to same from time to time by
Mercury. The most recent version of this integration guide can be obtained from a Mercury Developer
integrations analyst by calling 800-846-4472, Ext 1808.
To distribute and otherwise make available integration upgrades or modifications made by Mercury to
your reseller and merchant base utilizing any Mercury product integrated by you or your payment
application.
Any use of your point of sale system or environment to store, process or transmit cardholder data, places that
point of sale system and environment within full scope of the PA-DSS. You agree to comply with PCI DSS and, if
your point of sale system or environment engages in any of the above activities, to ensure that the point of sale
system and environment meets all PA-DSS requirements.
By your use of these Specifications, you warrant, represent and certify your agreement to the above terms and
conditions and that your payment application is compliant and adheres to the above requirements and that future
versions of your payment application will continue to comply and adhere with these requirements.



2014 Mercury Payment Systems, LLC - all rights reserved.


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 2014 Mercury

Document Version History
Version Date Description
03.26.2014 March 2014 Corrected comment syntax in XML examples
01.07.2014 January 2014 Added information on how many time a Gift card may be reloaded per day.
12.19.2013 12/19/2013 Figure 8: Removed N/A on iFrame from ReturnCodes 102 and 104, added
ReturnCode and ReturnMessage 105, and added Note emphasizing the
importance of return codes and messages.
Figure 15: Corrected description of the ReturnMethod to read CardID (not
PaymentID)
Updated the Gift section on Using the Three-Digit Card Verification Value to
reflect changes in the default options. There is only one option now: validate
CVV data if supplied.
11.13.2013 11/13/2013 Updated the CSS to include version 4.0.1.254 of the whitelist
Revised section, Using Card Security Codes and Address Verification Data
10.01.2013 10/1/2013 Added missing parameters to table for Credit Response-Return Values:
o Authorized Amount
o Gratuity Amount
o Purchase Amount
09.11.2013 09/11/2013 Added missing table for Production and Development-Test Gift/Prepaid
Servers
Changed incorrect references:
o Incorrect CVVResult to correct CvvResult
o Incorrect TransDateTime to correct TransPostTime
08.08.2013 08/07/2013 Re-organized the guide
Added sections:
o Overview of the Integration Process
o Appendix 4: CSS Functionality
Updated sections:
o Special Considerations for eCommerce Solutions
o MercuryStand-In
TM
Authorization
o Protection Against Duplicate Transactions
o Handling Transaction Timeouts
o Using Card Security Codes (CVV) and Address Verification Data (AVS)
o Appendix 1: MercuryGift
TM
Card Integration
05.23.2013 05/23/2013 Corrected XML example request changed <Track2> to <Track>
05.06.2013 05/06/2013 MerchantID changed to 013163015566916
Updated Mercury Stand-In Authorizations section
02.26.2013 02/26/2013 Minor text and format changes.
02.19.2013 02/19/2013 Re-designed document format.
Added Table of Contents, Table of Figures, and List of Acronyms.
Updated content.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 2014 Mercury

Application Updates
Version Date Description
4.0 08/2013 CSS support has been added, which allows a developer to upload a CSS
(cascading style sheet) to Mercurys server for each merchant site. This can be
used to replace the customization through the IntializePayment parameters, and
provides greater flexibility in designing the HostedCheckout page:
UploadCSS: Allows developer to upload a CSS for each merchant site.
DownloadCSS: Allows developer to download a previously uploaded CSS for
editing.
RemoveCSS: Allows developer to remove an uploaded CSS.
Additional changes:
Security Logo: The logo can be enabled/disabled. Values are on and off.
Default is off.
CVV: Ability to disable CVV on all pages via API. Allows the developer to
enable/disable the CVV on the HostedCheckout page. Values are on and off.
Default is on.
AVS Configuration for eCommerce via API: Allows a developer to
enable/disable address and zip code fields on the HostedCheckout page.
Values are on, zip, and off. Default is off.
3.7 10/10/2012
The following parameters have been deprecated. Parameters are still available in
the API but passing a value will not change the behavior.
SecurityLogo
SubmitButtonDefaultImageUrl
SubmitButtonHoverImageUrl
CancelButtonDefaultImageUrl
CancelButtonHoverImageUrl
AcknowledgePayment and AcknowledgeCardInfo calls have been deprecated
AcknowledgePayment and AcknowledgeCardInfo calls are no longer needed to
expire the PaymentID or CardID. The PaymentID and CardID will expire
automatically 20 minutes after generated.
Increase in iFrame size to accommodate PageTimeoutIndicator on largest browser
font.
iFrame size must be increased to 600 X 600 if FontSize = large
iFrame size must be increased to 550 X 500 if FontSize = medium.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 5 of 118
2014 Mercury

Table of Contents
Introduction to Mercury HostedCheckout ......................................................................................................... 8
Overview of the Integration Process ...................................................................................................................... 8
Integration: Three Step Transaction Process ........................................................................................................ 10
Overview............................................................................................................................................................... 10
Step 1: Initiate the Payment Process .................................................................................................................... 11
Step 2: Display the Mercury HostedCheckout Page ............................................................................................. 16
Step 3: Verify the Payment ................................................................................................................................... 19
CARDINFO ............................................................................................................................................................ 23
Step 1: Initiate the CardInfo Process .................................................................................................................... 23
Step 2: Display the Mercury CardInfo Page .......................................................................................................... 27
Step 3: Verify the CardInfo ................................................................................................................................... 31
Tokenization (MToken) ..................................................................................................................................... 33
General Overview ................................................................................................................................................. 33
MercuryPay
TM
MToken Specifications .................................................................................................................. 33
Subsequent Token Transaction Calls using Transaction Web Service .................................................................. 34
CreditResponse - Returned Values ....................................................................................................................... 44
Special Considerations for eCommerce Solutions ................................................................................................ 45
eCommerce Card Data Storage Using MToken .................................................................................................... 45
Required Transactions .......................................................................................................................................... 45
<Memo Tag> - Software Product and Version ..................................................................................................... 45
CVV and AVS data ................................................................................................................................................. 45
eCommerce Website Requirements .................................................................................................................... 45
eCommerce Best Practices ................................................................................................................................... 46
Handling Errors in eCommerce Transactions ....................................................................................................... 47
Additional Processing Features ............................................................................................................................ 49
MercuryStand-In
TM
Authorization ........................................................................................................................ 49
Protection Against Duplicate Transactions........................................................................................................... 52
Handling Transaction Time-Outs .......................................................................................................................... 53
PrePaid Partial Authorization and Real-Time Reversal Support ........................................................................... 53
Corporate Card Support: Level II data Tax and CustomerCode ......................................................................... 54
Using Card Security Codes (CVV) and Address Verification Data (AVS) ............................................................... 54
A P P E N D I C E S ...................................................................................................................................... 59
Appendix 1: MercuryGift Card Integration ........................................................................................................ 60
Appendix 2: HostedCheckout Development and Production URLs ....................................................................... 84
Appendix 3: Hosted Checkout Process Flows ....................................................................................................... 85
APPENDIX 4: CSS Functionality ............................................................................................................................ 87
Input Parameters to CssUploadRequest Method ................................................................................................. 87
Input Parameters to CssDownloadRequest Method ............................................................................................ 88
Input Parameters to CssRemoveRequest Method ............................................................................................... 89
Mercury CSS White List Rules ............................................................................................................................... 90
Appendix 5: List of Acronyms ............................................................................................................................. 118


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 6 of 118
2014 Mercury

Table of Figures
Figure 1. Input Parameters to InitializePayment Method ........................................................................................... 14
Figure 2. Return Parameters from InitializePayment Method .................................................................................... 15
Figure 3. C# Code Example: InitializePayment Web Method ...................................................................................... 16
Figure 4. Hidden Fields in HTML Form Post to Hosted Checkout ................................................................................ 16
Figure 5. Code Example: Redirect to Mercurys HostedCheckout page ...................................................................... 17
Figure 6. Code Example: Embedding the Hosted Checkout page into an iFrame ....................................................... 17
Figure 7. Fields Returned in Form Post to the ProcessCompleteURL .......................................................................... 19
Figure 8. Fields Returned in Form Post to the ReturnUrl ............................................................................................ 19
Figure 9. Input Parameters for VerifyPayment ............................................................................................................ 19
Figure 10. Return Parameters for VerifyPayment ....................................................................................................... 21
Figure 11. Code Example: VerifyPayment Web Method ............................................................................................. 22
Figure 12. Input Parameters to InitializeCardInfo Method.......................................................................................... 25
Figure 13. Return Parameters from IntializeCardInfo Method .................................................................................... 25
Figure 14. C# Code Example: InitializeCardInfo web method ................................................................................... 26
Figure 15. Hidden Fields in HTML Form Post to Hosted Checkout .............................................................................. 27
Figure 16. C# Sample Code: Redirect to Mercury's HostedCheckout page ................................................................. 27
Figure 17. Code Example: iFrame markup ................................................................................................................... 28
Figure 18. Example HTML for iFrame markup ............................................................................................................. 28
Figure 19. Fields Returned in Form Post to the ProcessCompleteURL ........................................................................ 30
Figure 20. Fields Returned in Form Post to the ReturnUrl .......................................................................................... 30
Figure 21. CardInfo Input Parameters ......................................................................................................................... 31
Figure 22. CardInfo Return Parameters ....................................................................................................................... 32
Figure 23. Sample Code: VerifyCardInfo Web Method ............................................................................................... 32
Figure 24. Token Transaction Elements ....................................................................................................................... 33
Figure 25. Token Transaction Calls using Transaction Web Service ............................................................................ 34
Figure 26. CreditPreAuth Token Input Parameters ..................................................................................................... 36
Figure 27. Code Example: CreditPreAuth Token ......................................................................................................... 36
Figure 28. CreditPreAuthCaptureToken Input Parameters ......................................................................................... 37
Figure 29. Code Example: CreditPreAuthCaptureToken.............................................................................................. 37
Figure 30. CreditSaleToken Input Parameters ............................................................................................................. 38
Figure 31. Code Example: CreditSaleToken ................................................................................................................. 38
Figure 32. CreditAdjustToken Input Parameters ......................................................................................................... 39
Figure 33. Code Example: CreditAdjustToken ............................................................................................................. 39
Figure 34. CreditVoidSaleToken Input Parameters ..................................................................................................... 40
Figure 35. Code Example: CreditVoidSaleToken .......................................................................................................... 40
Figure 36. CreditReversalToken Input Parameters ...................................................................................................... 41
Figure 37. Code Example: CreditReversalToken .......................................................................................................... 41
Figure 38. CreditReturnToken Input Parameters ........................................................................................................ 42
Figure 39. Code Example: CreditReturnToken ............................................................................................................. 42
Figure 40. CreditVoidREturnToken Input Parameters ................................................................................................. 43
Figure 41. Code Example: CreditVoidReturnToken ..................................................................................................... 43
Figure 42. CreditResponse - Returned Values ............................................................................................................. 44
Figure 43. Illustration of the Three Phases of Stand-In ............................................................................................... 49
Figure 44. Card Verification Results Codes .................................................................................................................. 55
Figure 45. Screenshot capturing CVV and AVS data .................................................................................................... 56
Figure 46. AVS Response Codes ................................................................................................................................... 57
Figure 47. AVS Test Information .................................................................................................................................. 58
Figure 48. The Gift Card Life Cycle ............................................................................................................................... 60
Figure 49. Example of a Gift XML REQUEST ................................................................................................................. 62
Figure 50. Example of Gift XML RESPONSE.................................................................................................................. 65
Figure 51. Gift Card Attributes ..................................................................................................................................... 66
Figure 52. Web Services URLs and WSDLs ................................................................................................................... 67
Figure 53. Gift Transaction Web Services Methods and Arguments ........................................................................... 68
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 7 of 118
2014 Mercury

Figure 54. Web Services Example: Swiped Gift Issue .................................................................................................. 70
Figure 55. Web Services Example: Swiped Gift NoNSFSale ......................................................................................... 71
Figure 56. Web Services Example: Gift VoidSale ......................................................................................................... 72
Figure 57. Web Services Example: Gift Reload ............................................................................................................ 73
Figure 58. Web Services Example: Gift NoNSFSale using CRC ..................................................................................... 74
Figure 59. Web Services Example: Gift Sale using CVV Data ....................................................................................... 75
Figure 60. Code Example: Adding Gift Card Balance Query text link to a website ...................................................... 76
Figure 61. Code Example: Adding Gift Balance query image link to a website ........................................................... 76
Figure 62. Back of a Gift Card ...................................................................................................................................... 78
Figure 63. XML Example: Manual Gift Request using the two-digit security value (CRC) ........................................... 79
Figure 64. Example XML: Duplicate Transaction Declined .......................................................................................... 80
Figure 65. Gift Card Error responses............................................................................................................................ 83

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 8 of 118
2014 Mercury

Introduction to Mercury HostedCheckout
Mercurys HostedCheckout with integrated MToken technology provides a secure payment API for eCommerce
website developers by redirecting the transaction path to a Mercury secure payment site. The HostedCheckout
solution supplements the eCommerce checkout process, by providing a customized payment page for collection of
card data. Because the payment page is hosted by Mercury, card data is kept off of the eCommerce solution
providers servers, keeping them from qualifying as a Service Provider as defined by the PCI Council.
HostedCheckout does not replace the checkout process entirely, just the handling of sensitive credit card data.
HostedCheckout eliminates the need for eCommerce web developers to handle cardholder data.
Mercurys tokenization processing returns a token record that may be stored. This helps merchants achieve
PCI compliance and enables them to implement features such as recurring billing and card-on-file.
Overview of the Integration Process
Development cycles will vary according to available resources, the scope of the project and urgency of the
business. However, the overall process falls into recognizable phases proven to bring about a successful
outcomeaccelerated time to market and return on investment. Mercurys recommended best practice for a
successful integration is to plan do-able phases and know the Mercury certification and industry requirements
ahead of time to avoid surprises; focus development time on achievable results; and then let us help you grow
your business.
1. Integration Planning
Decide which features and functionalities you wish to implement. This may drive the programming language
or integration method best suited for these features.
Understand the specific requirements for your target industry/business.
Decide which integration method best fits your native architecture.
Review Mercurys integration specifications, and error response handling.
Participate in a pre-integration kick-off interview with your developer integrations representative, so
Mercury understands the scope of your integration to better customize our support.
Plan routine check-ins with your developer integrations representative to stay on track throughout the
integration process.
2. Active Development
Combine your programming language with the tools and sample code from our integration specifications.
Program and test using the MercuryDev.Net certification network.
3. Certification and Beta Review
Transaction Review and Certification: Complete and submit your transaction review test scripts to your
developer integrations representative. Your representative will review the test results and provide a quick
turnaround, identifying any issues that need to be addressed prior to issuing the Transaction Review
Certification letter.
(1) Integration
Planning
(2) Active
Development
(3) Certification
and Beta
Review
(4) Release and
Distribution
(5) System
Enhancements
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 9 of 118
2014 Mercury

Compliance Review: Our compliance specialists can assist with a preliminary compliance review or assist
with questions you may have in preparation for a Qualified Security Assessor audit.
Beta Review: Your developer integrations representative will review and monitor transactions of your first
merchant site(s) through one complete billing cycle. This includes analysis of the merchant(s) statements to
ensure payment-type interchange stability and to ensure that the best qualified rates are maintained
4. Release and Distribution
After your product is released into full production, Mercury provides you with:
Prospect to processing: our internal sales force can help you grow your channel.
Friendly, well-trained, 24-7 customer support teams to assist your merchants with common questions and
processing concerns.
Knowledgeable technical support teams to help troubleshoot and resolve more complex issues.
5. System Enhancements: Upgrades or Adding New Features
Once your integration is in production, enhancements, upgrades and new features may be requested by your
merchant base and/or target market, or may be required by revisions in security standards. Your developer
integrations representative will be available to consult with you on system enhancement requirements that you
would like to put into place and assist with any additional certification procedures required for that new feature.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 10 of 118
2014 Mercury

Integration: Three Step Transaction Process
Overview
1. Initiate the Payment Process. The web site developer initiates a call to a Mercury Payment Systems web
service (server to server) to start the checkout process and obtain a unique PaymentID. Transaction data
fields such as the MerchantID and the TotalAmount are passed to Mercury at this time.
2. Display the Mercury HostedCheckout page for Secure Processing. The web site developer redirects the user
to the Mercury HostedCheckout page, or the developer embeds the page in an iFrame on their site. The
unique PaymentID is passed to Mercury in hidden fields using an HTTP form post. The customer will enter
their credit card information on Mercurys hosted page and then press a [Submit Payment] button. The
payment is processed and control is relinquished back to the developer to continue processing as needed.
3. Verify Payment. The VerifyPayment method in the HostedCheckout web service is used to confirm the
successful status of a payment. This allows the eCommerce developer to validate the transaction approval or
decline status and includes additional information about the payment after Mercury has processed it,
including receipt data.
Supported Browsers
Internet Explorer 8, and 9
Firefox
Google Chrome
Safari 5 on Mac
Supported Devices
iPhone4, iPad/iOS 4, iOS 5
Android Smartphone and Tablet/Android 2.2, 2.3
BlackBerry/OS6, OS7
Windows Phone 7.5
Kindle Fire

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 11 of 118
2014 Mercury

Step 1: Initiate the Payment Process
To initiate the payment process, the Initialize Payment method in the HostedCheckout web service must be called
to pass the information needed to setup the process. The information passed is stored on Mercurys server for a
defined period of time. A unique PaymentID will be returned. The HostedCheckout web service is available
through the URL:
HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/hcws/hcservice.asmx
Production URL: https://hc.mercurypay.com/hcws/hcservice.asmx
Input Parameters to InitializePayment Method
Note Parameter names are case sensitive; please follow exactly as shown.
Parameter Type Length Description Required
MerchantID Numeric 24 The Merchants account or MerchantID that
payments will be processed under. The typical
format for a Mercury merchant ID is:
88430087469
The test MerchantID is 013163015566916
Yes
Password String 16 The web services password generated by
merchant or dealer/developer on the
MercuryView portal to allow access to the web
service.
Please contact your developer integrations
analyst for the test password
Yes
TranType String 16 The type of payment Mercury should process.
Values are PreAuth and Sale
Yes
PartialAuth String 3 Values = on or off - Default is off. You will have
to code to prompt for the remaining balance if
the card has insufficient funds to cover the
TotalAmount. If you do not want card holders
to be able to use the remainder of the balance
on their PrePaid debit cards, set this to off.
No
TotalAmount Numeric 8 The total amount of the order to charge the
card holder. Two decimal places are required.
Format is 99999.99.
If TotalAmount is left null, or is not a valid
number, you will receive an error response
back, such as The remote server returned an
error: (500) Internal Server Error.
Yes
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. It
will be used for both the Invoice and the RefNo
fields when the pre-auth is submitted.
Yes
Memo String 40 The Memo tag is the product name and version
number of the developers software.
Yes
TaxAmount Numeric 8 The tax amount of the transaction. Two
decimal places are required. If there is no tax
amount, pass in 0.00. Format is 99999.99.
Yes
CardHolderName String 30 Customer Card Holder Name as it appears on
card. This will pre-populate the Card Holder
name on the checkout page and will appear in
Mercury reporting. This can be pre-populated
with the Billing Name if you dont have the
Cardholders Name from the card.
No
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 12 of 118
2014 Mercury

Parameter Type Length Description Required
AVSFields String 4 Valid values = Off, Zip, or Both. Not available
for Canadian market.
No
AVSAddress String 8 Street number portion of CardHolder Billing
Address. If provided will be used for Address
Verification. Not available for Canadian market.
No
AVSZip String 5 or 9 Cardholder Zip. If provided, will be used for
address verification. Not available for Canadian
market.
No
CVV String 3 Valid values = off or on. Determines whether
CVV field is displayed. Default is on.
No
CustomerCode String 16 max Customer Code. No
ProcessCompleteUrl String 512 The URL on the Merchants Ecommerce site to
return to after the Mercury HostedCheckout
page finishes processing the transaction.
For an iFrame: This page will display within the
iFrame window. Must be a valid URL.
Yes
ReturnUrl String 512 For a Redirect: The URL to return to in the
event the user wants to cancel and go back to
the eCommerce site. Typically this URL is the
E-Commerce page they just came from such as
an Order Page. The ReturnUrl is also used
during a session timeout or if Mercury goes
into maintenance mode.
For an iFrame: The [Cancel] button is not
displayed. However, the ReturnUrl is used for a
session timeout. In that case, the ReturnUrl
page will display in the iFrame. This URL must
not be the same page that the iFrame exists on
or it will cause the iFrame to display duplicate
or nested pages. Use a separate URL such as
the ProcessCompleteURL or some other page.
Must be a valid URL.
Yes
PageTimeoutDuration Numeric 2 Values are 0 to 15, and indicates the number of
minutes until the page times out. Defaults to 0.
If PageTimeoutDuration is greater than 0,
timeout is active. Upon timeout, user will be
automatically redirected to the ReturnUrl and a
ReturnCode of 105 will be sent from
HostedCheckout indicating the reservation can
be released.
No
PageTimeoutIndicator String 3 Values are on and off. Default is off. The
timeout indicator will count down to 0 and
then redirect.
iFrame size must be increased to 600 X 600 if
FontSize = large or 550 X 500 if FontSize =
medium.
No
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 13 of 118
2014 Mercury

Parameter Type Length Description Required
DisplayStyle String 8 Valid values are Mercury or Custom.
Default is Mercury.
Mercury: Displays the Mercury banner with
a white background, and black Arial text.
On an iFrame, no Mercury banner is
displayed.
Custom: Displays the supplied logo from
LogoURL, background color, and font
information. If no LogoURL is passed or if it
is an iFrame, then no logo is displayed. Also
allows for CSS support. See Appendix 4 for
additional information.*
No
BackgroundColor String

16 Specifies the background color of the page.
Default is white. Format is hexadecimal or a
standard named color. The color should be
consistent with the background displayed on
the Merchants web site to make the
integration more seamless.
Note If Mercury is passed as DisplayStyle,
the background color will be white regardless
of the value passed.
No
FontColor String 16 The color for the labels on the page. Default is
black. Format is hexadecimal or html name
(i.e., Cyan or #00ffff)
Note If Mercury is passed as DisplayStyle,
font color will be black, regardless of the value
passed.
No
FontFamily String 64 The font family to be used for the labels on the
page. Default is Arial. There are 3 pre-defined
font family values that may be used:
FontFamily1, FontFamily2, FontFamily3.
The pre-defined font families are defined as
follows:
FontFamily1: Arial, Verdana, Geneva,
Helvetica, sans-serif
FontFamily2: Georgia, Times New Roman,
Times, serif
FontFamily3: Courier New, Courier,
monospace
A custom font family may also be specified.
This is a comma-delimited string of fonts.
Example: Comic Sans MS, Arial, sans-serif
Note If Mercury is passed as DisplayStyle,
font family will be Arial, regardless of the value
passed. Not utilized in mobile integration.
No
FontSize String 8 The font size. Default is Medium. Options are
Small, Medium, Large.
Note If Mercury is passed as DisplayStyle,
font size will be Medium, regardless of the
value passed. Not utilized in mobile
integration.
No
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 14 of 118
2014 Mercury

Parameter Type Length Description Required
LogoUrl String 512 For a Redirect: Specifies the URL of the logo to
display at the top of the page. Default is no
logo. The logo should be located on the
Merchants Ecommerce web site at a public
URL. The logo should be consistent with the
Merchants web site to make the integration
more seamless.
Note If Mercury is passed as DisplayStyle,
this will not be displayed.
This URL must use the HTTPS protocol. If the
LogoURL is HTTP, security warnings will be
displayed to the end user. Must be a valid
image URL.
For an iFrame: The LogoURL is not used
because the iFrame is already embedded on
the developers web page.
No
PageTitle String 64 For a Redirect: The html title of the page that
the browser will display in the title bar.
Typically this is the name of the merchants
web site. Helps to brand the checkout page
similar to the Merchants web site. If this is not
specified, the default value is Mercury Secure
Checkout.
For an iFrame: Not applicable.
No
OrderTotal String 3 Indicates whether the Order Total box will be
displayed on the page. This only applies to
iFrame. Valid values are on and off. Default is
on.
No
TotalAmountBackgroundColor String 8 Background color of the Order Total box.
Default color if not specified is gray.
No
SubmitButtonText String 32 Custom text for the [Submit] button. Default
value is Submit Payment. Note that on iFrame,
some 32 character strings will not fit due to
physical space constraints, and the text will be
cut off. DisplayStyle = Custom or Mercury.
No
CancelButtonText String 32 Custom text for the [Cancel] button. Default
value is Cancel. Only applies to Redirect.
DisplayStyle = Custom or Mercury.
No
ButtonTextColor String 16 Custom button text color. Can be a web color,
such as White, or a color hex value such as
#ffffcc.
No
ButtonBackgroundColor String 16 Custom button background color. Can be a web
color, such as Magenta, or a color hex value
such as #567891.
No
CancelButton String 3 Displays a [Cancel] button on the iFrame. If
selected it returns user to the ReturnUrl page.
Values are on and off. Default is off. This only
applies to iFrame pages.
No
JCB String 3 Display JCB logo. Values are on and off.
Default is on.
No
Diners String 3 Display Diners logo. Values are on and off.
Default is on.
No
Figure 1. Input Parameters to InitializePayment Method

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 15 of 118
2014 Mercury

Return Parameters from InitializePayment Method
Parameter Name Type Length Description
ResponseCode Integer 0 Success
100 AuthFail (bad password or MerchantId)
200 Mercury Internal Error
300 ValidationFail: General Validation Error (See
Message for list of validation errors)
PaymentID String 36 A unique identifier that identifies this particular
payment process.
Message String unlimited Success if initialization was successful, a verbal
description of one or more errors if initialization did not
succeed.
Figure 2. Return Parameters from InitializePayment Method
Note CSS Functionality
CSS (Cascading Style Sheets) provide extensive styling capability for HostedCheckout pages. CSS utilizes a separate
method to submit and have Mercury store the merchants CSS. This process is outside the initialize payment
process. See Appendix 4 for more information on CSS.
InitializePayment web method C# sample code
This sample code calls the InitializePayment web method. It is C# used in an Asp.net button click event. This code
references two variables on the markup page: txtPaymentID and lblInitResponseMessage
<!--Set the URL variables-->
string returnUrl =
"https://localhost:4307/ECommerceSite_1.0/ShoppingCart_SampleCode.aspx";
string orderCompleteUrl =
"https://localhost:4307/ECommerceSite_1.0/ShoppingCart_SampleCode.aspx";
string logoURL = ConfigurationManager.AppSettings["LogoURL"];

<!--Create the InitializePayment request-->
HCService.InitPaymentRequest hcRequest = new HCService.InitPaymentRequest();

<!--Populated the request fields.-->
hcRequest.MerchantID = ConfigurationManager.AppSettings["MerchantID"];
hcRequest.Password = ConfigurationManager.AppSettings["HCPassword"];
hcRequest.TranType = "PreAuth";
hcRequest.TotalAmount = 5.99;
Random rand = new Random();
hcRequest.Invoice = rand.Next(999999999).ToString();
hcRequest.CardHolderName = "John Jones";
hcRequest.AVSAddress = "4 Corporate Square";
hcRequest.AVSZip = "30329";
hcRequest.Frequency = "OneTime";
hcRequest.Memo = "Demo Ecommerce Merchant 1.0";
hcRequest.ReturnUrl = returnURL;
hcRequest.ProcessCompleteUrl = orderCompleteURL;
hcRequest.BackgroundColor = "Gray";
hcRequest.FontColor = "Black";
hcRequest.FontSize = "Medium";
hcRequest.FontFamily = "FontFamily1";
hcRequest.PageTitle = "Demo Ecommerce Merchant";
hcRequest.LogoUrl = logoURL;
hcRequest.DisplayStyle = "Custom";
hcRequest.OrderTotal = "on";
hcRequest.SubmitButtonText = "Submit Order";
hcRequest.CancelButtonText = "Cancel Order";

<!--Call the InitializePayment Web Service Method -->
HCService.HCService hcWS = new HCService.HCService();
HCService.InitPaymentResponse response = hcWS.InitializePayment(hcRequest);


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 16 of 118
2014 Mercury

<!--Check the responseCode-->
if (response.ResponseCode == 0)
{
<!--get the payment ID-->
txtPaymentID.Text = response.PaymentID;
}

<!--Access the response message if needed -->
lblInitResponseMessage.Text = response.Message;
Figure 3. C# Code Example: InitializePayment Web Method
Note If the transaction is not formatted correctly, you will receive an error message of "Your XML
is invalid. Check your XML syntax and refer to the Integration Guide." This can be caused by a misspelled tag, a tag
name that has incorrect case, a bad namespace, or just malformed xml.
Step 2: Display the Mercury HostedCheckout Page
Note If you are utilizing an iFrame, please skip to section 2b.
Mercury HostedCheckout URL: (For use on desktop browsers and tablets)
HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/Checkout.aspx
Production URL: https://hc.mercurypay.com/Checkout.aspx
Mercury HostedCheckout URL for mobile: (Optimized for use on mobile smartphone devices and Kindle.)
HostedCheckout Mobile URLs
Development URL: https://hc.mercurydev.net/mobile/mCheckout.aspx
Production URL: https://hc.mercurypay.com/mobile/mCheckout.aspx
Hidden Fields in HTML Form Post to HostedCheckout
Field Name Description Required
PaymentID The unique identifier returned by the InitializePayment web service call. Yes
ReturnMethod Returns users to your site using a GET or a POST. Default is POST.
If ReturnMethod = POST, PaymentID ReturnCode, and ReturnMessage will be passed
back as hidden fields in an html form.
If ReturnMethod = GET, the PaymentID and ReturnCode will be returned as Query String
parameters in the URL.
If your site is using HTTP instead of HTTPS (HTTPS is highly recommended), you should
use a GET to avoid browser warnings.
No
Figure 4. Hidden Fields in HTML Form Post to Hosted Checkout
2.a Redirect sample code
This sample code will redirect the browser to Mercurys HostedCheckout page. It is server-side C# code used in an
asp.net click event that creates an html response that will redirect to Mercury.
<!--Set the necessary variables before building html.-->
String hostedCheckoutURL = ConfigurationManager.AppSettings[HostedCheckoutURL];
string paymentID = this.txtPaymentID.Text;

<!--Build an html form post to be sent back to the browser -->
<!--It will redirect the browser to the Mercury HostedCheckout page-->
Response.Clear();
Response.Write(<html><head>);
Response.Write(</head><body onload=\document.frmCheckout.submit()\>);
Response.Write(<form name=\frmCheckout\ method=\Post\ action=\ +
hostedCheckoutURL + \ >);
Response.Write(<input name=\PaymentID\ type=\hidden\ value=\ + paymentID +
\>);
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 17 of 118
2014 Mercury

Response.Write(</form>);
Response.Write(</body></html>);
Response.End();
Figure 5. Code Example: Redirect to Mercurys HostedCheckout page
In the event a user with a smartphone ends up on a HostedCheckout page that is designed for a desktop browser,
then HostedCheckout will attempt to detect this situation and redirect the user to our mobile optimized page. If
the users device is a larger tablet such as an iPad, HostedCheckout will not redirect to the mobile version because
larger tablets work best with the desktop version of HostedCheckout pages.
Some tablets that are large may still redirect to the mobile version because the UserAgent string in the browser
only indicates that its mobile and may not indicate its a tablet. This is okay because the HostedCheckout mobile
pages render well on the larger tablets.

2.b Embedding the HostedCheckout page in an iFrame (eCommerce only, not available for
mobile)
HostedCheckout Credit URLs
Development URL iFrame: https://hc.mercurydev.net/CheckoutiFrame.aspx
Production URL iFrame: https://hc.mercurypay.com/CheckoutiFrame.aspx
1. Create an iFrame HTML tag on your main shopping cart or order page where you need to collect the payment
information.
a. Set your iFrame height and width attributes to 450 pixels.
The default payment information content has been optimized for display at 450 x 450pixels. However,
you may have a requirement to modify the height and width values or change the value from pixels to a
percentage. If you set the height and width attributes to something other than 450 x 450 pixels, take care
to ensure scrolling is not forced in your target resolution.
b. Set the scrolling attribute to auto.
c. Set the src to an empty string to keep the iFrame from loading before you are ready.
Below is an example of the markup for an iFrame. Combining the style setting of display: none with the
onload=this.style.display=block; will help avoid the flashing effect when the iFrame loads. Note that the
iFrame will not be visible at this point because of the src= setting. The Your browser does not support
text only appears if the browser does not support iFrames.
Example HTML:
<div style= height: 450px; margin-left: 253px;>
<iFrame id=ctl00_MainContent_ifrm
src=https://hc.mercurydev.net/Checkoutiframe.aspx?pid=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e height=450px width=450px scrolling=auto frameborder=0
style=text-align: center; display: none;> onload=this.style.display=block;>
Your browser does not support iFrames. To view this content, please download and use
the latest version of one of the following browsers: Internet Explorer, Firefox,
Google Chrome or Safari.
</iFrame>
</div>
Figure 6. Code Example: Embedding the Hosted Checkout page into an iFrame
After you have called InitializePayment, and when you are ready to display and load the iFrame page, you will
need to set the src property of the iFrame from either the client side script or server side code:
src= https://hc.mercurydev.net/CheckoutiFrame.aspx?pid=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e.
The URL must contain a pid query parameter that is the PaymentID you received when calling
InitializePayment.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 18 of 118
2014 Mercury

If you require the user to be returned to your site using GET instead of a Form POST, include
ReturnMethod=get in the URL. The default is post.
If your site is using HTTP instead of HTTPS (HTTPS is highly recommended), you should use a GET to avoid
browser warnings.
Src= https://hc.mercurydev.net/CheckoutiFrame.aspx?pid=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e&ReturnMethod=get
2. Once the user has pressed [Submit Payment] on the HostedCheckout page within the iFrame, the iFrame will
process the payment and then display the page specified in the ProcessCompleteURL.
3. Additional notes about the use of iFrame:
The ReturnUrl parameter passed in InitializePayment should not be the same page that contains the
iFrame. Currently the only reason the ReturnUrl is used for an iFrame is when a session timeout occurs. If
the ReturnUrl is the same as the page containing the iFrame, and a timeout occurs, it will cause a
repetitive nested display in the iFrame. To handle this use the page specified in the ProcessCompleteURL
or create an additional page for session timeouts. The page content size should display in a 450 x 450 pixel
iFrame*. You can display whatever you want on this page based on the ReturnCode in the form post as
identified in section 2c below.
Similarly, the page specified in the ProcessCompleteURL parameter passed in InitializePayment is going to
appear within the iFrame window. The page content size should display in a 450 x 450 pixel iFrame*. The
page will receive form post parameters as identified in section 2c below. You can display whatever
information they want because the developer controls this page. It is also possible to communicate
between the iFrame and the parent page by navigating the dom.
* If you modify the suggested iFrame size, take care to ensure your content displays properly in its
defined size based on your target resolution.
2.c Parameters Passed Back to ProcessCompleteURL or ReturnUrl Page via GET or POST
Once the user enters the credit card data and presses [Submit Payment], the payment is processed and control is
returned back to the web site developer via the ProcessCompleteURL. The fields passed to the developer are
listed in the table below.
When returning to the eCommerce web site, if the ReturnMethod is a GET, the fields below will appear as
query string parameters in the URL. For a ReturnMethod of POST, they will appear as hidden fields in an html
form.
For a redirect, the user is redirected back to the ProcessCompleteURL.
For an iFrame, the iFrame will redirect to the page specified by the ProcessCompleteURL and display it within
the iFrame.
! Important Note It is very important to reference the ResponseCode/Message returned in the ReturnURL and
ProcessCompleteURL. Using them will allow you to continue the transaction flow in a logical manner.
Fields Returned in Form Post to the ProcessCompleteURL
Parameter Name Type Length Description
PaymentID String 36 The PaymentID that started the payment process is returned back to the
eCommerce developer.
ReturnCode Int 0 Success
100 AuthFail (bad password or id)
101 CardDeclined the card was declined for the transaction.
Status=Decline
200 Mercury Internal Error
202 LoadPaymentInfoFail data saved from Initialize Payment
invalid/missing
203 ProcessPaymentFail unable to process. Payment Status=Error.
204 PreAuthFailDBErr internal database error for PreAuth transaction
205 SalesNotCompletedDBErr internal database error for Sale transaction
301 ValidationCCFail Credit Card failed Mod10 check multiple times
302 ValidationServerSideFailure can occur when scripting is off in users
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 19 of 118
2014 Mercury

Parameter Name Type Length Description
browser so client side validation did not occur.
303 ValidateNameFail. Invalid data entered in cardholder name field.
ReturnMessage String unlimited Success: Your Transaction has been approved.*
AuthFail, ValidationFail, ValidateCCFail, ValidationServerSideFail: We are
unable to process your order at this time. Please contact our customer service.
MercuryInternalFail, FormPostFail, GetInitDBFail, ProcessPaymentFail,
SavePreAuthDBFail, SaveSaleDBFail: We are unable to process your order at
this time. Please place your order again.
* ReturnMessage is not returned if ReturnMethod = GET
Figure 7. Fields Returned in Form Post to the ProcessCompleteURL
The user may be sent back to the designated ReturnUrl for several different reasons as listed below. The
ReturnMessage is provided, but does not necessarily need to be displayed.
Fields Returned in Form Post to the ReturnUrl
Parameter Name Type Length Description
PaymentID String 36 The PaymentID that started the payment
process is returned back to the eCommerce
developer.
ReturnCode Int 102 UserCancelled the user pressed cancel.
103 SessionTimeout the session timed out.
104 MaintenanceMode the site is in maintenance mode.
105 PageTimeout duration time exceeded.
ReturnMessage String unlimited 102 The user pressed cancel. *
103 The user session timed out.
104 Payment processing is temporarily unavailable at this time.
105 The transaction was cancelled because the time to commplete
the transaction was exceeded.
*ReturnMessage is not returned if ReturnMethod = GET.
Figure 8. Fields Returned in Form Post to the ReturnUrl
Step 3: Verify the Payment
To find out the status of a payment, the VerifyPayment method in the HostedCheckout web service must be
called. This allows the eCommerce developer to get the status and additional information about the payment
after Mercury has processed it. The HostedCheckout web service is available through the URL:
HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/hcws/hcservice.asmx
Production URL: https://hc.mercurypay.com/hcws/hcservice.asmx
Input Parameters
Parameter Name Type Length Description
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be processed
under.
PaymentID String 36 The unique identifier returned by the InitializePayment web service.
Password String 16 The web services password assigned by Mercury to the Merchants account
(MerchantID) to allow access to the web
Figure 9. Input Parameters for VerifyPayment

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 20 of 118
2014 Mercury

Return Parameters
Field Name Type Length Description
ResponseCode* Int A Code indicating the result of the transaction (See associated Status):
0 Success
100 AuthFail (bad password or id)
200 Mercury Internal Error. Specific error will be logged in Mercurys
internal error log.
300 Validation failure one of the request parameters was either missing
or invalid.
Status Char 16 The Status of the transaction.
Values: Approved, Declined, Error, Invalid, AuthFail, MPSError.
If ResponseCode = 0
Approved: The transaction was approved.
Declined: The transaction was declined.
Blank: The payment has not been processed at the time the method was
called.
Error: Indicates an error from the transaction processing host.
Invalid: Indicates that the user entered invalid card data too many times
and was therefore redirected back to the Merchants eCommerce site.
If ResponseCode = 100
AuthFail: The authorization failed for the given MerchantID and Password
If ResponseCode =200
MPSError: An internal error has occurred.
StatusMessage Char 64 The textual description of the status. This should not be displayed to the
end user. Use DisplayMessage instead.
AcqRefData Char 200 Required for PreAuthCapture and PreAuth Reversal.
Amount Numeric 8 The amount of the transaction
AuthCode Char 16 The Authorization Code. Required for PreAuthCapture.
AVSAddress Char 8 Address used for AVS verification. Note it is truncated to 8 characters.
AVSResult Char 40 The result of the AVS check. AVSResult codes are in the Global Spec and
there is a different list per card type. Suggested message upon AVS
mismatch: The billing address provided does not match the billing address
on file. Please verify that the billing address provided matches the billing
address on file with the card issuer. If you continue to experience problems,
please contact your credit card company.
AVSZip Char 9 Postal code used for AVS verification.
CardholderName Char 32 The name on the card
CardType Char 40 The type of card used to make the payment.
CustomerCode Char 16 The customer code passed in InitializePayment.
CvvResult Char 40 Result of the CVV check. Values:
M=Match
N=No Match
P=Not Processed
S=CVV should be on card but merchant indicated it is not present
(Visa/Discover only)
U=Issuer is Not Certified, CID not checked (AMEX only)
DisplayMessage Char 512 Mercurys Recommended message to display to the end user. The
eCommerce web site developer can use this message or display own
message.
ExpDate Char 4 Expiration date of card used. Can be stored in instances where card-on-file
or recurring billing is being utilized and merchant desires to remind
cardholder to update card information when expiration date approaches.
Note Expiration date cannot be printed on receipts or used in
correspondence with card holder. Expiration date on receipts should be
masked with Xs, such as XXXX or XX/XX.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 21 of 118
2014 Mercury

Field Name Type Length Description
Invoice Char 25 Mercury responds back with the Invoice passed to us on the
HostedCheckout request.
MaskedAccount Char 12 Masked credit card number. (e.g.,: xxxxxxxx6781)
Memo Char 40 The Memo tag is the product name and version number of the developers
software.
PaymentIDExpired Bool If the paymentID has been used to make a payment (even if they payment
was declined or had an error), or if the session timed out while the user
was on the HostedCheckout page, then this will be true. Otherwise, this
will be false.
Once the payment ID is set to Expired, it may not be used again to make a
payment. The payment process must be started again with
InitializePayment.
ProcessData Char 200 Required for PreAuthReversal.
RefNo Char 16 Transaction reference number. Required for VoidSale.
TaxAmount Numeric 8 The tax amount of the transaction, passed in InitializePayment.
Token Char 100 The token generated by the transaction that replaces the credit card #. Can
be used in subsequent transactions such as CreditPreAuthCaptureToken.
TransPostTime DateTime The date/time that the transaction occurred in EST.
If it is 1/1/0001 this is equivalent to blank or Null.
TranType Char 10 PreAuth or Sale
Figure 10. Return Parameters for VerifyPayment

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 22 of 118
2014 Mercury

VerifyPayment Web Method Sample Code
This sample calls the VerifyPayment web method and displays the response information.
<!--create the request-->
HCService.PaymentInfoRequest verifyPaymentRequest = new HCService.PaymentInfoRequest();

verifyPaymentRequest.MerchantID = System.Configuration.ConfigurationManager.AppSettings["Merchan
tID"];
verifyPaymentRequest.Password = System.Configuration.ConfigurationManager.AppSettings["HCPasswor
d"];
verifyPaymentRequest.PaymentID = txtPaymentID.Text;

<!--Call the VerifyPayment web method-->
HCService.HCService hcService = new HCService.HCService();
HCService.PaymentInfoResponse response = hcService.VerifyPayment(verifyPaymentRequest);
<!--get the information from the response-->
this.lblVerifyInfo.Text = "ResponseCode=" + response.Status + "<BR/>";
this.lblVerifyInfo.Text += "Status=" + response.Status + "<BR/>";
this.lblVerifyInfo.Text += "StatusMessage=" + response.Status + "<BR/>";
this.lblVerifyInfo.Text += "DisplayMessage=" + response.Status + "<BR/>";
this.lblVerifyInfo.Text += "Token=" + response.Token + "<BR/>";
this.lblVerifyInfo.Text += "AuthCode=" + response.AuthCode + "<BR/>";
this.lblVerifyInfo.Text += "AvsResult: " + response.AvsResult + "<BR/>";
this.lblVerifyInfo.Text += "CvvResult: " + response.CvvResult + "<BR/>";
this.lblVerifyInfo.Text += "CardType: " + response.CardType + "<BR/>";
this.lblVerifyInfo.Text += "RefNo: " + response.RefNo + "<BR/>";
this.lblVerifyInfo.Text += "Invoice: " + response.Invoice + "<BR/>";
this.lblVerifyInfo.Text += "AcqRefData: " + response.AcqRefData + "<BR/>";
this.lblVerifyInfo.Text += "TaxAmount: " + response.TaxAmount + "<BR/>";
this.lblVerifyInfo.Text += "TransPostTime: " + response.TransPostTime + "<BR/>";
this.lblVerifyInfo.Text += "Masked Acct: " + response.MaskedAccount + "<BR/>";
this.lblVerifyInfo.Text += "Amount: " + response.Amount + "<BR/>";
this.lblVerifyInfo.Text += "Cardholder Name: " + response.CardholderName + "<BR/>";
this.lblVerifyInfo.Text += "AVS Address: " + response.AVSAddress + "<BR/>";
this.lblVerifyInfo.Text += "AVS Zip: " + response.AVSZip + "<BR/>";
this.lblVerifyInfo.Text += "Tran Type: " + response.TranType + "<BR/>";
this.lblVerifyInfo.Text += "Payment ID
Expired: " + response.PaymentIDExpired.ToString() + "<BR/>";
this.lblVerifyInfo.Text += "Customer Code: " + response.CustomerCode + "<BR/>";
this.lblVerifyInfo.Text += "Memo: " + response.Memo + "<BR/>";
Figure 11. Code Example: VerifyPayment Web Method

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 23 of 118
2014 Mercury

CARDINFO
CardInfo is used to obtain a token without charging the card. Used for Card-on-File and Recurring billing.

Step 1: Initiate the CardInfo Process
To initiate the CardInfo process, the InitializeCardInfo method in the HostedCheckout web service must be called
to pass the necessary information to setup the process. The information passed is stored on Mercurys server for a
defined period of time. A unique CardID will be returned. The HostedCheckout web service is available through
the URL:
HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/hcws/hcservice.asmx
Production URL: https://hc.mercurypay.com/hcws/hcservice.asmx
Input Parameters to InitializeCardInfo Method
Parameter Name Type Length Description Required
MerchantID Numeric 24 The Merchants account or MerchantID that
payments will be processed under. The typical
format for a Mercury merchant ID is: 88430087469
The test MerchantID is 013163015566916
Yes
Password String 16 The web services password assigned by Mercury to
the Merchants account (MerchantID) to allow
access to the web service.
Please contact your developer integrations analyst
for the test password
Yes
Frequency String 9 OneTime or Recurring Yes
CardHolderName String 30 Customer Card Holder Name as it appears on card.
This will pre-populate the Card Holder name on the
checkout page and will appear in Mercury
reporting. This can be pre-populated with the
Billing Name if you dont have the Cardholders
Name off the card.
No
OperatorID String 10 Operator ID No
ProcessCompleteUrl String 512 The URL to return to after the Mercury
HostedCheckout page finishes processing the
transaction.
For an iFrame: This page will display within the
iFrame window.
Yes
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 24 of 118
2014 Mercury

Parameter Name Type Length Description Required
ReturnUrl String 512 For a Redirect: The URL to return to in the event
the user wants to cancel. Typically this URL is the
page they just came from such as an Order Page.
The ReturnUrl is also used during a session timeout
or if Mercury goes into maintenance mode.
For an iFrame: The [Cancel] button is not displayed.
However, the ReturnUrl is used for a session
timeout. In that case, the ReturnUrl page will
display in the iFrame. This URL must not be the
same page that the iFrame exists on or it will cause
the iFrame to display duplicate or nested pages.
Use a separate URL such as the
ProcessCompleteURL or some other page.
Yes
PageTimeoutDuration numeric 2 Values are 0 to 15, and indicate minutes until the
page times out. Defaults to 0. If
PageTimeoutDuration is greater than 0, timeout is
active. Upon timeout, user will be automatically
redirected to the ReturnUrl.
No
DisplayStyle String 8 Valid values are Mercury or Custom. If DisplayStyle
is not specified, the style of the page will default to
Mercury.
Mercury: Displays the Mercury banner with a white
background, and black Arial text. On an iFrame, no
Mercury banner is displayed.
Custom: Displays the supplied logo from LogoURL,
background color, and font information. If no
LogoURL is passed or if it is an iFrame, then no logo
is displayed.
No
BackgroundColor String

16 Specifies the background color of the page. Default
is white. Format is hexadecimal or a standard
named color. The color should be consistent with
the background displayed on the Merchants web
site to make the integration more seamless.
Note If Mercury is passed as DisplayStyle, the
background color will be white regardless of the
value passed.
No
FontColor String 16 The color for the labels on the page. Default is
black. Format is hexadecimal or html name (i.e.,
Cyan or #00ffff)
Note If Mercury is passed as DisplayStyle, font
color will be black, regardless of the value passed.
No
FontFamily String 64 The font family to be used for the labels on the
page. Default is Arial. There are 3 pre-defined font
family values that may be used:
FontFamily1, FontFamily2, FontFamily3.
A custom font family may also be specified. This is a
comma-delimited string of fonts. Example: Comic
Sans MS, Arial, sans-serif
Note If Mercury is passed as DisplayStyle, font
family will be Arial, regardless of the value passed.
Not utilized in mobile integration.
No
FontSize String 8 The font size. Default is Medium. Options are
Small, Medium, Large
Note If Mercury is passed as DisplayStyle, font
size will be medium, regardless of the value passed.
Not utilized in mobile integration.
No
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 25 of 118
2014 Mercury

Parameter Name Type Length Description Required
LogoUrl String 512 For a Redirect: Specifies the URL of the logo to
display at the top of the page. Default is no logo.
Note If Mercury is passed as DisplayStyle, this
will not be displayed.
This URL must use the HTTPS protocol. If the
LogoURL is HTTP, security warnings will be
displayed to the end user.
For an iFrame: The LogoURL is not used because
the iFrame is already embedded on the developers
web page.
No
PageTitle String 64 For a Redirect: The html title of the page that the
browser will display in the title bar. Typically this is
the name of the merchants web site. Helps to
brand the checkout page similar to the Merchants
web site. If this is not specified, the default value is
Mercury Secure Checkout.
For an iFrame: Not applicable.
No
SubmitButtonText String 32 Custom text for the [Submit] button. Default value
is Update on Ecomm and Add Card on POS solution.
Note that on iFrame, some 32 character strings will
not fit due to physical space constraints, and the
text will be cut off.
No
CancelButtonText String 32 Custom text for the [Cancel] button. Default value
is Cancel. This only applies to Redirect pages, since
there is no [Cancel] button on iFrame pages.
No
ButtonTextColor String 16 Custom button text color. Can be a web color, such
as White, or a color hex value such as #ffffcc.
No
ButtonBackgroundColor String 16 Custom button background color. Can be a web
color, such as Magenta, or a color hex value such
as #567891.
No
CancelButton String 3 Displays a [Cancel] button on the iFrame. If selected
it returns user to the ReturnUrl page. Values are on
and off. Default is off. This only applies to iFrame
pages. The [Cancel] button is always displayed on
the redirect pages.
No
JCB String 3 Display JCB radio button. Values are On and Off.
Default is On.
No
Diners String 3 Display Diners radio button. Values are On and Off.
Default is On.
No
Figure 12. Input Parameters to InitializeCardInfo Method
Return Parameters from InitializeCardInfo Method
Parameter Name Type Length Description
ResponseCode Integer 0 Success
100 AuthFail (bad password or MerchantId)
200 Mercury Internal Error
300 ValidationFail: General Validation Error (See Message for list
of validation errors)
CardID String 36 A unique identifier that identifies this particular CardInfo
transaction.
Message String unlimit
ed
Success if initialization was successful, a verbal description of
one or more errors if initialization did not succeed.
Figure 13. Return Parameters from IntializeCardInfo Method
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 26 of 118
2014 Mercury

InitializeCardInfo Web Method Sample Code
This sample code calls the InitializeCardInfo web method. It is C# used in an Asp.net button click event. This code
references two variables on the markup page: txtCardID and lblInitResponseMessage
<!--Set the URL variables-->
string returnURL = "http://localhost:4307/CardInfo_SampleCode.aspx";
string orderCompleteURL = "http://localhost:4307/CardInfo_SampleCode.aspx";
string logoURL = ConfigurationManager.AppSettings["LogoURL"];

<!--Create the InitializeCardInfo request-->
HCService.InitCardInfoRequest hcRequest = new HCService.InitCardInfoRequest();

<!--//Populated the request fields-->
hcRequest.MerchantID = ConfigurationManager.AppSettings["MerchantID"];
hcRequest.Password = ConfigurationManager.AppSettings["HCPassword"];

hcRequest.CardHolderName = "John Jones";
hcRequest.Frequency = "OneTime";
hcRequest.ReturnUrl = returnURL;
hcRequest.ProcessCompleteUrl = orderCompleteURL;
hcRequest.BackgroundColor = "Gray";
hcRequest.FontColor = "Black";
hcRequest.FontSize = "Medium";
hcRequest.FontFamily = "FontFamily1";
hcRequest.PageTitle = "Demo Card Info";
hcRequest.LogoUrl = logoURL;
hcRequest.DisplayStyle = "Custom";
hcRequest.SubmitButtonText = "Save Card";
hcRequest.CancelButtonText = "Cancel Save";
hcRequest.OperatorID = "OP10";

<!--Call the InitializeCardInfo Web Service Method.-->
HCService.HCService hcWS = new HCService.HCService();
HCService.InitCardInfoResponse response = hcWS.InitializeCardInfo(hcRequest);

<!--Check the responseCode-->
if (response.ResponseCode == 0)
{
<!--get the CardInfo ID-->
txtCardID.Text = response.CardID;
}
<!--Access the response message if needed-->
lblInitResponseMessage.Text = response.Message;
Figure 14. C# Code Example: InitializeCardInfo web method
Note If the transaction is not formatted correctly, you will receive an error message of Your XML
is invalid. Check your XML syntax and refer to the Integration Guide."

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 27 of 118
2014 Mercury

Step 2: Display the Mercury CardInfo Page
Note If you are utilizing an iFrame, please skip to section 2b.
Mercury HostedCheckout URL: (For use on desktop browsers and tablets)
HostedCheckout CardInfo URLs
Development URL: https://hc.mercurydev.net/CardInfo.aspx
Production URL: https://hc.mercurypay.com/CardInfo.aspx
Mercury HostedCheckout URL: (Optimized for use on mobile smartphone devices)
HostedCheckout CardInfo Mobile URLs
Development URL: https://hc.mercurydev.net/mobile/mCardInfo.aspx
Production URL: https://hc.mercurypay.com/mobile/mCardInfo.aspx
Hidden Fields in HTML Form Post to HostedCheckout
Field Name Description Required
CardID The unique identifier returned by the InitiateCardInfo web service. Yes
ReturnMethod Returns users to your site using a GET or a POST. Default is POST. If ReturnMethod
= POST, CardID, ReturnCode, and ReturnMessage will be passed back as hidden
fields in an html form. If ReturnMethod = GET, the PaymentID and ReturnCode will
be returned as Query String parameters in the URL. If your site is using HTTP
instead of HTTPS (HTTPS is highly recommended), you should use a GET to avoid
browser warnings.
No
Figure 15. Hidden Fields in HTML Form Post to Hosted Checkout
Redirect sample code
This is sample code that will redirect the browser to Mercurys HostedCheckout page. It is server side C# code
used in an asp.net click event that creates an html response that will redirect to Mercury.
<!--Set the necessary variables before building html.-->
string addCardURL = ConfigurationManager.AppSettings["CardInfoURL"];
string CardID = this.txtCardID.Text;

<!--Build an html form post to be sent back to the browser.It will redirect the browser to the
Mercury HostedCheckout page.-->
Response.Clear();
Response.Write("<html><head>");
Response.Write("</head><body onload=\"document.frmAddCard.submit()\">");
Response.Write("<form name=\"frmAddCard\" method=\"Post\" action=\"" + addCardURL +
"\" >");
Response.Write("<input name=\"CardID\" type=\"hidden\" value=\"" + CardID + "\">");
Response.Write("</form>");
Response.Write("</body></html>");
Response.End();
Figure 16. C# Sample Code: Redirect to Mercury's HostedCheckout page
Note In the event a user with a smartphone ends up on a HostedCheckout page that is designed for a desktop
browser, then HostedCheckout will attempt to detect this situation and redirect the user to our mobile optimized
page. If the users device is a larger tablet such as an iPad, HostedCheckout will not redirect to the mobile version
because larger tablets work best with the desktop version of HostedCheckout pages.
Some tablets that are large may still redirect to the mobile version because the UserAgent string in the browser
only indicates that its mobile and may not indicate its a tablet. This is okay because the HostedCheckout mobile
pages render well on the larger tablets.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 28 of 118
2014 Mercury

2b. Embedding the CardInfo page in an iFrame (E-commerce only, not available for mobile)
HostedCheckout CardInfo URLs
Development URL: https://hc.mercurydev.net/CardInfoiFrame.aspx
Production URL: https://hc.mercurypay.com/CardInfoiFrame.aspx
1. Create an iFrame HTML tag on your CardInfo page where you need to collect the CardInfo information.
a. Set your iFrame width and height attributes to 450X450 pixels if you are implementing the iFrame
eComm.
Note The default CardInfo information content has been optimized for display at the above
resolutions. However, you may have a requirement to modify the height and width values or change the
value from pixels to a percentage. If you set the height and width attributes to something other than the
recommended values, take care to ensure scrolling is not forced in your target resolution.
b. Set the scrolling attribute to auto.
c. Set the src to an empty string. This will cause the iFrame to not display initially.
Below is an example of the markup for an iFrame. Combining the style setting of display: none with the
onload="this.style.display='block'; will help avoid the flashing effect when the iFrame loads. Note that the
iFrame will not be visible at this point because of the src="" setting. The Your browser does not support
text will only appear if the browser does not support iFrames.
<div style=" width: 450px; ">
<iFrame id='ifrm' src="" height="450px" width="450px" scrolling="auto"
frameborder="0" runat="server" style="text-align: right; display: none;"
onload="this.style.display='block';">
Your browser does not support iFrames. To view this content, please download and
use the latest version of one of the following browsers: Internet Explorer,
Firefox, Google Chrome or Safari.
</iFrame>
</div>
Figure 17. Code Example: iFrame markup
2. After you have called InitializeCardInfo, and when you are ready to display and load the iFrame page, you will
need to set the src property of the iFrame either from client side script or server side code:
src= https://hc.mercurydev.net/CardInfoiFrame.aspx?cardID=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e.
The URL must contain a CardID query parameter that is the CardID you received in the Response when
calling InitializeCardInfo.
If you require the user to be returned to your site using GET instead of a Form POST, include
ReturnMethod=get in the URL. Default is post.
If your site is using HTTP instead of HTTPS (HTTPS is highly recommended), you should use a GET to avoid
browser warnings.
src= https://hc.mercurydev.net/CardInfoiFrame.aspx?cardID=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e;ReturnMethod=get
Example HTML
<div style= "width: 450px; >
<iFrame id="ctl00_MainContent_ifrm"
src="30https://hc.mercurydev.net/CardInfoiFrame.aspx?CardID=e727bd2e-c1ae-43c9-aadb-
e20fd604ae4e" height="450px" width="450px" scrolling="auto" frameborder="0" style="text-
align: right;" onload="this.style.display='block';"> Your browser does not support
iFrames. To view this content, please download and use the latest version of one of the
following browsers: Internet Explorer, Firefox, Google Chrome or Safari.
</iFrame>
</div>
Figure 18. Example HTML for iFrame markup
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 29 of 118
2014 Mercury

3. Once the user has pressed the [Update] button on the CardInfo page within the iFrame, the iFrame will
process the CardInfo and then display the page specified in the ProcessCompleteURL.
4. Additional notes about the use of iFrame:
a. The ReturnUrl parameter passed in InitializeCardInfo should not be the same page that contains the
iFrame. Currently the only reason the ReturnUrl is used for an iFrame is when a session timeout occurs. If
the ReturnUrl is the same as the page containing the iFrame, and a timeout occurs, it will cause a
repetitive nested display in the iFrame. To handle this, use the page specified in the OrderCompleteURL
or create an additional page for session timeouts. The page content size should display in a 450 x 450
pixel iFrame*. You can display whatever you want on this page based on the ReturnCode in the form
post as identified in section 2c below.
b. Similarly, the page specified in the OrderCompleteURL parameter passed in InitializeCardInfo is going to
appear within the iFrame window. The page content size should display in a 450 x 450 pixel iFrame*. The
page will receive form post parameters as identified in section 2c below. The developer can display
whatever information they want because they control this page. It is also possible to communicate
between the iFrame and the parent page by navigating the dom.
*If you modify the suggested iFrame size, take care to ensure your content displays properly in its defined
size based on your target resolution.
2c - Form Post Parameters Passed Back to ProcessCompleteUrl or ReturnUrl
Once the user enters the credit card data and clicks [Update] or [Add Card], a token is generated and control is
returned back to the web site developer via the ProcessCompleteURL. The fields passed to the developer are listed
below.
When returning to the eCommerce web site, if the ReturnMethod is a GET, the fields below will appear as
query string parameters in the URL. For a ReturnMethod of POST they will appear as hidden fields in an html
form.
For a redirect, the user is redirected back to the ProcessCompleteURL.
For an iFrame, the iFrame will redirect to the page specified by the ProcessCompleteURL and display it within
the iFrame.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 30 of 118
2014 Mercury

Fields Returned in Form Post to the ProcessCompleteURL
Parameter Name Type Length Description
CardID String 36 The CardID that started the CardInfo process is returned back to the POS.
ReturnCode Int 0 Success
100 AuthFail (bad password or id)
101 CardDeclined the card was declined for the transaction.
Status=Decline
102 Cancel. The user pressed cancel.
103 Session Timeout
206 SaveCardInfoFail A transaction error occurred processing the card
info.
207 LoadCardInfoFail Could not retrieve the card info for the supplied
CardID.
208 ProcessCardInfoFail unable to process. CardInfo Status=Error.
301 ValidationCCFail Credit Card failed Mod10 check multiple times
302 ValidationServerSideFailure possible tampering suspected
303 ValidateNameFail. Invalid data entered in cardholder name field.
ReturnMessage String unlimited Success: Your card information has been saved.
Cancel: The user pressed cancel.
Session Timeout: The users session timed out.
CardDeclined: An error occurred while saving your card information.
Please try again.
All others: An error occurred while saving your card information. Please
contact our customer service.
ReturnMessage is not returned if ReturnMethod = GET.
Figure 19. Fields Returned in Form Post to the ProcessCompleteURL
The user may be sent back to the designated ReturnUrl for a couple of reasons as listed below. The
ReturnMessage is provided, but does not necessarily need to be displayed.
Fields Returned in Form Post To the ReturnUrl
Parameter Name Type Length Description
CardID String 36 The CardID that started the CardInfo process is returned back to the POS.
The CardID is stored in the PaymentID field.
ReturnCode Int
102 UserCancelled the user pressed cancel. n/a for iFrame.
103 SessionTimeout the session timed out.
104 MaintenanceMode the site is in maintenance mode. n/a for
iFrame.
ReturnMessage String unlimited
102 The user pressed cancel.
103 The users session timed out.
104 -- Processing is temporarily unavailable at this time.
ReturnMessage is not returned if ReturnMethod = GET.
Figure 20. Fields Returned in Form Post to the ReturnUrl

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 31 of 118
2014 Mercury

Step 3: Verify the CardInfo
To find out the status of a CardInfo, the VerifyCardInfo routine in the HostedCheckout web service must be called.
This allows the application to get the status and additional information about the CardInfo after Mercury has
processed it. The HostedCheckout web service is available through the URL:
HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/hcws/hcservice.asmx
Production URL: https://hc.mercurypay.com/hcws/hcservice.asmx
Input Parameters
Parameter Name Type Length Description
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be processed
under.
CardID String 36 The unique identifier returned by the InitializeCardInfo web service.
Password String 16 The web services password assigned by Mercury to the Merchants account
(MerchantID) to allow access to the web
Figure 21. CardInfo Input Parameters
Return Parameters
Parameter Type Length Description
Status Char 10 The Status of the transaction.
Values: Approved, Declined, Error, Invalid, AuthFail, MPSError.
If ResponseCode = 0
Approved: The transaction was approved.
Declined: The transaction was declined.
Blank: The payment has not been processed at the time the method
was called.
Error: Indicates an error from the transaction processing host.
Invalid: Indicates that the user entered invalid card data too many
times and was therefore redirected back to the POS.
If ResponseCode = 100
AuthFail: The authorization failed for the given MerchantID and
Password
If ResponseCode =200
MPSError: An internal error has occurred.
ResponseCode* Int A Code indicating the result of the transaction (See associated Status)
0 Success
100 AuthFail (bad password or id)
200 Mercury Internal Error. Specific error will be logged in Mercurys
internal error log.
300 Validation failure one of the request parameters was either
missing or invalid.
StatusMessage Char 40 The textual description of the status. This should not be displayed to the
end user. Use DisplayMessage instead.
CardholderName Char 32 The name on the card
CardType Char 40 The type of card used to make the payment.
CardUsage Char 20 The card usage
DisplayMessage Char 512 Mercurys recommended message to display to the end user. The
developer can use this message or display own message.
ExpDate Char 4 Expiration date of card used. Can be stored in instances where card-on-file
or recurring billing is being utilized and merchant desires to remind
cardholder to update card information when expiration date approaches.
Note Expiration date cannot be printed on receipts or used in
correspondence with card holder. Expiration date on receipts should be
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 32 of 118
2014 Mercury

Parameter Type Length Description
masked with Xs, such as XXXX or XX/XX.
MaskedAccount Char 12 Masked credit card number. (i.e.: xxxxxxxx6781)
Operator ID Char 10 The Operator ID passed in InitializePayment.
CardIDExpired Bool If the payment ID has been used to make a payment (even if they payment
was declined or had an error), or if the session timed out while the user
was on the HostedCheckout page, then this will be true. Otherwise, this
will be false.
Once the payment ID is set to Expired, it may not be used again to make a
payment. The payment process must be started again with
InitializePayment.
Token Char 100 The token generated by the transaction that replaces the credit card #. Can
be used in subsequent transactions such as CreditPreAuthCaptureToken.
TranType Char 10 CardLookup
Figure 22. CardInfo Return Parameters
VerifyCardInfo Web Method Sample Code
This sample calls the VerifyCardInfo web method and displays the response information.
<!--create the request-->
HCService.CardInfoRequest verifyCardInfoRequest = new HCService.CardInfoRequest();

verifyCardInfoRequest.MerchantID = System.Configuration.ConfigurationManager.AppSettings["
MerchantID"];
verifyCardInfoRequest.Password = System.Configuration.ConfigurationManager.AppSettings["HC
Password"];
verifyCardInfoRequest.CardID = txtCardID.Text;

<!--Call the VerifyCardInfo web method -->
HCService.HCService hcService = new HCService.HCService();
HCService.CardInfoInfoResponse response = hcService.VerifyCardInfo(verifyCardInfoRequest);
<!--get the information from the response-->
this.lblVerifyInfo.Text = "ResponseCode=" + response.ResponseCode + "<BR/>";
this.lblVerifyInfo.Text += "Status=" + response.Status + "<BR/>";
this.lblVerifyInfo.Text += "StatusMessage=" + response.StatusMessage + "<BR/>";
this.lblVerifyInfo.Text += "DisplayMessage=" + response.DisplayMessage + "<BR/>";
this.lblVerifyInfo.Text += "Token=" + response.Token + "<BR/>";
this.lblVerifyInfo.Text += "CardUsage=" + response.CardUsage + "<BR/>";
this.lblVerifyInfo.Text += "CardType: " + response.CardType + "<BR/>";
this.lblVerifyInfo.Text += "OperatorID: " + response.OperatorID + "<BR/>";
this.lblVerifyInfo.Text += "TransPostTime: " + response.TransPostTime + "<BR/>";
this.lblVerifyInfo.Text += "Masked Acct: " + response.MaskedAccount + "<BR/>";
this.lblVerifyInfo.Text += "Cardholder Name: " + response.CardholderName + "<BR/>";
this.lblVerifyInfo.Text += "Tran Type: " + response.TranType + "<BR/>";
this.lblVerifyInfo.Text += "CardInfo ID
Expired: " + response.CardIDExpired.ToString() + "<BR/>";
Figure 23. Sample Code: VerifyCardInfo Web Method
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 33 of 118
2014 Mercury

Tokenization (MToken)
General Overview
MToken is Mercurys proprietary technology that replaces sensitive card data with non-sensitive reference data for
long-term data storage. It has become popular as a means of reducing the risk, cost, and complexity of credit card
processing. The actual card number is used only when submitted by the user on the HostedCheckout web page.
After the transaction is processed by HostedCheckout the token is retrieved using the VerifyPayment or
VerifyCardInfo web methods. The token can be used to perform subsequent transactions for the same card. This
can be used for capturing a PreAuth, voiding or reversing a transaction in the current batch, returning a previous
transaction, card-on-file, or recurring billing.
MercuryPay
TM
MToken Specifications
Initial token request: <Token> and <Frequency>
Tokens are unique reference records generated by Mercury for all credit transactions. A token is returned in the
VerifyPayment or VerifyCardInfo response. In the event of a decline/error response, no token is generated.
The token is used in subsequent transactions against the Transaction Web Service. With each transaction call, a
new token will be sent back in the response.
The developer should use appropriate precautions when storing a token:
Only store a token if there is a business need and if this
information supports your targeted business/merchants.
Note that although AVS data may be stored as non-
sensitive card data, it is important to remember that CVV
data may never be stored.
Never store a token if there is not a business need.
Build in retention and expiration timelines for any stored token record. Note that because of truncated card
expiration data returned in the token response, developers should, if needed, obtain the expiration date prior
to processing the request.
Always dispose of expired tokens.
A new token will always be returned with each subsequent transaction associated with a particular card
number. Therefore, if storing token data, always store only the most recent token returned and dispose of all
previous tokens.
The <Frequency> element has two options:
1. OneTime token used in subsequent transactions and card-on-file.
The maximum life-span until a OneTime token expires is approximately 6 months from the date the token is
generated.
2. Recurring tokens used for recurring billing.
The maximum life-span until a Recurring token expires is approximately 24 months from the date the token
record is generated.
Note A token generated for OneTime use cannot be used for Recurring; a token generated for Recurring use
cannot be used for OneTime.
Element Req Min Max Type Description
Transaction: Token Y 1 100 AN Used in subsequent transaction as the actual token
returned from Mercury
Transaction: Frequency Y 1 20 AN Type of Token requested: OneTime or Recurring
TransResponse: Token Y 1 100 AN Token record returned from Mercury
Figure 24. Token Transaction Elements
Note <Frequency> values must stay consistent in all subsequent MToken requests. For example, a OneTime
Sale request must be followed with a OneTime VoidSaleByRecordNo Request or a Recurring PreAuth request can
- Recommendation
Developers should build in provisions to
securely handle, store and maintain
Token Records.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 34 of 118
2014 Mercury

only be followed by a Recurring PreAuthCaptureByRecordNo request. Inconsistent usage of Frequency will cause
the subsequent transaction request to fail with the following error: Error # 004119 - Token Service Unavailable. -
200 Response With Status: Failure Message: Parse token failure.
Using Tokenization for Merchant environments requiring recurring billing
The initial and subsequent use of tokens requested for recurring billing purposes follows the same guideline except
that the initial frequency is requested as Recurring. Recurring token records expire after 2 years. It is important to
have provision in place to store token records appropriately and to always store only the most recently returned
token data.
Downgrade Note Always use a valid transaction or CardInfo Lookup to generate a token. Sending an un-
captured PreAuth as a way of receiving a token constitutes a misuse of the authorization network and causes
additional fees generated by the card associations.
Multiple-Merchant Tokenization (MMT)
MMT enables a single business entity with multiple locations to use Mercury's MToken platform across all of their
locations if:
they all share common ownership attributes (legal name, Tax ID and owner), and
they have a centrally housed, cross-location database infrastructure in place to support it.
Tokens are tied to merchant locations and can only be used in MMT situations if they are grouped. Upon
request, Mercury's Underwriting account specialists can authorize the creation of an MMT grouping that allows
token sharing from one location to another. In most cases this will be implemented at the merchant level without
issue, but there are safeguards in place to prevent inadvertent users of MMT outside the prescribed group. For
example, if ungrouped Merchant A tries to redeem a token issued from grouped Merchant B, Merchant A
would receive a response of Token Invalid.
Subsequent Token Transaction Calls using Transaction Web Service
There are eight Token calls available to a developer in the Transaction Web Service (examples of each are provided
on the following pages):
Token Call
Description
1. CreditPreAuthToken
For Recurring billing and card-on-file transactions
2. CreditPreAuthCaptureToken
For finalizing a PreAuth
3. CreditSaleToken
For Recurring billing and card-on-file transactions
4. CreditAdjustToken
For adjusting the amount of the original Sale or PreAuthCapture.
5. CreditVoidSaleToken
For voiding a Sale or PreAuthCapture transaction in the current batch
6. CreditReversalToken
For reversing PreAuth, PreAuthCapture, and Sale transactions*
7. CreditReturnToken
For returning a previously ran transaction
8. CreditVoidReturnToken
For voiding a Return transaction in the current batch
Figure 25. Token Transaction Calls using Transaction Web Service
*HostedCheckout now supports PreAuth Reversals (CreditReversalToken). This transaction allows a PreAuth to
be reversed in cases where the PreAuth wont be captured. This keeps the funds from being held on the card
holders account. (This transaction requires the addition of the AcqRefData and ProcessData from the PreAuth
response.)
The TransactionService web service is available through the following URLs:
HostedCheckout Credit URLs
Development URL TransactionService: https://hc.mercurydev.net/tws/transactionservice.asmx
Production URL TransactionService: https://hc.mercurypay.com/tws/transactionservice.asmx
Each of these transactions require a token and the merchants HostedCheckout password. See the examples of
each call shown at the bottom of each section.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 35 of 118
2014 Mercury

If the transaction is not formatted correctly, you will receive an error message of Your XML is invalid. Check your
XML syntax and refer to the Integration Guide." This can be caused by a misspelled tag, a tag name that has
incorrect case, a bad namespace, or just malformed xml.
For each of these transactions, a Credit Response structure is returned (see the Credit Response Returned Values
for a list of the returned values). The structure is the same for each transaction, although some values will be
blank if they are not applicable.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 36 of 118
2014 Mercury

1. CreditPreAuthToken
CreditPreAuthToken Input Parameters
Parameter Type Length Description Required
Address String 8 CardHolder Billing Address. If provided will be used for Address
Verification.
No
CardholderName String 30 Customer Card Holder Name as it appears on card. No
CVV Numeric 3 or 4 Card Verification Value from back of credit card. Used for card
verification
No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. It will be used for
both the Invoice and the RefNo fields when the pre-auth is
submitted. Invoice Number must be unique.
Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID

Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID No
Amount Double The initial amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
TerminalName String 20 Terminal Name No
Token Numeric 100 The token generated by a PreAuth transaction that replaces the
credit card #. Can be used in subsequent transactions.
Yes
Zip String 5 or 9 Cardholder Zip. If provided, will be used for address verification. No
Figure 26. CreditPreAuth Token Input Parameters
CreditPreAuthToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditPreAuthToken preAuthRequest = new
TransactionService.CreditPreAuthToken()
{
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "OneTime",
Amount = 9.00,
MerchantID = 013163015566916,
Invoice = 12345,
TerminalName = "",
OperatorID = "",
Memo = "MPS WebServer v1.0.0",
Address = 4 Corporate Square,
Zip = 30329,
CardHolderName = Carolyn Anderson,
CVV = "123",
};

string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditPreAuthToken(preAuthRequest,
password);
Figure 27. Code Example: CreditPreAuth Token

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 37 of 118
2014 Mercury

2. CreditPreAuthCaptureToken
CreditPreAuthCaptureToken Input Parameters
Parameter Type Length Description Required
AcqRefData String 200 Acquirer Reference Data Yes
AuthCode String 16 The Authorization code. Yes
AuthAmount Double The amount authorized for the transaction. Two decimal places
are required. Must match the AuthorizeAmount that was sent
in the PreAuth. Format is 99999.99.
Yes
CardHolderName String 30 The name on the card No
CustomerCode String 16 The customer code No
Frequency String 9 OneTime or Recurring Yes
GratuityAmount Double The gratuity amount of the order. Two decimal places are
required. If there is no gratuity amount, pass 0.00. Format is
99999.99.
Yes
Invoice String 16 Invoice Number from the eCommerce site. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID No
PurchaseAmount Double The amount authorized for the transaction. Two decimal places
are required. Must match the Amount that was sent in the
PreAuth. Format is 99999.99.
Yes
TaxAmount Double The tax amount of the order. Two decimal places are required.
If there is no tax amount, pass 0.00. Format is 99999.99.
No
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth transaction that replaces the
credit card #. Can be used in subsequent transactions.
Yes
Figure 28. CreditPreAuthCaptureToken Input Parameters
CreditPreAuthCaptureToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditPreAuthCaptureToken preAuthCaptureRequest = new
TransactionService.CreditPreAuthCaptureToken()
{
AcqRefData = KbMCC1757080329,
AuthCode = 12345,
AuthAmount = 9.00,
CardHolderName = Carolyn Anderson,
CustomerCode = CUSTCODE1,
Frequency = "OneTime",
GratuityAmount = 1.00,
Invoice = 12345,
Memo = " MPS WebServer v1.0.0",
MerchantID = 013163015566916,
OperatorID = "",
PurchaseAmount = 9.00,
TaxAmount = .62,
TerminalName = "",
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
};
string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response =
ts.CreditPreAuthCaptureToken(preAuthCaptureRequest, password);
Figure 29. Code Example: CreditPreAuthCaptureToken
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 38 of 118
2014 Mercury

3. CreditSaleToken
CreditSaleToken Input Parameters
Parameter
Name
Type Length Description Required
Address String 8 CardHolder Billing Address. If provided will be used for Address
Verification.
No
Cardholder
Name
String 30 Customer Card Holder Name as it appears on card. No
CustomerCode String 16 The customer code. No
CVV Numeric 3 or 4 Card Verification Value from back of credit card. Used for card
verification
No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID No
PartialAuth Boolean 5 Set to true to allow partial authorization. Default is false. No
PurchaseAmount Double 8 The total amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
TaxAmount Double 8 The tax amount of the order. If there is no tax for the
transaction, set to 0.00. Format is 99999.99.
Yes
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth transaction that replaces the
credit card #. Can be used in subsequent transactions.
Yes
Zip String 5 or 9 Cardholder Zip. If provided, will be used for address verification. No
Figure 30. CreditSaleToken Input Parameters
CreditSaleToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditSaleToken saleRequest = new
TransactionService.CreditSaleToken()
{
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "Recurring",
PurchaseAmount = 9.00,
TaxAmount = .72,
MerchantID = 013163015566916,
Invoice = 12345,
TerminalName = "",
OperatorID = "",
Memo = "Sale Test",
Address = 4 Corporate Square,
Zip = 30329,
CardHolderName = Carolyn Anderson,
CustomerCode = cust1042,
CVV = "123",
};

string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditSaleToken(saleRequest,
password);
Figure 31. Code Example: CreditSaleToken

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 39 of 118
2014 Mercury

4. CreditAdjustToken
CreditAdjustToken Input Parameters
Parameter Type Length Description Required
AuthCode String 16 The Authorization code. Yes
CardHolderName String 30 The name on the card No
CustomerCode String 16 The customer code No
Frequency String 9 OneTime or Recurring Yes
GratuityAmount Double The gratuity amount of the order. Two decimal places are
required. If there is no gratuity amount, pass 0.00. Format is
99999.99.
Yes
Invoice String 16 Invoice Number from the POS. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID. Alphanumeric. Yes
PurchaseAmount Double The amount of the order to charge the cardholder not including
gratuity. Two decimal places are required. Format is 99999.99.
Yes
RefNo String 16 The reference number returned to the developer in the
response of the Sale or PreAuthCapture transaction.
Yes
TaxAmount Double The tax amount of the order. Two decimal places are required.
If there is no tax amount, pass 0.00. Format is 99999.99.
No
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a Sale or PreAuthCapture transaction
that replaces the credit card #. Can be used in subsequent
transactions.
Yes
Figure 32. CreditAdjustToken Input Parameters
CreditAdjustToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditadjustToken AdjustRequest = new
TransactionService.CreditAdjustToken()
{
AuthCode = 12345,
AuthorizeAmount = 9.00,
CardHolderName = Carolyn Anderson,
CustomerCode = CUSTCODE1,
Frequency = "OneTime",
GratuityAmount = 1.00,
Invoice = 12345,
Memo = " MERCURY WebServer v1.0.0",
MerchantID = 013163015566916,
OperatorID = "Bob67",
PurchaseAmount = 9.00,
TaxAmount = .62,
TerminalName = "",
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
};

string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditAdjustToken(AdjustRequest,
password);
Figure 33. Code Example: CreditAdjustToken





Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 40 of 118
2014 Mercury


5. CreditVoidSaleToken
CreditVoidSale Token Input Parameters
Parameter Type Length Description Required
AuthCode String 16 The Authorization code Yes
CardHolderName String 30 The name on the card No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID. Alphanumeric. No
PurchaseAmount Double The total amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
RefNo String 16 The reference number returned to the developer in the
response of the Sale or PreAuthCapture transaction or the
InvoiceNo from a PreAuth for reversal.
Yes
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth, PreAuthCapture, or Sale
transaction that replaces the credit card #. Can be used in
subsequent transactions.
Yes
Figure 34. CreditVoidSaleToken Input Parameters
CreditVoidSaleToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditVoidSaleToken saleRequest = new
TransactionService.CreditVoidSaleToken()
{
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "OneTime",
PurchaseAmount = 9.00,
MerchantID = 013163015566916,
Invoice = 12345,
RefNo = 004,
TerminalName = "",
OperatorID = "Bob67",
AuthCode = "Xyie123xP,
Memo = Void Sale Test;
CardHolderName = Carolyn Anderson,
};
string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditVoidSaleToken(saleRequest,
password);
Figure 35. Code Example: CreditVoidSaleToken



Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 41 of 118
2014 Mercury

6. CreditReversalToken*
CreditReversalToken Input Parameters
Parameter Type Length Description Required
AuthCode String 16 The Authorization code Yes
CardHolderName String 30 The name on the card No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the POS. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID. Alphanumeric. No
PurchaseAmount Double The total amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
RefNo String 16 The reference number returned to the developer in the
response of the Sale or PreAuthCapture transaction or the RefNo
filler from the PreAuth.
Yes
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth transaction that replaces the
credit card #. Can be used in subsequent transactions.
Yes
AcqRefData String 200 Acquirer Reference Data that was received in the response of
VerifyPayment, CreditSaleToken, CreditPreAuthToken, or
CreditPreAuthCaptureToken transaction.
Yes
ProcessData String 200 Process Data that was received in the response of
VerifyPayment, CreditSaleToken, CreditPreAuthToken, or
CreditPreAuthCaptureToken transaction.
Yes
Figure 36. CreditReversalToken Input Parameters
* For additional information, see PrePaid Partial Authorization and Real-Time Reversal Support later in this
document.
CreditReversalToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditReversalToken saleRequest = new
TransactionService.CreditReversalToken()
{
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "OneTime",
PurchaseAmount = 9.00,
MerchantID = 013163015566916,
Invoice = 12345,
RefNo = 004,
TerminalName = "",
OperatorID = "Bob67",
AuthCode = "Xyie123xP,
Memo = Void Sale Test;
CardHolderName = Carolyn Anderson,
AcqRefData = KbMCC1049210708 ,
ProcessData = |17|210100700000,

};
string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditReversalToken(saleRequest,
password);
Figure 37. Code Example: CreditReversalToken

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 42 of 118
2014 Mercury

7. CreditReturnToken
CreditReturn Token Input Parameters
Parameter Type Length Description Required
CardHolderName String 30 The name on the card No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID. Alphanumeric No
PurchaseAmount Double The total amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth transaction that replaces the
credit card number. Can be used in subsequent transactions.
Yes
Figure 38. CreditReturnToken Input Parameters
CreditReturnToken Example
TransactionService.TransactionService ts = new
TransactionService.TransactionService();
TransactionService.CreditReturnToken request = new
TransactionService.CreditReturnToken()
{
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "OneTime",
PurchaseAmount = 9.00,
MerchantID = 013163015566916,
Invoice = 12345,
TerminalName = "",
OperatorID = "Bob67",
Memo = Void Sale Test;
CardHolderName = Carolyn Anderson,
};

string password = vNxE:r_CZNaHmkb^;
TransactionService.CreditResponse response = ts.CreditReturnToken(request,
password);
Figure 39. Code Example: CreditReturnToken
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 43 of 118
2014 Mercury

8. CreditVoidReturnToken
CreditVoidReturnToken Input Parameters
Parameter Type Length Description Required
AuthCode String 16 The Authorization code Yes
CardHolderName String 30 The name on the card No
Frequency String 9 OneTime or Recurring Yes
Invoice String 16 Invoice Number from the eCommerce site. Yes
Memo String 40 The Memo tag is the product name and version number of the
developers software.
Yes
MerchantID Numeric 24 The Merchants account or MerchantID that payments will be
processed under.
Yes
OperatorID String 16 Operator ID. Alphanumeric. No
PurchaseAmount Double The total amount of the order to charge the card holder. Two
decimal places are required. Format is 99999.99.
Yes
RefNo String 16 The reference number of the transaction returned in the original
PreAuthCapture or Sale response.
Yes
TerminalName String 20 Terminal Name No
Token String 100 The token generated by a PreAuth transaction that replaces the
credit card number. Can be used in subsequent transactions.
Yes
Figure 40. CreditVoidReturnToken Input Parameters
CreditVoidReturnToken Example
TransactionService.TransactionService target = new TransactionService.TransactionService();

CreditVoidReturnToken voidReturnToken = new CreditVoidReturnToken()
{
Memo = "CreditVoidReturnToken Test",
Token = J9yQO+wyBWS7GlA7TarjDtqzxk7DEOHDMhAFEAASNB0uYA==,
Frequency = "OneTime",
PurchaseAmount = 9,
MerchantID = 013163015566916,
Invoice = "12345",
TerminalName = "",
OperatorID = "Bob67",
AuthCode = "123456",
CardHolderName = "Carolyn Anderson",
RefNo = "004",
};

string password = vNxE:r_CZNaHmkb^;

CreditResponse response = target.CreditVoidReturnToken(voidReturnToken, password);
Figure 41. Code Example: CreditVoidReturnToken


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 44 of 118
2014 Mercury

CreditResponse - Returned Values
These are the values returned for all of the above token transactions (CreditPreAuthToken,
CreditPreAutCaptureToken,CreditSaleToken,CreditReturnToken,CreditVoidSaleToken,CreditVoidReturnToken,
CreditReversalToken).
Parameter Type Length Description
Account String 12 The masked account number used for the transaction.
AcqRefData String 200 Acquirer Reference Data
AuthCode String 16 Authorization code.
AuthorizeAmount Numeric 8 The amount that the transaction was authorized for. If this amount is less
than the PurchaseAmount field, then payment in full has not been
received and additional tender will need to be requested.
AVSResult String 40 The result of the AVS check. AVSResult codes are in the Platform
Integration Guide and there is a different list per card type.
BatchNo String 6 Batch # of transaction if applicable
CardType String 40 Type of card used to make the payment
CvvResult String 40 Result of the CVV check.
M=match
N=no match
P=not processed
S=CVV should be on card but merchant indicated it is not present
(Visa/Discover only)
U=Issuer is Not Certified, CID not checked (AMEX only)
GratuityAmount Numeric 8 Tip (gratuity) amount (with 2-place decimal e.g., 5.00)
Invoice String 16 Invoice # of the transaction
Message String unlimited Transaction status message or concatenated validation error messages.
PurchaseAmount Numeric 8 Purchase price (with 2-place decimal e.g., 29.25)
RefNo String 16 Transaction Reference Number
Status String 19 The status of the transaction. The Message field contains additional
information.
Approved. The transaction was approved.
Declined. The transaction was declined.
Error. A transaction processing error occurred.
AuthFail. Authentication failed for MerchantID/password.
MercuryInternalFail. An error occurred internal to Mercury.
ValidateFail. Validation of the request failed. See Message for validation
errors.
Token String 100 The token generated by the transaction that replaces the credit card #.
Can be used in subsequent transactions.
ProcessData String 200 ProcessData
Figure 42. CreditResponse - Returned Values





Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 45 of 118
2014 Mercury

Special Considerations for eCommerce Solutions
eCommerce Card Data Storage Using MToken
Ecommerce merchants that ship merchandise beyond a 24-hour period must support PreAuth/PreAuthCapture
transaction types and are required to implement tokenization support for secure storage and subsequent usage of
card data. These integrations need to store and maintain token data (RecordNo, Frequency) and AuthCode,
AcqRefData appropriately for subsequent use. Accordingly, CVV/AVS Data used for the PreAuth must not be retained
for any length of time.
Required Transactions
HostedCheckout integrations must support PreAuth, PreAuthCapture, and Return transaction types (although in
integrations where there is an immediate exchange of merchandise within 24 hours of purchase, Sales and Returns
transaction types can be substituted).
<Memo Tag> - Software Product and Version
The Memo data element should be coded dynamically in all transaction requests; it is used to identify the software
model and version. This use of the Memo tag is a certification requirement.
CVV and AVS data
For security reasons in a card-not-present environment, and for the best qualifying processing rates, eCommerce
credit integrations are highly recommended to include AVS (Address/Zip Verification) and CVV2/CVC2 data in the
transaction request. Though a failed AVS or CVV match will not always result in a declined response, it is important to
code in options for proceeding with the transaction in the event of an AVS/CVV mismatch. For more information, see
Utilizing CVV and AVS later in this document.
eCommerce Website Requirements
Before a business can be approved to process eCommerce transactions, it must have a valid website with the
requirements listed below. Should the products or services offered through an eCommerce merchant account
change, Mercury must be notified immediately. A merchant that currently has a retail or MOTO account with
Mercury must submit an entirely separate application for eCommerce. Mercury issues eCommerce merchants
unique Merchant ID numbers upon underwriting approval.
The following eCommerce policies and procedures have been established to comply with Visa, MasterCard,
Discover and Mercury regulations:
1. Product(s) Sold. Ecommerce merchants must maintain a valid website with complete descriptions of the
products and services sold. All federal and state laws apply in addition to the card association regulations
regarding all products and services sold.
2. Security Policy. Ecommerce merchants must submit transactions for authorization and settlement through a
secure online gateway. The security protocols used to protect a customers information must be disclosed.
3. Privacy & Return Policy. The website must contain a return, refund and privacy policy. Terms of Use or Terms
and Conditions must also be properly disclosed on the website.
4. Delivery Policy. Ecommerce merchants set their own policies and restrictions regarding delivery of goods. Any
restrictions on delivery must be clearly stated on the website.
5. Customer Service Contact. Contact information for your business must be easily accessible to customers. It
must show a physical address along with an electronic mail address and telephone number.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 46 of 118
2014 Mercury

6. Card Acceptance Brand Marks. Full-color brand marks are required by Visa, MasterCard and Discover. The
American Express logo must be displayed if accepted. See the following websites for more information:
http://usa.visa.com/merchants/marketing_center/logo_usage.html
http://www.mastercardbrandcenter.com/us/index.shtml
http://www.discovernetwork.com/clientsupport/signageacceptance.html
https://www209.americanexpress.com/merchant/marketing-data/pages/logosandsupplies
eCommerce Best Practices
1. Shipping and Delivery. The shipping method, time frame and delivery procedures should be clearly stated.
After the payment has been accepted, the product must ship immediately. The customer cannot be charged
unless the product is in inventory and ready to ship.
2. Transaction Receipt. A transaction receipt via electronic mail should be provided to the customer and must
include your business name, web address, contact information and the terms and conditions of the sale.
Always keep the transaction receipt, shipping record (UPS, Airborne, FedEx or USPS) and proof-of-delivery on
file. This information will need to be presented in the event of a chargeback.
3. Transaction Verification. AVS (the Address Verification System) should be used to validate the billing address
of the cardholder. Use the Card Verification Value (CVV2) to further validate the transaction.
4. Suspicious Transactions. It is highly recommended to develop in-house policies and procedures for handling
irregular or suspicious transactions and provide appropriate training for sales staff. Any order that seems
suspicious should be further investigated. Contact the cardholder for verification. Orders that fail AVS or CVV2
validation should be flagged for research. If an order is high-risk or possibly fraudulent, void the transaction
immediately. Shipping orders that are not validated by AVS or CVV2 could result in chargebacks and loss of
merchandise. All eCommerce merchants should be extremely suspicious of international orders. Some
geographic areas have a higher frequency of fraud and black market stolen credit card information.
Additional policies and procedures should be put into place to monitor the following types of orders:
rush orders,
random orders (orders not specifying color, size, etc.),
shipping address not the same as billing address,
shipments to post office boxes or business addresses,
transactions associated with anonymous email addresses or
orders from internet addresses at free email services.
5. Acknowledgement of Policies. Policies should require a cardholder to click to accept them. Not doing so
leaves merchants open to claims by the cardholder that they were not aware of the merchants policies at the
time of the transaction.
For More Information on Best Practices for eCommerce Transactions:
http://usa.visa.com/download/merchants/card-acceptance-guidelines-for-visa-merchants.pdf

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 47 of 118
2014 Mercury

Handling Errors in eCommerce Transactions
General Response
Categories TextResponse
Suggested Verbiage for
Response Remarks
Invalid Credentials/MID
Merchant ID not Found
Response due to
configuration error
INVLD MERCH ID,
INVLD CREDENTIALS
MERCHANT ID NOT FOUND,
MerchantID not found (Gift)
Invalid TranType for Prepaid
Server
Web Site Application Error.
Please Contact ###-###-####

Send corresponding email alert
notification to Gateway
admin/merchant.
Communication,
Connectivity and Socket
Response Errors

EDC UNAVAILABLE,
DB UNAVAIL,
TIMEOUT ON RESPONSE,
TIMEOUT WAITING FOR
RESPONSE,
MAX CONNECTION ERROR,
SOCKET CONNECTION FAILED,
NO CONNECTION TO ANY
SERVER,
HOST UNAVAIL,
ISSUER UNAVAIL
Were sorry. We are
experiencing a temporary
connectivity error. Please try
again.

Transaction Level:
Approvals
AP,
AP*,
AP NEW INFO
APPROVED STANDIN
AP-NOT CAPTURED
Approved, Successful!
Transaction Level:
Declines
DECLINED,
OTHER NOT EXCEPTED,
PIC UP,
EXCEEDS MAX AMT,
DECLINE TRY LATER
Were sorry, your
transaction has declined.

Transaction Level Declines:
Invalid Data Errors
INVLD ACCT,
INVALID EX DATE,
INVALID REFERENCE
NUMBER,
INVLD TRAN CODE,
INVALID FIELD: ______.
Your account information
has been entered incorrectly.
Please try again.

Maximum 3 retries.
Transaction Level Declines:
Duplicate Transaction
(AP*-- signifies duplicate logic
detected duplicate and did
not charge the card twice)
AP DUPE
Duplicate transaction data
has been entered.
Transaction declined.

Transaction Level Declines:
Call Referrals
CALL AE,
CALL DISCOVER,
CALL ND,
CALL XXXX
Your transaction has
declined: please contact us at
###-###-#### to complete
your transaction.

Verification Result codes:
CVV

M=CVV Match
N=CVV no Match
P=Not Processed
DECLINED-CV2 FAIL
Your information has been
entered incorrectly. Please
verify and try again.

Maximum 3 retries, or
Auto-void upon CVV fail
response of N, or
base void on established
criteria as in >$300.00
Note Mercury
recommends coding provisions
for Merchant level
configurable attributes.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 48 of 118
2014 Mercury

General Response
Categories TextResponse
Suggested Verbiage for
Response Remarks
Verification Result codes:
AVS
(AVS Varies by card brand, all
single digit alpha characters)
See Figure 46 for a list of
AVS Response Codes.
Your information has been
entered incorrectly. Please
verify your retry.

Maximum 3 retries
Settlement Response Codes OK,
INV BAL/SETL,
MUST BAL NOW
Merchant/Shopping
Cart/Gateway level only
Gift Card (PrePaid) Error
Responses

Invalid Account Number
Account not Issued
Account Expired
Account Already Issued
Issuance not Authorized
Insufficient Account Balance
Mag Stripe Error-Hand Key
Amount Exceeds Maximum
Return Not Allowed
Account Deactivated
Number of Returns on Card
over Limit
Account in Use
Could not VoidIssue
Were Sorry, your
transaction has declined: xxx.


All gift transaction error
verbiage may be passed as-is,
replacing the xxx.


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 49 of 118
2014 Mercury

Additional Processing Features
MercuryStand-In
TM
Authorization
Overview
MercuryStand-In
TM
is a proprietary emergency backup feature used to provide uninterrupted processing if the back-
end processing networks experience an outage. If an outage occurs, Mercurys platform architecture has the ability to
temporarily stand in for the back-end networks, and issues a provisional authorization code in place of an issuer-
generated authorization. These authorization codes are issued as MERCXX. All MERCXX transactions are additionally
marked with a provisional TextResponse of APPROVED STANDIN. Once out of Stand-In and processing returns to
issuer-generated authorizations, Mercury re-submits the MERCXX/APPROVED STANDIN transactions to the back-end
networks to secure actual, issuer-generated AuthCodes.
Figure 43. Illustration of the Three Phases of Stand-In
Handling Stand-In in your Application
Though seldom seamless, Stand-In related complications experienced by merchants can be greatly reduced by
understanding the three phases of Stand-In (normal processing, Stand-In, and post Stand-In), and how to build in
simple provisions to manage a transaction that originates in one phase but needs to be completed in another. How
your application should respond to Stand-In depends on your settlement method, the transactions your system
supports, and if your system handles tip modification or adjustments.
Note Encryption and Tokenization transaction processing are unaffected by Stand-In with one exception:
CardInfo will NOT return a token during Stand-In.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 50 of 118
2014 Mercury

For all Applications:
Code to accept the combination of provisional authorization indicators: AuthCode=MERCXX and
TextResponse=APPROVED STANDIN.
If Reversal-VoidSales are supported, code to accept the alternative TextResponse of APPROVED STANDIN (in
place of REVERSED) and AuthCode of VOIDED.
Do not alter your invoicing or duplicate procedures. Follow the same procedures that were used for your
certification.
By design, duplicate-checking functionality takes place during the post Stand-in phase as transactions are
resubmitted. If a transaction is submitted with the same card, amount and invoice, it will be treated as an
unintended duplicate and will not be charged to the card.
Additional Stand-In integration requirements based on the processing method used:
A) For systems that send both initial authorizations and final capture transactions to Mercury throughout the
business day (this is what Mercury terms Stream Capture):
For Time Initiated (auto settle) merchant environments, it is important to treat MERCXX/APPROVED
STANDIN transactions as legitimate authorizations and include them in the local batch reports. The stand-in
procedure remains transparent to the merchant. All approved MERCXX Stand-In generated authorizations
will be resubmitted to the Merchants current open batch during the Post Stand-In phase with actual, issuer
generated authorizations.
For Merchant Initiated environments supporting a local initiated batch close, it is important that merchants
continue processing as normal. Referenced transactions (i.e., PreAuthCapture, VoidSale or Adjust) should be
requested using the Stand-In response data to ensure that the proper authorization amounts (e.g., gratuity)
are finalized and funding is made available to the merchant.
Once normal processing has resumed, Mercury will process the MERCXX transactions back into the
merchants open batch as quickly as possible. However, after a Stand-In event merchants may find that
their batch summaries do not match when comparing them to Mercurys records. It is important that a
mechanism be put in place that allows the batch to be forced closed if required. The time it will take
for Mercury to re-submit transactions for issuer-generated authorization may vary from a few hours to
a few days. The timeframe depends on the length of the Stand-In event, where in the Stand-In event the
transaction was logged, and, very importantly, if the merchant can force-close their batch.
Mercury recommends that developers always provide a force-close option to their merchants. This
will enable merchants to close their batch when their local batch totals are out of balance with the
batch totals held at Mercury.
Merchants should follow the steps below after a Stand-In event:
1. Run a BatchSummary and compare the local
totals to the batch totals held at Mercury. If
all of the MERCXX transactions were
processed successfully, the totals will match
and the BatchClose can be requested.
2. If the totals do not match, make note of any
differences, compare these differences with
the MERCXX transactions, and force a
BatchClose.
3. The following day, run another BatchSummary to see if all of the MERCXX transactions have been
captured. If so, close the batch. If not, repeat step 2.
Continue following steps 1-3 each day until all of the MERCXX transactions have been captured, then close
the batch in the normal way.

- Recommendations
Flag all MERCXX transactions processed
in a batch.
Provide messaging to the merchant to
help them reconcile their batches after
a Stand-In event.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 51 of 118
2014 Mercury

Notes
If the merchant continues to have batch reconciliation discrepancies, Mercury Technical Support
should be contacted.
It is important to understand some approved MERCXX transactions will decline at the issuer level. If
this happens, Mercury will not place the transaction into the merchants batch. Instead, we will fund
these transactions separately.
B) For systems that send pre-authorizations to Mercury throughout the day and send a BatchClose at their end-of-
day to capture transactions along with additional gratuity adjustments or voids (this is what Mercury terms Batch
Capture):
1. The MERCXX pre-authorizations should be captured the same way as normally authorized transactions. Only
the non-MERCXX transactions should be included in the batch close total and item count.
2. It is very important to upload every finalized transaction before the BatchClose. Mercury can only process
MERCXX transactions after the batch is closed. These transactions will be included in a separate batch on a
secondary internal Mercury TID associated with the merchant account.
Important Stand-In Information to share with your Merchants and Resellers
Stand-In events are rare and happen only when communication to the processing networks is interrupted.
The value of MercuryStand-In is that it optimizes processing up-time for any merchant using your application
with Mercury.
The use of the MERCXX and APPROVED STANDIN provides easy identification for local reconciliation and when
using Mercurys online merchant transaction reporting tools.
During Stand-In, BatchSummary/BatchClose functions are unavailable. If these are attempted during Stand-In,
the response is Host UNAVAIL - TRY LATER.
As a part of the Post-Stand-In phase, approved MERCXX transactions are deposited to the merchants bank
account, although the timeframe for funding can be delayed.
Funding records are made available to merchants in MercuryViews Daily Deposits and Settlement reports (DDS).
The DDS is a valuable accounting tool that can be used to confirm the Post-Stand-In phase has successfully
funded the MERCXX transactions.
All Mercury merchants are assigned an average ticket amount called a floor limit. This is important to
understand because Mercury assumes the financial liability for the approved MERCXX transactions up to the
merchants floor limit.
In the event a MERCXX transaction declines in the Post-Stand-In phase and does not receive an actual, issuer-
generated authorization code, Mercury will not place these declined transactions into the open batch. These
transactions will be reviewed and funded separately and will not show in Daily Deposits and Settlement reports
(DDS).

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 52 of 118
2014 Mercury

Protection Against Duplicate Transactions
Mercurys duplicate logic screens for unintended duplicates within a current open merchant batch. This logic
incorporates the following variables:
Card number
Amount
Transaction Type
InvoiceNo
Avoiding duplicate transactions requires implementing an always-incrementing invoice logic. Use the Mercury
InvoiceNo field exactly as outlined below.
The one exception to this rule is in the event of a time-out response where the authorization response is
unknown. In this case, the merchant site should resubmit the exact same transaction request with the same
amount, same card number, and same invoice number.
If the transaction was not previously authorized, the response
data will include the standard approved or declined
processor's response.
If the transaction was previously authorized, the response
data will include a CmdStatus of APPROVED with the
additional TextResponse designation of AP* (reported as
Approved/AP DUPE). The second transaction will not be
charged.
When Mercury's duplicate checking recognizes the same card number, same amount, same transaction type and
same InvoiceNo within the same open batch, the duplicate checking assumes that the second transaction is an
unintended duplicate. The original authorization holds and the card is not charged twice. Mercury responds by
replacing the duplicated request with the original transaction informationAuthCode, AcqRefData, ProcessData,
RefNo, CVV and AVS Result data are all passed from the original response. Mercury passes the approval on to
the second duplicate transaction without charging the card a second time.
Important InvoiceNo and Duplicate Checking Specifications
InvoiceNo specification: Numeric only, incrementing 1-16 char in length BUT the right-ten characters must be
unique. The right ten are used for duplicate logic checking. No alpha characters, special characters or dashes.
Although there may be additional local uses for this field, developers are encouraged to strictly adhere to
these parameters and to use this field as an always-incrementing local transaction number with the one
rare exception of a time out.
Duplicate logic will fail if the application never sends an invoice number, always sends the same invoice such as
NOINVOICENO, or sends a zero-value: 0000.
If it is required to charge the same card again for the same amount, the application must submit a second
transaction with a new, unique invoice number.
The Duplicate Override tag is not required for U.S. processing. Duplicate Override is used in Canadian
processing as the duplicate logic only checks card number and amount in any current batch.

- Recommendation
Always send an incrementing InvoiceNo
with each transaction request except to
handle transaction timeouts. When a
timeout is received, resend the exact
transaction request.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 53 of 118
2014 Mercury

Handling Transaction Time-Outs
On rare occasions due primarily to connectivity-related issues, transaction requests can timeout while waiting for a
response, or timeout en route. Error responses will be returned depending on where in the transaction cycle the
communication failed.
When these connectivity errors are returned it is important to handle them effectively in order to avoid potential
duplicates. In these cases, the merchant is unsure whether the transaction was actually approved by the processor.
1. If the server (Mercury) did not get a response from the host (Global Payments), the transaction response will
show:
Status=Error
Message=Timeout on Response
2. If the client (merchants POS) did not get a response from the server (Mercury), the transaction response will
show:
Status=Error
Message=Timeout waiting for server Response
In these cases, it is unsure whether or not the transaction that was sent was actually approved by the processor.
Although the response indicates that the transaction failed to complete, in some cases it may have actually
completed.

- Recommendations
Developers should make provisions for timeouts, since it is inevitable that some small percentage of
transactions are going to be lost in transit. This problem is more significant when merchants have an unreliable
internet connection.
Upon receiving one of these timeout errors, the POS/POS operator should retry the transaction using the exact
same invoice number, card number, and amount.
PrePaid Partial Authorization and Real-Time Reversal Support
Real-time reversal support has been added to the HostedCheckout platform for better transaction handling in an
eCommerce environment. Though not required for card-not-present environments, this support allows PreAuth,
PreAuthCapture, and Sale transactions to be reversed, returning funds in real-time to the cardholders account as
long as their issuing bank supports it.
The <AcqRefData> and <ProcessData> values returned in the response will need to be stored for use with real-
time reversal functionality.
Real-Time Reversal Support using CreditReversalToken + <AcqRefData> and <ProcessData>
In the event a PreAuth needs to be reversed, a real-time reversal will be sent. Real-time reversals are supported by
Visa, MasterCard, and Discover cards. AMEX does not support real-time reversals at this time, but AcqRefData and
ProcessData can still be sent. It will be ignored by AMEX.
TranCode is CreditReversalToken
AcqRefData and ProcessData from the original transaction response needs to be provided in the Reversal
request. The AcqRefData and ProcessData fields are what trigger the Reversal to work in real time.
If reversing a PreAuth, RefNo value should equal the Invoice value from the original PreAuth.
If successful, the CMDStatus will be AP and the TextResponse will be REVERSED.
If an AP/REVERSED Status message is not returned in the reversal request, a CreditVoidSaleToken should be
immediately sent without the AcqRefData and ProcessData tags.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 54 of 118
2014 Mercury

Corporate Card Support: Level II data Tax and CustomerCode
For the lowest rates when processing business/commercial (corporate) cards it is necessary to supply Tax and
CustomerCode fields with all credit transactions. The use of this data lowers rates for retail and supermarket
merchants, but not restaurants. Level II Data also has nothing to do with Track2 Data.
Tax: Put the <Tax>9.99</Tax> tag in the Amount section of the XML request. The value format is numeric with 2
decimal places. Since the application already calculates the correct tax amount for each transaction, simply parse
the actual tax amount from the application into the Tax tag. The Purchase amount tag will be the total charge,
including tax. The tax field breaks out the tax amount for Level II reporting purposes only.
CustomerCode: Submit <CustomerCode>99999</CustomerCode>in the TranInfo section. The value should be
either the actual PO number, the merchants zip code, or the transaction invoice number. This is sufficient to
meet the Level II reporting requirements.
Using Card Security Codes (CVV) and Address Verification Data (AVS)
HostedCheckout provides the ability to enable or disable CVV and AVS (address and zipcode fields) on the
HostedCheckout page.
For CVV: values are on and off. Default is ON.
For AVS: Values are on, zip and off. Default is OFF.
For all ecommerce transactions, Card Security Codes (CVV/CVV2/CID) and Address Verification (AVS) data should
be supplied in the transaction request. Issuing bank result codes are returned in the transaction response along
with the card issuer authorization. The following information is provided for fine-tuning fraud prevention screening
based on these result codes. In the event of unauthorized credit card activity, it is critical to implement settings
that enable merchants to automatically respond to mis-matched or questionable card security codes and address
verification results.
! IMPORTANT NOTE
Card issuing banks may APPROVE a transaction but at the same time respond with a CVV or AVS No Match
response. Regardless if the issuing bank sends back an approval, if the CVV or AVS data indicate a no-match or
an otherwise questionable, potentially fraudulent result, ecommerce solutions should allow configurable
settings to automatically handle these result codes according to the merchants acceptable level of risk. The
appropriate corrective measure is determined by the merchants environment, the amount of the transaction,
how often the card is being used and, if applicable, any shipping/billing address mis-match. In other words,
Merchants can only prevent fraud and protect themselves from chargebacks if the solution they are using
supplies them the features to do so.
General "rules of thumb" actions are included below, but per card brand regulations, the variables that determine
the action are relative to the merchants environment. As such, AVS and Card Security Codes are important tools
used to help make business decisions on whether to proceed with a sale or delivery of goods and services. In all
cases of questionable or partial CVV or AVS results where the transaction is APPROVED by the issuing bank, your
solution should build in configurable merchant settings to automatically:
allow for the option to reject the transaction immediately by running a Reversal-VoidSale,
allow the option to both process a Reversal-VoidSale and to allow for reentry of the mis-matched data or
allow the option to accept the transaction authorization as is and by doing so, accepting the risk of the
potential fraudulent transaction.
Note To avoid phishing threats for CVV data it is recommended to allow no more than three attempts that
return a non-matching response.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 55 of 118
2014 Mercury

Card Verification Data
CVV2/CVC2 (Cardholder Verification Value)/CID (Amex and Discover)
CVV2 is a three- or four-digit code found only on the back of a card (for Amex it is on the front of the card), that is
used in eCommerce transactions to determine that the card is physically with the customer who is placing the order
(since the code can only be found on the card itself).
The table below lists the CVV Result codes along with rules of thumb recommendations for responding to each
code:

CVVResult
Code
Definition Explanation
Recommended Action
(Rules of Thumb)

M Match
The card security code supplied
matches the values on the card.
Complete transactions

N No Match
The card security code supplied does
not match the values on the card.
Reverse/Void and retry with updated
information (NOTE that Visa will DECLINE
for CV2 FAILURE so no need to Reverse).

*S
Should be
Present
The security code should be present
but the cardholder has reported that
it is not.
* This requires the CVV indicator be
submitted. Mercury currently does
not allow this to be configurable at
the merchant level.
Reverse/Void and ask for another form of
payment or Complete transaction

P
Not
Processed
The request was not processed. Reverse/Void the transaction and then
Retry

U
Not
Supported
The verification service is unavailable
or issuer does not support this
service.
Reverse/Void and ask for another form of
payment or Complete transaction
Figure 44. Card Verification Results Codes and Recommended Actions
CVV is not a factor in lowering Visa/MC costs, but Discover surcharges the merchant $0.50 for each manual
transaction submitted without CVV2/CID data.
Developer CVV Test Transaction Data
Use with MerchantID 595901 and only with test card 5499990123456781
Value: 123 / CvvResult: M ( = Match)
Value: 321 / CvvResult: N ( = No match)

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 56 of 118
2014 Mercury

Address Verification Service (AVS)
Cards that are swiped incur the lowest
processing rates. Mail, telephone and
eCommerce orders without cards present
incur higher rates as they are considered
higher risk. Though not impacting the
actual authorization approval, a better
processing rate is achieved for some
merchants (retail, QSR) if address
information is supplied when the card is not
swiped. This is referred to as Address
Verification Service (AVS).
Minimum AVS requirements include a
five digit ZIP code. Additionally the
numeric values of the credit card billing
address may be used. The nine digit zip
is also acceptable, no spaces or
hyphens allowed.
The AVS request data elements include AVSAddress and AVSZip. Example:
<mer:AVSAddress> 4Corporate Square </mer:AVSAddress>
<mer:AVSZip> 30329</mer:AVSZip>
The below example shows how this information is captured by Hosted Checkout:
Figure 45. Screenshot capturing CVV and AVS data
The AVS response will return a single alpha value indicating the quality of the match that was obtained (see the table
below for the list of values).
Not submitting AVS on keyed transactions affects processing cost in all merchant categories (SIC codes).
It is recommended to leave it up to the merchant to decide if non-matches should be accepted or reversed.
For better rates with Visa and MasterCard on keyed transactions, submit AVS, with at least the zip code.
For better rates with Discover on keyed transactions, submit AVS with street address and zip code.
For Amex, submit AVS with street address and zip code.

- Recommendation
AVS matching is only done on the numeric value of Address and
Zip fields. Always send the zip and then, optionally, address.
Never just send the address or send an address that starts with
alpha values such as PO Box.
Note Maximum length for the Address field is 20 characters,
alpha-numeric.
Although the match response has no effect on the transaction
approval, developers should make some provision to advise the
merchant of a bad AVS match so the merchant can opt to void
the transaction. The transaction is more likely to be a chargeback
risk for the merchant without a match. Although a matching
AVSResponse is not a guarantee in the event of a chargeback
dispute, it is a card brand best practice and does supply a higher
level of fraud protection.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 57 of 118
2014 Mercury

The AVSResult values and descriptions vary slightly from card brand:

Code VISA MasterCard DISC (MERCURY Platform) AMEX
A Address matches, Zip does not.
Address matches, postal
code does not
Address matches, Zip does not.
Billing address
only correct
B
Street address match. Postal code not
verified: incompatible formats

C
Street address and postal code not
verified: incompatible formats

D
Street Address and postal codes match
(International transactions)

G
Address information not verified for
International transaction

I
Address information not verified
(International transaction)

M
Street address and postal code match
(International transactions)

N No match
Neither address nor
postal code match
Nothing Matches
Billing address
and postal code
are both incorrect
P
Postal code match. Street address not
verified due to incompatible formats

R Retry; System unavailable or timed out
Retry: System unable to
process
Retry, system unable to
process.
System available:
Retry.
S

AVS currently not
supported
AVS not supported
SE not allowed
function
T

9-digit ZIP matches, address
does not

U
Address not verified. Issuer not AVS
participant or AVS data was present
but issuer did not return result.
No data from issuer/
authorization system
No data from
issuer/authorization system

W

For U.S. addresses, 9-digit
postal code matches,
address does not; for
address outside the U.S.
postal code matches,
address does not.
Nine-digit Zip Code matches,
address does not

X

For U.S. addresses, 9-digit
postal code and address
match; for address
outside the U.S. postal
code and address match
All digits match, nine-digit Zip
Code

Y Street address and postal code match
For U.S. addresses, 5-digit
postal code matches,
address matches.
All digits match 5-digit ZIP code
Yes, billing
address and
postal code are
both correct
Z
Postal/ZIP matches; street address
does not match not included
For U.S. addresses, 5-digit
postal code matches,
address does not.
5-digit ZIP code matches,
address does not
Billing postal code
only correct
Figure 46. AVS Response Codes

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 58 of 118
2014 Mercury

Developer AVS Test Data






Figure 47. AVS Test Information

CardType Test Card Number ExpDate
AVS Data
Address ZIP
MasterCard 5499990123456781 0513 4 30329
Visa 4003000123456781 0513 4 30329
Amex 373953244361001 0513 1661 85016
Discover 6011000997235373 0513 2500 60015
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 59 of 118
2014 Mercury



















A P P E N D I C E S
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 60 of 118
2014 Mercury

Appendix 1: MercuryGift Card Integration
Overview of MercuryGift
TM

MercuryGift
TM
is a locally-hosted gift processing platform designed to provide your system with a fully integrated
gift solution that can increase revenue, build merchant retention, and enhance the end-users experience.
Developers who integrate directly with MercuryGift benefit from value-added features including unlimited, free
gift card processing; online reconciliation and liability reporting through MercuryView; and multi-location account
management capabilities. Our comprehensive gift program features:
A specially trained gift sales force and technical agents working with your merchants to assist with
designing, ordering and distributing gift cards, building gift card ranges and offering
recommendations on how to make the most of the MercuryGift features.
Single and multi-store functionality with ACH disbursements is available.
A full range of supported gift transactions: Issue, Balance, Reload, Return, Sale, NoNSFSale and
Voids.
Quick integration turnaround: gift transaction XML and Web Services payload formats parallel credit
transaction formats for ease of integration coding. Examples are provided in the Appendix.
Online balance inquiry and history for gift card holders through mercury-gift.com.
Gift Card Processing Basics
The Gift Card Life Cycle
Mercurys gift cards are shipped without a specified value, which allows the merchant to issue the cards per the
request of the customer, or to use as a credit for returned merchandise.

Figure 48. The Gift Card Life Cycle
Mercurys gift transactions are built around simple Web Services SOAP-wrapped payloads using request and
response exchanges incorporating a set of common XML tags.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 61 of 118
2014 Mercury

All gift transactions use the transaction type of Prepaid (<TranType>PrePaid</TranType>) accompanied by the
corresponding transaction code (<TranCode>Issue</TranCode>). Other TranCodes include Sale, NoNSFSale,
Reload, Return, VoidIssue, VoidSale, VoidReload, VoidReturn and Balance. Details are provided later in this guide.
The first gift transaction processed on a new gift card is Issue. The Issue activates the card, sets the initial card
balance, and associates the card with the usage parameters on the Mercury Gift server. Once a card is activated
and put into use, it remains issued for the life of the card.
Gift cards can be used at the issuing merchant location or any associated locations as a form of tender. Use
Sale or NoNSFSale to reduce the available balance; use Reload or Return to add value to the available balance.
Mercury manages the available balance of all Issued gift card accounts. A balance value is always returned in
the transaction response. A balance inquiry can also be processed at any time locally by the merchant, online by
the cardholder or programmatically by the application.
A comprehensive reporting tool is available on the MercuryView portal.
Required and Supported Transactions
There are ten supported gift transactions: Issue, Sale, NoNSFSale, Reload, Return, VoidIssue, VoidSale, VoidReload,
VoidReturn and Balance. Although most developers choose to support the full range of gift transactions, at a
minimum, it is necessary to support:
Issue
NoNSFSale or Sale
Reload or Return
Balance
In addition to the above, it is recommended to also support gift card void functionality. For more information, see
the table on MercuryGift Transaction codes later in this guide.
Mercury Standard Issue Gift Card ranges
Mercurys gift card ranges are 19 digits long, starting with 6050110XXXXXXXXXXX. Encoding is Track2 format.
If validating gift cards, it is recommended to use the complete 6050110 so as not to be mistakenly compared to
Discover Card credit ranges.
Pre-Existing Cards and Third-Party Gift Cards
When a merchant has participated in another providers gift card program prior to processing with Mercury, they may
be able to use these cards with Mercury. Consider the following:
1. If the encoded magnetic stripe data contains more thanTrack2 data, it is important to parse out the Track2
string for processing to Mercury. If the encoded magnetic stripe data contains less than Track2 data, it may be
necessary to have Mercury re-encode the data to a compatible format.
2. Mercurys gift servers may be able to support the previously issued cards without having to physically re-
encode the magnetic stripes and/or reprint the card numbers. In order to determine this, please contact the
Mercury Gift department and arrange to provide four sample gift cards in sequence for evaluation.
If the pre-existing cards ARE compatible with Mercurys platform, Mercury can import these gift card
values. The merchant only needs to supply an Excel spreadsheet listing the card numbers and current
balances.
In the event that the pre-existing cards are NOT compatible with Mercurys platform, Mercury may be able
to re-encode the Track2 portion of the merchants cards.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 62 of 118
2014 Mercury

Chain or Franchise Merchant Gift Card Acceptance
If merchants are part of a larger chain or franchise, Mercury can group accounts together so they will be able to
perform Sale and Return transactions on cards that are issued by other members of their group. Reports are also
easily accessed that summarize these cross-merchant transactions, showing how much each store may owe to, and
be owed by, the other stores in the group.
Production and Development-Test Gift/Prepaid Servers
HostedCheckout Gift URLs
Development URL: https://hc.mercurydev.net/tws/transactionservicegift.asmx
Production URL: https://hc.mercurypay.com/tws/transactionservicegift.asmx

Note The gift server names are different from those used for credit, and must be explicitly specified to process
successfully.
Building Gift Transactions
There is a common set of data elements used to build gift transactions, regardless of how your code is implemented.
This section describes these common features as XML-based pairs. The Web Services Integration Method section
below provides specifics on how to implement them using a SOAP envelope to wrap the common payload and send it
to our Web Services URL endpoint.
Example of a Gift Transaction XML REQUEST
The example below illustrates the XML data elements required by Mercury regardless of integration method. Each
numbered tag is described below the figure:
<?xml version="1.0"?>
<TStream>
<Transaction>
<IpPort>9100</IpPort>
<MerchantID>003503902913105</MerchantID>
<OperatorID>test</OperatorID>
<TranType>PrePaid</TranType>
<TranCode>Issue</TranCode>
<InvoiceNo>123456</InvoiceNo>
<RefNo>123456</RefNo>
<Memo>POS.v123</Memo>
<Account>
<Track2>6050110010021825120=250110117</Track2>
</Account>
<Amount>
<Purchase>250.00</Purchase>
</Amount>
</Transaction>
</TStream>
Figure 49. Example of a Gift XML REQUEST
1. <IpPort> 9100 All gift transactions require that port 9100 be specified in the IpPort tag. If a gift transaction is sent
without an IpPort specified, a client error will result with the message, No Connection to any Server!
2. <MerchantID> (MID) Mercury merchant accounts are set up with a primary MerchantID (MID) used for routing
daily transaction deposits to the merchants bank, and identifying the merchants monthly statement. This MID is
also used for gift card processing.
The format combines an 11-digit numeric value, separated by an = and a 6-digit alpha value, as in:
884300XXXXX=ABCDEF. For coding purposes, allow a maximum value of 24 alphanumeric characters. Alpha
characters are not case sensitive.
Under the primary MID account, it is also possible to have additional, parallel processing sub-IDs, referred to
as Terminal IDs (TID). Used typically for credit and debit processing, these TIDs are linked to, and route funds

C
C

C
C
C
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 63 of 118
2014 Mercury

to the primary Merchant account. It is not required to use a separate TID for gift processing. Gift accounts
will be set up using the merchants primary MID.
MerchantID and TerminalIDs can be independently configured to enable duplicate checking logic, tokenization
and/or E2E support.
3. <TranType> (Transaction Type) and <TranCode> (Transaction Codes)
a. <TranType> is the transaction or tender category. For gift, use Prepaid.
b. <TranCode> is the specific type of transaction. Options include: Issue, Sale, NoNSFSale, Return, Reload,
Balance, and all voids.) See the MercuryGift Transaction Codes table for a complete list of supported
Transaction Types and TranCodes.
4. <InvoiceNo> and <RefNo>
a. InvoiceNo, a required field, is the local systems transaction number. If it is missing, the request will error
and return Invoice Number Missing in the response. The InvoiceNo should be kept distinct from other local
system numbering methods (also referred to as order, ticket, check, or receipt number) because each gift
transaction that is processed requires a unique InvoiceNo, especially in the case of split tenders. For
example, if the system presents ticket number #1234 for $100 and this ticket is split among two gift cards,
then the system would need to generate two separate receipts, each with its own unique InvoiceNo specific
to each of the two cards presented.
InvoiceNo format: Length: MIN: 1 digit, MAX: 16 digit, Right 10 unique; Data Type: Numeric only.
b. RefNo requires a filler value for all Sale, NoNSFSale, Issue, Return, Reload and Balance transaction
requests, and is the actual response value for all Voids. Without a RefNo the request will error and return
Reference Number Missing in the response.
RefNo format: length: MIN 6 digits, MAX: 9 always use full response value; Data Type: Numeric only.
Note The AuthCode field in the response will match the RefNo. The value returned is 6 numeric digits.
Use the actual server-assigned response for RefNo and AuthCode whenever submitting a VoidIssue,
VoidSale, Void Reload or Void Return.
5. <Memo> Placed in all transaction requests, the <Memo> tag is used to identify your systems name and version.
Example: <Memo>POS NAME v1.10A-08</Memo>
Memo format: Length: 1-40 maximum; Data Type: Alpha-Numeric.
- Recommendation Dynamically build the Memo tag so that it pulls the product name and version from
the project with each new build. This way the Memo stays current when the application version changes.
6. <Account> (parsed Track2 data) This is the gift card account number. Track 2 data is obtained from a clear-
text Card reader (MSR), a supported peripheral device, or an encryption E2E device. The card may either be
swiped or manually entered.
Note Mercury gift cards use a BIN range starting with 6050110 and are 19 digits long. On
the physical card, this number is printed followed by a dash - followed by a 1-6 digit
merchant BusinessID number. When manually entering a gift transaction it is only required
to use the numbers before the dashdo not include the numbers following the dash.
Account level Examples:
a. In a standard, non-encrypted swiped request, always parse Track2, removing the start and end sentinels
(; and ?). For example, here is a typical Mercury formatted gift card Track encoding:
;6050110010021825120=250110117?
<Account>
<Track2>6050110010021825120=250110117</Track2>
</Account>
b. In a non-encrypted manual request, only the AcctNo is required:
<Account>
<AcctNo>6050110010021825120</AcctNo>
<ExpDate>0513</ExpDate>
</Account>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 64 of 118
2014 Mercury

c. The example below is for developers who also support E2E encryption and use a supported E2E
peripheral for their credit integration. In this case, the gift card swipe data is encrypted and the Account
data elements are sent using four additional, encryption-specific tags: <EncryptedFormat>,
<AccountSource>, <EncryptedBlock> and <EncryptedKey>, as shown below:
<Account>
<EncryptedFormat>MagneSafe</EncryptedFormat>
<AccountSource>Swiped</AccountSource>
<EncryptedBlock>F40DDBA1F645CC8DB85A6459D45AFF8002C244A0F4402B4
79ABC9915EC9567C81BE99CE4483AF3D</EncryptedBlock>
<EncryptedKey>9012090B01C4F200002B</EncryptedKey>
</Account>
For manual encryption transactions the AccountSource must be changed to Keyed and the accompanying
EncryptedBlock is generated using a manual-entry format specific to each encryption device.
Note For keyed gift transactions, you should code to disable the prompt for Expiration Date and the
Card Security Code as these are unsupported features with gift processing and encryption.
7. <Amount> For all gift transaction requests except Balance, the Amount element uses the <Purchase> tag.
Amounts are dollar values to 2 decimal pointse.g., 25.30
<Amount>
<Purchase>25.30</Purchase>
</Amount>
Note For developers supporting Tokenization (not shown in the above examples): Frequency and RecordNo
tags are used in Mercurys tokenization procedures and may be optionally inserted into a gift transaction if
required for coding consistency. These two tags, when inserted, are ignored in gift processing; a token is never
generated or returned.
Example of a Gift Transaction XML RESPONSE
All gift transactions return a common set of response data, whether originating in a locally installed DSIClientX or sent
to a Mercurys Web Services endpoint. This data contains authorization information and the available card balance
and may be used to build receipts, build records for internal reporting, and can be stored for subsequent use.
The response data is divided into two sections:
A. <CmdResponse> summarizes the authorization. It shows the response origin, status of the authorization
response (Approved, Declined, Success, Error) and clarification verbiage in the <TextResponse> .
B. <TranResponse> is the Transaction Response in detail.
Each numbered tag is described below this figure:
<?xml version="1.0"?>
<RStream>
<CmdResponse>
<ResponseOrigin>Processor</ResponseOrigin>
<DSIXReturnCode>000000</DSIXReturnCode>
<CmdStatus>Approved</CmdStatus>
<TextResponse>Approved</TextResponse>
</CmdResponse>
<TranResponse>
<MerchantID>003503902913105</MerchantID>
<TranType>PrePaid</TranType>
<TranCode>Issue</TranCode>
<InvoiceNo>123456</InvoiceNo>
<OperatorID>test</OperatorID>
<AcctNo>6050110010021825120</AcctNo>
<RefNo>531747</RefNo>
<AuthCode>531747</AuthCode>
<Amount>
<Authorize>250.00</Authorize>
<Purchase>250.00</Purchase>
<Balance>250.00</Balance></Amount>

C
C

C
C
C


(A)
(B)
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 65 of 118
2014 Mercury

</TranResponse>
</RStream>
Figure 50. Example of Gift XML RESPONSE
(A) <CmdResponse> contains the following details:
1. <Response Origin> indicates the source of the response:
Client indicates that the response is from a locally installed DSIClientX .ocx control or, for developers
who point to Mercurys Web Services endpoint, the DSIClientX maintained on Mercurys Web
Services platform.
Server though rarely used, indicates is the response originating from Mercury's front-end gift server.
Processor indicates that the response originates from Mercurys processing platform.
2. <DSIXReturnCode> is 000000 on all Approved or Declined responses; on ERROR responses it is a six-digit
numeric code that corresponds to dynamically-generated text responses. Appendix 8 contains details on
this text response verbiage.
3. <CmdStatus> and <TextResponse>
a. <CmdStatus> indicates the outcome of the transaction. For gift, the value returned will be either
Approved, Declined, or Error.
b. <TextResponse> is clarifying verbiage used to explain the <CmdStatus>.
An Approved CmdStatus returns a TextResponse of Approved.
A Declined or Error CmdStatus will return a TextResponse based on the origin of the message. See
Gift Card Error Responses later in this guide for details.
(B) <TranResponse> contains all the transaction details as follows:
4. <MerchantID> is returned with the numeric value only.
5. <TranType> and <TranCode> mirror the transaction request.
6. <InvoiceNo> is passed back as generated by the POS.
7. <AcctNo> is returned in place of Track2 Data, returned in clear-text and may be stored as such.
8. <RefNo> and <AuthCode> are the same 6-digit numeric values generated at the time of the transaction
authorization and are returned in the transaction response. (The MercuryView merchant portal report shows
the Reference Number slightly differentlyas a nine-digit value. It is the right-six digits of this identifier that
are passed back in the transaction response for use in the RefNo and AuthCode.) These values may be stored
for use with void transactions if supported.
9. <Amount> always returns the authorized amount, the original purchase amount and the remaining available
balance amount.
The examples below illustrate <Amount> response tags:
a. Response for Sale, NoNSFSale (where sufficient balance is remaining), Return and Reload:
<Amount>
<Authorize>3.00</Authorize>
<Purchase>3.00</Purchase>
<Balance>109.76</Balance>
</Amount>
b. Response for Balance:
<Amount>
<Balance>200.00</Balance>
</Amount>
c. Response for a NoNSFSale when the remaining balance is less than the purchase amount. In this case, a
$27.00 purchase amount was requested on a card that had a remaining balance of $25.00:
<Amount>
<Authorize>25.00</Authorize>
<Purchase>25.00</Purchase>
<Balance>0.00</Balance>
</Amount>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 66 of 118
2014 Mercury

Note For NoNSFSale approved transactions, it is important to always compare the systems requested
Purchase amount with the actual Authorize amount in order to submit a balance due for the remaining
amount.
MercuryGift Card Usage Features
Each gift card issue range has specific features
that control the behavior of the cards. These
features are determined by the merchant during
the gift card application process. The table below
provides a list of these setup attributes and their
default values. These attributes affect developers
in terms of the text responses associated with
declined transactions.
Set up Feature Remarks Default Value
Card Expiration
There are five parameters pertaining to the expiration of gift cards. If "enforce
expiration" is NOT activated, none of the other expiration attributes are active.
1. Enforce Expiration
Controls whether transactions will be permitted after a
card has expired.
NO expiration date
2. Monthly Debit on
Expiration
Allows assessment of monthly inactivity fees after card has
expired.
$0.00
3. Months Expire
Each card will expire after a specified number of months,
relative to the issue date.
<Null>
4. Absolute
Expiration Date
All cards in the range will expire on specified date,
regardless of issue/activation date.
<Null>
5. Expire Type
Two choices: Absolute or Relative (see items 3 and 4
above.)
Relative
Maximum Issue
Limits the maximum balance allowed on the card. An issue
or return that results in exceeding the Maximum will
decline.
$250.00
Allow Return Controls whether return transactions will be accepted. Do NOT allow Returns
Max # of Returns per
Day
If Returns ARE allowed, limits how many return
transactions are allowed per day.
2 per day
Deactivate Card at
Zero
If true, once the cards balance reaches zero, it will be
deactivated and no further transactions will be accepted
for that card.
Do NOT deactivate
Use CRC
On swiped transactions, compare the full track read to the
track on file. Provides a higher level of security against
fraudulent cards. Cannot be used on third-party gift cards
not originating from Mercury.
Yes
Date Effective
Date after which previously issued cards can be redeemed
(for holiday promotions, etc.)
<Null>
Figure 51. Gift Card Attributes
Note Gift card legislation varies by State. For example, some states are now mandating the ability to cash
out prepaid gift cards when amounts are $10 or less. Therefore, it is important that developers, resellers and
merchants consult with the appropriate State agencies in order to determine how to set merchant gift card
attributes.
- Recommendation
Developers should ensure that their application and/or
receipts display the TextResponse messages on declined
gift transactions. This will help inform the merchant on
how to proceed. For instance, if the decline response
says Max Returns Exceeded, this indicates that the
maximum number of daily returns has been reached.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 67 of 118
2014 Mercury

Web Services Integration Method
Web Services MerchantID and Password Requirements
A Merchant ID and Web Services password are required for authenticating a transaction to the Web Services servers.
Web Services Merchant IDs follow the same formatting described earlier. In addition, Web Services also uses a
unique password which is generated upon merchant account set up.
Allow up to eight alpha-numeric characters, e.g., 81302DUR. Alpha characters are not case sensitive.
Note Web Services Merchant ID not Found and Invalid Credentials Errors:
If a transaction reaches the Web Services servers, but the merchant account cannot be authenticated, the error
Merchant ID not found or Invalid Credentials will occur. This happens when:
The SOAP envelope is malformed, the XML is incorrect, or the MerchantID or Web Services password cannot be
extracted.
The MerchantID or Web Services password is incorrect or missingError: "Invalid Credentials Call 1800-846-
4472."
Gift transactions Web Services URLs
There are two Web Services URLs . Mercury's Web Services W1 and W2 servers are geographically separate, yet act
as parallel, fully functioning entry points to Mercury's processing platform.

Server URL
Development Testing W1 Primary Server
(Only W1 is used in testing)
https://w1.mercurydev.net/ws/ws.asmx
Production Web Services W1 https://w1.mercurypay.com/ws/ws.asmx
Production Web Services W2 https://w2.backuppay.com/ws/ws.asmx
Mercurys Web Services Direct Libraries (WSDL)
Development Test /Certification WSDL https://w1.mercurydev.net/ws/ws.asmx?WSDL
Production WSDL https://w1.mercurypay.com/ws/ws.asmx?WSDL
Figure 52. Web Services URLs and WSDLs
Note Make sure to use the correct server when processing over Web Services.
Failover between WS servers
Unlike the DSIClientX ServerIPConfig () method, Web Services developers are required to monitor and build-in failover
logic in the rare event of a server connection failure. If there is a connection failure, it is recommended to failover to
the alternate server and remain at that URL. It is not necessary to fail back to the previous server. If both WS servers
are returning http response connectivity errors, contact Mercury immediately.
Note that WS connectivity errors can happen at several points along the transaction routing path:
If your system receives a WS http error (e.g. 503, 500, 404) indicating the connectivity to the WS server has
failed, is lost or unavailable, then this is a good indication to immediately rollover to the secondary server.
If your system receives WS http formatting or parsing errors (e.g. 400-Bad Request), rolling over to an
alternative WS server would not correct the root cause of the error.
Error responses originating beyond the WS server returned from the Client, Server or Processor with
TextResponses such as No Connection to Any Server or Socket Connection Error do not indicate a need to fail
over to an alternative WS server. These response messages indicate that the transaction has been routed
correctly by Mercury WS server but is failing to connect to the gift server. In this case, the option is to attempt
a retry first to the same server; if subsequent retries fail, contact Mercury.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 68 of 118
2014 Mercury

Gift Transaction Web Services Methods and Arguments
Note The XML string specifies the necessary transaction information (payload) that is sent as an argument of the
methods.
WS Method Purpose and Argument Description
GiftTransaction() Send a gift card transaction
GiftTransaction(trans as string, password as string)
Two arguments:
1. trans is an XML string formatted with transaction details as specified in the DSIClientX PI Spec
2. password is a string that Mercury assigns for a particular MerchantID
Example: s = x.GiftTransaction(tran,"xyz")
Note IP Port 9100 must be included in the soap-wrapped GiftTransaction() request
CAllGiftDetail() Returns transaction records to match specified criteria (by Invoice, or start date/end date)
This method will return up to 3,000 records matching the specified invoice, start date and end date.
CAllGiftDetail(merchant as string, password as string, invoice as string, startdate as string, enddate as string)
Five arguments:
1. merchant is the merchant ID of this account
2. pw is a string that Mercury assigns for a particular merchant ID
3. invoice (optional): a string that specifies the invoice number of the transaction record
4. startdate (optional): string formatted mm/dd/yy, used to find the start date of the invoice
5. enddate (optional): string formatted mm/dd/yy, specifying the end date to find the invoice
Example: s = x.CAllGiftDetail(595901,xyz,1234,01/01/05,07/08/05)
SOAPAction: "http://www.mercurypay.com/CAllGiftDetail"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<CAllDetail xmlns="http://www.mercurypay.com">
<merchant>string</merchant> <!--note argument/element is here lower
case and does not use DataCap convention of 'MerchantID'-->
<pw>string</pw> <!--note use of 'pw' not 'password'-->
<invoice>string</invoice> <!--string value and data elements are
optional-->
<startdate>string</startdate> <!--string value is optional but data
elements are required. Other option includes '<startdate />' -->
<enddate>string</enddate> <!--string value is optional but data
elements are required. Other option includes '<enddate />'-->
</CAllGiftDetail>
</soap:Body>
</soap:Envelope>
Figure 53. Gift Transaction Web Services Methods and Arguments

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 69 of 118
2014 Mercury

Gift Web Services Examples
Swiped Gift Issue
Swiped Gift NoNSFSale
VoidSale of Previous Manual Transaction
Swiped Gift Reload
Manual Gift NoNSFSale using modified Track2=CRC Method
Manual Gift Sale using CVV data
Web Services: Swiped Gift Issue
Request
User-Agent: MPS Transact 1.2.0.5
Content-Type: text/xml; charset=utf-8
SOAPAction: http://www.mercurypay.com/GiftTransaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Issue&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123468&lt;/InvoiceNo&gt;
&lt;RefNo&gt;123468&lt;/RefNo&gt;
&lt;Memo&gt;POS.v345&lt;/Memo&gt;
&lt;Account&gt;
&lt;Track2&gt;6050110010021825120=250110117&lt;/Track2&gt;
&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;200.00&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
</GiftTransaction>
</soap:Body>

</soap:Envelope>
Response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;
&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Approved&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 70 of 118
2014 Mercury

&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Issue&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123468&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110010021825120&lt;/AcctNo&gt;
&lt;RefNo&gt;532048&lt;/RefNo&gt;
&lt;AuthCode&gt;532048&lt;/AuthCode&gt;
&lt;Amount&gt;
&lt;Authorize&gt;200.00&lt;/Authorize&gt;
&lt;Purchase&gt;200.00&lt;/Purchase&gt;
&lt;Balance&gt;200.00&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 54. Web Services Example: Swiped Gift Issue
Note If developers have implemented E2E or MToken requiring E2E or MToken enabled MerchantIDs, the
request may be sent, for consistency in coding, either with or without the encrypted or token data fields. A token
is never generated or returned on gift transactions. Clear-text gift card data will be returned in the AcctNo
response tag and may be stored for subsequent use.
Web Services: Swiped Gift NoNSFSale
Request
User-Agent: MPS Transact 1.2.0.5
Content-Type: text/xml; charset=utf-8
SOAPAction: http://www.mercurypay.com/GiftTransaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;595901&lt;/MerchantID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;NoNSFSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;9&lt;/InvoiceNo&gt;
&lt;RefNo&gt;9&lt;/RefNo&gt;
&lt;Memo&gt;MPS Transact 1.2.0.5&lt;/Memo&gt;
&lt;Account&gt;
&lt;Track2&gt;6050110000012485491=250110117&lt;/Track2&gt;
&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;2.25&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
</GiftTransaction>
</soap:Body>

</soap:Envelope>
Response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 71 of 118
2014 Mercury

xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;
&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Approved&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;595901&lt;/MerchantID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;NoNSFSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;9&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110000012485491&lt;/AcctNo&gt;
&lt;RefNo&gt;469955&lt;/RefNo&gt;
&lt;AuthCode&gt;469955&lt;/AuthCode&gt;
&lt;Amount&gt;
&lt;Authorize&gt;2.25&lt;/Authorize&gt;
&lt;Purchase&gt;2.25&lt;/Purchase&gt;
&lt;Balance&gt;79.25&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 55. Web Services Example: Swiped Gift NoNSFSale
Web Services: Gift VoidSale of Previous Manual Transaction
Request
User-Agent: MPS Transact 1.2.0.5
Content-Type: text/xml; charset=utf-8
SOAPAction: http://www.mercurypay.com/GiftTransaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;VoidSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123476&lt;/InvoiceNo&gt;
&lt;RefNo&gt;532137&lt;/RefNo&gt;
&lt;Memo&gt;POS.v345&lt;/Memo&gt;
&lt;Account&gt;
&lt;AcctNo&gt;6050110010021825120&lt;/AcctNo&gt;
&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;4.00&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;TranInfo&gt;
&lt;AuthCode&gt;532137&lt;/AuthCode&gt;
&lt;/TranInfo&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 72 of 118
2014 Mercury

</GiftTransaction>
</soap:Body>

</soap:Envelope>
response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;

&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Voided&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;VoidSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123476&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110010021825120&lt;/AcctNo&gt;
&lt;RefNo&gt;532137&lt;/RefNo&gt;
&lt;Balance&gt;200.00&lt;/Balance&gt;
&lt;Amount&gt;
&lt;Authorize&gt;4.00&lt;/Authorize&gt;
&lt;Purchase&gt;4.00&lt;/Purchase&gt;
&lt;Balance&gt;200.00&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 56. Web Services Example: Gift VoidSale
Web Services: Swiped Gift Reload
Request
User-Agent: MPS Transact 1.2.0.5
Content-Type: text/xml; charset=utf-8
SOAPAction: http://www.mercurypay.com/GiftTransaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Reload&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123478&lt;/InvoiceNo&gt;
&lt;RefNo&gt;123478&lt;/RefNo&gt;
&lt;Memo&gt;POS.v345&lt;/Memo&gt;
&lt;Account&gt;
&lt;Track2&gt;6050110010021825120=250110117&lt;/Track2&gt;
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 73 of 118
2014 Mercury

&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;50.00&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
</GiftTransaction>
</soap:Body>

</soap:Envelope>
Response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;

&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Approved&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Reload&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123478&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110010021825120&lt;/AcctNo&gt;
&lt;RefNo&gt;532139&lt;/RefNo&gt;
&lt;AuthCode&gt;532139&lt;/AuthCode&gt;
&lt;Amount&gt;
&lt;Authorize&gt;50.00&lt;/Authorize&gt;
&lt;Purchase&gt;50.00&lt;/Purchase&gt;
&lt;Balance&gt;250.00&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 57. Web Services Example: Gift Reload
Web Services: Manual Gift NoNSFSale using Modified Track2=CRC Method
Request
User-Agent: MPS Transact 1.2.0.5
Content-Type: text/xml; charset=utf-8
SOAPAction: http://www.mercurypay.com/GiftTransaction

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 74 of 118
2014 Mercury

&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;NoNSFSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123488&lt;/InvoiceNo&gt;
&lt;RefNo&gt;123488&lt;/RefNo&gt;
&lt;Memo&gt;POS.v345&lt;/Memo&gt;
&lt;Account&gt;
&lt;Track2&gt;6050110010021825120=17&lt;/Track2&gt;
&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;5.25&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
</GiftTransaction>
</soap:Body>

</soap:Envelope>
Response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;

&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Approved&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;NoNSFSale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123488&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110010021825120&lt;/AcctNo&gt;
&lt;RefNo&gt;532163&lt;/RefNo&gt;
&lt;AuthCode&gt;532163&lt;/AuthCode&gt;
&lt;Amount&gt;
&lt;Authorize&gt;5.25&lt;/Authorize&gt;
&lt;Purchase&gt;5.25&lt;/Purchase&gt;
&lt;Balance&gt;244.75&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 58. Web Services Example: Gift NoNSFSale using CRC


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 75 of 118
2014 Mercury

Web Services: Manual Gift Sale using CVVData
Request
<soap:Body>
<GiftTransaction xmlns="http://www.mercurypay.com">
<tran>&lt;?xml version="1.0"?&gt;
&lt;TStream&gt;
&lt;Transaction&gt;
&lt;IpPort&gt;9100&lt;/IpPort&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;TerminalID&gt;003503902913105&lt;/TerminalID&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Sale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123483&lt;/InvoiceNo&gt;
&lt;RefNo&gt;123483&lt;/RefNo&gt;
&lt;Memo&gt;POS.v345&lt;/Memo&gt;
&lt;Account&gt;
&lt;AcctNo&gt;6050110000002570798&lt;/AcctNo&gt;
&lt;/Account&gt;
&lt;Amount&gt;
&lt;Purchase&gt;3.00&lt;/Purchase&gt;
&lt;/Amount&gt;
&lt;CVVData&gt;880&lt;/CVVData&gt;
&lt;/Transaction&gt;
&lt;/TStream&gt;</tran>
<pw>xyz</pw>
</GiftTransaction>
</soap:Body>

</soap:Envelope>
Response
<?xml version="1.0" encoding="utf-8"?><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><GiftTransactionResponse
xmlns="http://www.mercurypay.com"><GiftTransactionResult>&lt;?xml version="1.0"?&gt;

&lt;RStream&gt;
&lt;CmdResponse&gt;
&lt;ResponseOrigin&gt;Processor&lt;/ResponseOrigin&gt;
&lt;DSIXReturnCode&gt;000000&lt;/DSIXReturnCode&gt;
&lt;CmdStatus&gt;Approved&lt;/CmdStatus&gt;
&lt;TextResponse&gt;Approved&lt;/TextResponse&gt;
&lt;UserTraceData&gt;&lt;/UserTraceData&gt;
&lt;/CmdResponse&gt;
&lt;TranResponse&gt;
&lt;MerchantID&gt;003503902913105&lt;/MerchantID&gt;
&lt;TranType&gt;PrePaid&lt;/TranType&gt;
&lt;TranCode&gt;Sale&lt;/TranCode&gt;
&lt;InvoiceNo&gt;123483&lt;/InvoiceNo&gt;
&lt;OperatorID&gt;test&lt;/OperatorID&gt;
&lt;AcctNo&gt;6050110000002570798&lt;/AcctNo&gt;
&lt;RefNo&gt;532155&lt;/RefNo&gt;
&lt;AuthCode&gt;532155&lt;/AuthCode&gt;
&lt;Amount&gt;
&lt;Authorize&gt;3.00&lt;/Authorize&gt;
&lt;Purchase&gt;3.00&lt;/Purchase&gt;
&lt;Balance&gt;197.00&lt;/Balance&gt;
&lt;/Amount&gt;
&lt;CvvResult&gt;M&lt;/CvvResult&gt;
&lt;/TranResponse&gt;
&lt;/RStream&gt;
</GiftTransactionResult></GiftTransactionResponse></soap:Body></soap:Envelope>
Figure 59. Web Services Example: Gift Sale using CVV Data
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 76 of 118
2014 Mercury

Adding a gift card balance query page to a website
Consumers may check the balance on their gift card by going to www.mercurygift.com. However, you may prefer
to create your own web page as part of your POS. Mercury provides both a text link and an image link that you can
use.
Adding the Text Link

http://www.mercury-gift.com/textlink.html

Add all of the following code to your html page:
<!-- Begin GiftBalance code Text link-->
<script language=javascript type=text/javascript>
<!--
function popup(url) {
newwindow=window.open(url,giftbalance,width=678,height=416);
if (window.focus) {newwindow.focus()}
return false;
}
// -->
</script>
<a href=https://www.mercury-gift.com/GiftInquiry.aspx
onclick=return popup(https://www.mercury-gift.com/GiftInquiry.aspx)>
<font face=verdana,arial,helvetica style=font:13px
arial,helvetica;color:#3a9dd7;font-weight:bold;text-decoration:none;>
Click here to check your Gift Card balance </font></a>
<!-- End giftbalance code -->
Figure 60. Code Example: Adding Gift Card Balance Query text link to a website
Adding the Image Link
http://www.mercury-gift.com/imagelink.html

Add all of the following code to your html page:
<!-- Begin GiftBalance code image link -->
<script language=javascript type=text/javascript>
<!--
function popup(url) {
newwindow=window.open(url,giftbalance,width=678,height=416);
if (window.focus) {newwindow.focus()}
return false;
}
// -->
</script>
<a href=https://www.mercury-gift.com/GiftInquiry.aspx
onclick=return popup(https://www.mercury-gift.com/GiftInquiry.aspx)>
<img src=http://www.mercury-gift.com/images/balance.gif
alt=Click here to check your Gift Card Balance width=216 height=36 border=0></a>
<!-- End giftbalance code -->
Registered ISO and Merchant Service Provider of HSBC Bank, USA National Association, Buffalo, NY
Figure 61. Code Example: Adding Gift Balance query image link to a website
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 77 of 118
2014 Mercury

Add the gift balance iFrame code to the inquiry page to your website:
1. Add all of the following code between the <head></head> tags in the html page.
<script type=text/javascript>
function chkVisibilityOn() {
window.document.getElementById(scroll).style.visibility = visible;
}
function chkVisibilityOff() {
window.document.getElementById(scroll).style.visibility = hidden;
}
/*************************************************************************
This code is from Dynamic Web Coding at http://www.dyn-web.com/
See Terms of Use at http://www.dyn-web.com/bus/terms.html
regarding conditions under which you may use this code.
This notice must be retained in the code as is!
*************************************************************************/
function getDocHeight(doc) {
var docHt = 0, sh, oh;
if (doc.height) docHt = doc.height;
else if (doc.body) {
if (doc.body.scrollHeight) docHt = sh = doc.body.scrollHeight;
if (doc.body.offsetHeight) docHt = oh = doc.body.offsetHeight;
if (sh && oh) docHt = Math.max(sh, oh);
}
return docHt;
}
function setIframeHeight(iframeName) {
var iframeWin = window.frames[iframeName];
var iframeEl = document.getElementById? document.getElementById(iframeName): document.all?
document.all[iframeName]: null;
if ( iframeEl && iframeWin ) {
iframeEl.style.height = auto; // helps resize (for some) if new doc shorter than previous
var docHt = getDocHeight(iframeWin.document);
// need to add to height to be sure it will all show
if (docHt) iframeEl.style.height = 240 + 34 + px;
}
}
function loadIframe(iframeName, url) {
if ( window.frames[iframeName] ) {
window.frames[iframeName].location = url;
return false;
}
else return true;
}
var timer_id;
function scroll_iframe(frm,inc,dir) {
if (timer_id) clearTimeout(timer_id);
if (window.frames[frm]) {
if (dir == v) window.frames[frm].scrollBy(0, inc);
else window.frames[frm].scrollBy(inc, 0);
timer_id = setTimeout(scroll_iframe( + frm + , + inc + , + dir + ), 20);
}
}
function stopScroll() { if (timer_id) clearTimeout(timer_id);
}
</script>
2. Add the following iFrame tag between the <body></body> tags in the html page.
<iframe name=ifrm id=ifrm src=https://www.mercury-gift.com/giftbalance/ height=420
Width=100% scrolling=no
frameborder=0>Sorry, your browser doesnt support iframes.</iframe>&nbsp;

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 78 of 118
2014 Mercury

Gift Card Encoding and Security Features CRC and CVV Data
For fraud protection on Mercury generated gift cards, there is a printed set of numbers and an encoded set of
numbers on the magnetic stripe. For manual entry, two levels of fraud protection are available using either a two- or
three-digit card verification value (security code). The two-digit security code is the standard encoding on Mercury gift
cards. A three-digit security code is available by special order.
Printed on the front of the card is the gift card number followed by a dash and then a series of one to five additional
numbers.
The number to the left of the dash is the account card number used for processing gift transactions.
The number to the right of the dash is the Merchants Business ID. Both numbers are used when checking for
balance inquiries online (www.mercury-gift.com ), but only the account number is used for processing.
Printed on the back of the card, just below the encoding magnetic stripe:
Figure 62. Back of a Gift Card
1. On the left side is the gift card number followed by a dash then the Business ID.
2. The encoding on the magnetic stripe contains Track2 data, which is the encoding format used on Mercury gift
cards. Mercury and many third parties use a non-ISO financial format when encoding gift cards. The following is a
typical Track2 read found on Mercury encoded gift cards:
;6050110000000296518=250110314?
The sentinels (; and ?) are used to delineate the track. Sentinels must be parsed before processing. The data after
the = is discretionary data only. 2501 is a filler value. Expiration dates are not imposed from the card track data.
Expiration is a usage parameter associated with the card at the time the range is generated.
3. On the right is the cards security data number (card verification value), shown as a two or three digit number.
4. www.mercury-gift.com can be used to look up the card balance, using the Card Number plus Business ID.
Using the Two-Digit Card Verification Value
By default, Mercury gift cards include a standard, two-digit card verification value referred to in this discussion as CRC
(but typically also referred to as CVV). This two-digit value is printed on the back of the card. In order to build a
request that uses the CRC, the card number is combined with the two-digit security data and inserted into a modified,
pseudo Track2 format.

O
O
O
O
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 79 of 118
2014 Mercury

Example of a Manual Gift Transaction using the 2-digit Card Verification Value (aka CRC)
The example below uses the pseudo <Track2>6050110000000296518=14</Track2>, where
Account number = 6050110000000296518, and
CRC=14 (CRC is printed on the back of the card)
Request
<?xml version="1.0"?>
<TStream>
<Transaction>
<IpPort>9100</IpPort>
<MerchantID>595901</MerchantID>
<TranType>PrePaid</TranType>
<TranCode>NoNSFSale</TranCode>
<InvoiceNo>12</InvoiceNo>
<RefNo>12</RefNo>
<Memo>JBsPOS 7.5.0.2</Memo>
<Account>
<Track2>6050110000000296518=14</Track2>
</Account>
<Amount>
<Purchase>2.10</Purchase>
</Amount>
</Transaction>
</TStream>
Response
<?xml version="1.0"?>
<RStream>
<CmdResponse>
<ResponseOrigin>Processor</ResponseOrigin>
<DSIXReturnCode>000000</DSIXReturnCode>
<CmdStatus>Approved</CmdStatus>
<TextResponse>Approved</TextResponse>
<UserTraceData></UserTraceData>
</CmdResponse>
<TranResponse>
<MerchantID>595901</MerchantID>
<TranType>PrePaid</TranType>
<TranCode>NoNSFSale</TranCode>
<InvoiceNo>12</InvoiceNo>
<AcctNo>6050110000000296518</AcctNo>
<RefNo>379733</RefNo>
<AuthCode>379733</AuthCode>
<Amount>
<Authorize>2.10</Authorize>
<Purchase>2.10</Purchase>
<Balance>195.65</Balance>
</Amount>
</TranResponse>
</RStream>
Figure 63. XML Example: Manual Gift Request using the two-digit security value (CRC)
Note The two-digit gift card verification value (Track2=CRC) method requires additional development work to
build the pseudo-Track2 data and interpret the results.
Invalid or Missing CRC Error Handling when using the Track2=CRC method
1. If the two-digit CRC is invalid or missing, the transaction will decline with the text response: Mag Stripe Error
- Hand Key. This message requires the card to be re-entered with the correct CRC, or re-entered without
using the Track2=CRC method by using the AcctNo field only.
2. If the AcctNo tag is inadvertently used in place of Track2, the transaction will fail with Invalid Account
Number. Using the Track2=CRC method requires the format illustrated above.

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 80 of 118
2014 Mercury

Using the Three-digit Card Verification Value
Mercury has a second level of gift card fraud protection for manual entry that employs a three-digit card
verification value. The following details apply:
CVVData is validated only when the gift card is used
to tender a transaction (Sale, NoNSFSale, Reload,
Return and corresponding voids). Non-tendered
transactions, Issue, VoidIssue, and Balance, are not
validated.
Developers must add a <CVVData> tag to the
transaction request, which is used exclusively with
the three-digit security code, e.g. <CVVData>123
</CVVData>. The value is numeric, MIN 3 digits, MAX
4 digits. The result will be passed back as a single
alpha character in the <CvvResult> tag in the
response:
CmdStatus is Approved, CvvResult is M indicates an approved security code match, i.e.
<CvvResult>M</CvvResult>
CmdStatus is Declined, CvvResult is P indicates and invalid, missing or incorrect security code
<CvvResult>P</CvvResult>
Gift cards are set to validate CVVData if supplied. If the CVVData tag is not provided, or if no value is present in the
tag, Mercury processes the transaction without any security check. If the CVVData tag is present and has data,
Mercury will validate the data and return the appropriate result.
Protection against Duplicate Transactions
Mercurys gift server duplicate logic checks the card number, total amount, invoice number and date. A duplicate is
defined as the same card number, the same amount, and the same invoice number processed on the same day. The
duplicate gift transaction will decline and return:
<CmdResponse>
<ResponseOrigin>Processor</ResponseOrigin>
<DSIXReturnCode>000000</DSIXReturnCode>
<CmdStatus>Declined</CmdStatus>
<TextResponse>Duplicate Transaction</TextResponse>
<UserTraceData></UserTraceData>
</CmdResponse>
Figure 64. Example XML: Duplicate Transaction Declined
The Duplicate Transaction response indicates that the same card account, amount and invoice number was already
logged as an approved transaction and a duplicate has been detected.
If the transaction is valid, (that is, if the cardholder is legitimately running a second transaction for the same
amount on the same gift card), then incrementing the InvoiceNo will resolve the decline.
If the decline was returned after a Time out on Response message, this indicates that the original gift transaction
was authorized and does not require the transaction to be resubmitted.

Note The three-digit gift security check
method requires additional development work.
New merchants on systems that support this
method must specifically request the three-
digit CVV at the time any new gift card account
application is filed. (Once Gift Issue ranges are
boarded the merchant record cannot be
altered). The three-digit security code method
cannot be applied to previously issued ranges
boarded without the specifically generated
security data.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 81 of 118
2014 Mercury

MercuryGift Transaction Codes
These transaction codes are applicable to both manual and swiped transactions.
TranCode Description Comments
Issue Activates the account and loads a specified
amount value onto the card.
The card may not be previously issued .
The issue amount may not exceed the
merchants agreed upon maximum issue
amount value.
The Issue may be voided/cancelled by
processing a VoidIssue as long as there is no
transaction history on the card.
Sale Takes value off of the card, reducing the
available balance by that purchase amount.
Declines the transaction if there is insufficient
balance.
The card must already be issued.
Card must have sufficient balance to cover the
purchase request.
A gift Sale can be cancelled by using a gift
VoidSale or by adding value to the card using
Reload or Return.
NoNSFSale
Takes value off of the card, reducing the
available balance by that purchase amount.
If there is an insufficient account balance,
the transaction will approve for the
remaining balance on the card.
Requires the system to manage a Balance
Due split-tender if there is an insufficient
balance on the card to cover the total
purchase amount.
Note Cash Out (Paid Out) is required in
California. In California, customers may opt
to cash out remaining balances under
$10.00. To accommodate this state mandate,
developers should build in provisions to allow
using Balance followed by a Sale or
NoNSFSale to bring the card to 0.00 balance
and then provide a local POS-side Paid out.
For example, a gift card has a balance of
$60.00. The cardholder uses the card to
perform a $100 purchase; the NoNSFSale will
authorize for the available balance of $60.00,
reducing the gift card balance to $0.00. The
system must include logic which prompts for
the remaining amount due, which is $40.00 in
this example.

In either case, a NoNSFSale can be cancelled
using a gift VoidSale or by adding value to the
card using Reload or Return.


Reload
Adds value to a card, increasing the balance.
Typically used for a gift inventory line item.
The card must already be issued.
Default is maximum two reloads/day. By
request, this can be changed to a maximum of
10 reloads/day.
Return
Adds value to a card, increasing the
balance.
Typically used when merchandise is
returned and the value is added to a gift
card in place of cash.
The card must already be issued.
Return may be used interchangeably with Reload
however, it is important to consider tax and
inventory impacts, if your system handles this
level of accounting detail.
VoidSale,
VoidReload,
VoidReturn
Cancels a previously approved
Sale/Reload/Return, adding the voided
amount back to the card.

All gift Voids must specify the RefNo (reference
number) and AuthCode (authorization code)
returned in the originating transaction response, as
well as the card number and original transaction
amount.
VoidIssue
Cancels the issuance of a card, returning the
account balance to 0.00 and puts the card
into a non-issued state.
VoidIssue is allowed only when there is no
transaction history on the card since the original
Issue transaction.
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 82 of 118
2014 Mercury

TranCode Description Comments
Balance
A balance inquiry returns the remaining
balance of a card.
In states requiring cash-out
functionality, use Balance to confirm the
remaining value on the card, then build in a
system-side Cashout by sending a
NoNSFSale for that available balance,
bringing the card to 0.00 and a paid out
at the system for the amount of the card
balance.
For liability concerns, there is a default maximum
value allowed on gift cards of $250.00.
Merchants may adjust this default during their
gift account application.
The balance inquiry is independent of a card's
expiration date, so a balance will be returned
even for cards that have an enforced expiration
date.
Cards that have been de-activated through a
VoidIssue will not return a balance if queried
using the Balance transaction. A TextResponse,
Account not Issued will be returned instead.
Note Mercurys gift server returns the available balance in the response for all gift card transactions. It is
recommended to print the available balance on all receipts. Please review the State regulations where your is
distributed for additional requirements.
-Recommendation
Some States are now mandating a function to cash out prepaid gift cards when amounts are $10 or less. At the
time of this writing, California and Massachusetts require this feature. Mercury recommends supporting the
NoNSFSale combined with Balance Inquiry. NoNSFSale also provides greater convenience to merchants and
customers in the event of an insufficient gift card balance.
For more information see Gift Card Laws by State: http://www.scripsmart.com/state_gift_card_laws
Gift Card Error Responses
<TextResponse> Error messages Description
Gift Set Up
No MerchantID Specified This merchant ID was not found in our database
MerchantID not found The merchant ID entered is not valid
Merchant Not Accepting Gift This merchant ID is not setup for gift
Invalid TranType for Prepaid Server The transaction type entered is not valid for gift
Invalid TranCode The transaction code entered is not valid for gift
Database Insertion Error Can't insert into our database
Issue
Invalid Account Number Account number not in Merchant's range
Account Not Issued Card has not been issued, or has been de-activated with VoidIssue.
Missing Invoice Field There was no invoice number given
Amount Field Error Incorrect amount entered
Non Numeric Account Account number provided is not numeric
Account Already Issued Gift Card has already been issued
Issuance Not Authorized Didnt find the card in the merchant's range or exceed max amount
allowed to issue
Not a GIFT AccountType Wrong issuing range type
Mag Stripe Error - Hand Key Card did not swipeplease key in the card number
Amount Exceeds Maximum Exceeds the maximum amount that the gift card can be issued for
Amount Cannot Be Zero There must be an amount higher than Zero
Could not Issue Card cannot be issued
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 83 of 118
2014 Mercury

<TextResponse> Error messages Description

Return
Account has not met the Effective Date The card's start date has not been reached
Account Deactivated The gift card account has been deactivated and is no longer allowing
transactions
Return Not Allowed Returns are not allowed on this card
Duplicate Transaction There has already been a return issued for this invoice number, card
number and amount
Number of Returns on Card over Limit The maximum amount of returns on the card has been met
Sale
Account on Hold The gift card is on hold, no transactions are allowed on this card
Account Expired The gift card account has expired
Insufficient Account Balance There are not enough funds on this account
Bad Reference Number The reference number supplied is not valid
No Account Match no account for this
merchant
The card number is not in the valid range for this merchant
No Amount Match
Void
Void RefNo not found No transaction to void was found
Void Last Transaction First Not the last transaction
Please use VoidIssue A void cannot void an issue, please use the VoidIssue transactions type
Declined - Insert Error Cant insert into database
VoidIssue
Account In Use Too many transactions already on card to void issue
Could not VoidIssue Unable to complete VoidIssue transaction
Figure 65. Gift Card Error responses


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 84 of 118
2014 Mercury

Appendix 2: HostedCheckout Development and Production URLs

Mercury HostedCheckout Credit URLs
Development URL: https://hc.mercurydev.net/hcws/hcservice.asmx
Production URL: https://hc.mercurypay.com/hcws/hcservice.asmx
Mercury HostedCheckout URL for mobile: (Optimized for use on mobile smartphone devices and Kindle.)
Development URL: https://hc.mercurydev.net/mobile/mCheckout.aspx
Production URL: https://hc.mercurypay.com/mobile/mCheckout.aspx
Mercury HostedCheckout URL for iFrame (eCommerce only, not available for mobile)
Development URL iFrame: https://hc.mercurydev.net/CheckoutiFrame.aspx
Production URL iFrame: https://hc.mercurypay.com/CheckoutiFrame.aspx
TransactionService web service URLs
Development URL TransactionService: https://hc.mercurydev.net/tws/transactionservice.asmx
Production URL TransactionService: https://hc.mercurypay.com/tws/transactionservice.asmx
Mercury HostedCheckout URL for CardInfo: (For use on desktop browsers and tablets)
Development URL: https://hc.mercurydev.net/CardInfo.aspx
Production URL: https://hc.mercurypay.com/CardInfo.aspx
Production and Development-Test Gift Servers
Development URL: https://hc.mercurydev.net/tws/transactionservicegift.asmx
Production URL: https://hc.mercurypay.com/tws/transactionservicegift.asmx


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 85 of 118
2014 Mercury

Appendix 3: Hosted Checkout Process Flows
HostedCheckout Payment Process and Checkout from eCommerce Site



Initialize HostedCheckout Payment Process and Checkout from eCommerce Site
Collect Secure Payment Information Hosted by Mercury Payment Systems
6
th
STEP
Client Side Validation
Return to eCommerce Site and Verify Payment
8
th
STEP
ORDER COMPLETE QUERY DATA Returned to the Developer Hosted Server
https://www.durangopizza.com/ordercomplete.aspx
Query String Params
PaymentID
12
th
Step
Developer to return results to client
5
th
Step
https://hc.mercurypay.com/Checkout.aspx
Https Form Post PaymentID hidden field Server Side
PaymentID
1
st
Step
www.durangopizza.com
Orders Food
Enters Shipping Address
Enters Billing Address
Selects CheckOut
4
th
Step
9
th
Step
Re-Direct
2
nd
Step
InitializePayment(MID {String}
TotalAmount {String}
InvoiceNo {String}
BillingAddresss {String}
BillingPostalCodes {String}
TranType {String}
CardHolderName {String}
PW {String})
...
3
rd
Step
Return PaymentID
10
th
STEP
VerifyPayment(
MerchantID {String}
PaymentID {String}
Password {String})
11
th
STEP
Response Code
Status: {Approved, Declined, Success}
Token
Display and Error Messaging
Last 4 Digits of CC
Receipt Info for PreAuth and Sale...
And Pre-Auth Info for PreAuth Capture(AuthCode, etc)
...
Merchant PreAuth Capture via HostedCheckout Web Services
14
th
STEP
Web Method Capture(MerchantID, TOKEN, AuthCode, etc)
15
th
STEP
Return Capture Results
Status
...
13
th
STEP
Customer Receives Goods
Consumer PC
Consumer PC
Consumer PC
Developers Web Server
Mercury Payment Systems
Mercury Payment Systems
Transaction Processing
Developers Web Server
Mercury Payment Systems
Developers Web Server Mercury Payment Systems
Transaction Processing
7
th
STEP
HTTPS: ASP.NET Form Post
Mercury Server Side C# from user entered fields
Card Type {Visa, MC, etc}
CC#
CVV
Expiration Date
Name on Card
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 86 of 118
2014 Mercury

Hosted Checkout Mobile Data Flow

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 87 of 118
2014 Mercury

APPENDIX 4: CSS Functionality
CSS (Cascading Style Sheets) provide extensive styling capability for HostedCheckout pages. CSS uses a separate
method to submit, and have Mercury store, the merchants CSS. This process is separate from the initialize
payment process. Below are examples of the calls needed to support CSS.
CssUploadRequest
CssDownloadRequest
CssRemoveRequest
Input Parameters to CssUploadRequest Method
Parameter Type Length Description Required
MerchantID Numeric 24 The Merchants account or MerchantID that
payments will be processed under. The typical
format for a Mercury Payment Systems merchant
ID is: 88430087469
Please contact your developer integrations analyst
for the test MerchantID.
Yes
Password String 16 The web services password generated by the
merchant or dealer/developer on the MercuryView
portal and entered into the POS configuration
screen to allow access to the web service. Please
contact your developer integrations analyst for the
test password.
Yes
Css String 20,000 max Merchant specific CSS . Yes

Upload Request Code Example
HCService.CssUploadRequest request = new HCService.CssUploadRequest();
request.MerchantID = "013163015566916";
request.Password = "KR568r@1spyC13,T";
request.Css = .divTotalDefault{color: #000000;background-color: red;}

<!--Call the web service to initialize the UploadCSS request.-->
HCService.HCService hcWS = new HCService.HCService();
HCService.CssAdminResponse response = new HCService.CssAdminResponse();
response = hcWS.UploadCSS(request);

if (response != null)
{
this.txtCode.Text = response.ResponseCode.ToString();
this.txtResponseMsg.Text = HttpUtility.HtmlDecode(response.Message);
}
else
<!--something seriously wrong. probably couldn't connect to the web service at all-->
this.txtResponseMsg.Text = "Response from UploadCss was Null";

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 88 of 118
2014 Mercury

Input Parameters to CssDownloadRequest Method
Parameter Type Length Description Required
MerchantID Numeric 24 The Merchants account or MerchantID that
payments will be processed under. The typical
format for a Mercury Payment Systems merchant
ID is: 88430087469
Please contact your developer integrations analyst
for the test MerchantID.
Yes
Password String 16 The web services password generated by the
merchant or dealer/developer on the MercuryView
portal and entered into the POS configuration
screen to allow access to the web service. Please
contact your developer integrations analyst for the
test password.
Yes
Formatting String 3 Values are on and off. A value of on will
include carriage returns and formatting to make
the CSS more readable. Default is off.
No

Download Request Code Example
HCService.CssDownloadRequest request = new HCService.CssDownloadRequest();
request.MerchantID = "013163015566916";
request.Password = "KR568r@1spyC13,T";
request.Formatting = "on";

<!--Call the web service to initialize the DownloadCSS request.-->
HCService.HCService hcWS = new HCService.HCService();
HCService.CssDownloadResponse response = new HCService.CssDownloadResponse();
response = hcWS.DownloadCSS(request);

if (response != null)
{
this.txtCode.Text = response.ResponseCode.ToString();
this.txtResponseMsg.Text = response.Message;
this.txtCSS.Text = HttpUtility.HtmlDecode(response.Css);
}
else
<!--something seriously wrong. probably couldn't connect to the web service at all-->
this.txtResponseMsg.Text = "Response from DownloadCss was Null";

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 89 of 118
2014 Mercury

Input Parameters to CssRemoveRequest Method
Parameter Type Length Description Required
MerchantID Numeric 24 The Merchants account or MerchantID that payments
will be processed under. The typical format for a
Mercury Payment Systems merchant ID is: 88430087469
Please contact your developer integrations analyst for
the test MerchantID.
Yes
Password String 16 The web services password generated by the merchant
or dealer/developer on the MercuryView portal and
entered into the POS configuration screen to allow
access to the web service. Please contact your
developer integrations analyst for the test password.
Yes

Remove Request Code Example
HCService.CssRemoveRequest request = new HCService.CssRemoveRequest();
request.MerchantID = "013163015566916";
request.Password = "KR568r@1spyC13,T";

<!--Call the web service to initialize the DownloadCSS request.-->
HCService.HCService hcWS = new HCService.HCService();
HCService.CssAdminResponse response = new HCService.CssAdminResponse();
response = hcWS.RemoveCSS(request);

if (response != null)
{
this.txtCode.Text = response.ResponseCode.ToString();
this.txtResponseMsg.Text = response.Message;
this.txtCSS.Text = String.Empty;
}
else
<!--something seriously wrong. probably couldn't connect to the web service at all-->
this.txtResponseMsg.Text = "Response from RemoveCss was Null";



Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 90 of 118
2014 Mercury

Mercury CSS White List Rules
Release Summary
The 4.0.1.254 release of the whitelist adds the following capabilities:
1. New selectors:
a. #btnSubmitPOS
b. #btnCancelPOS
2. New pseudo-classes for all buttons:
a. :hover
b. :active
c. :disabled
d. :first-child
e. :focus
3. New properties:
a. background-position
b. border-top-right-radius
c. border-bottom-right-radius
d. border-top-left-radius
e. border-bottom-left-radius
f. box-shadow
g. filter
h. opacity
i. outline-offset
j. outline-width
k. outline-style
4. New values:
a. rgba color values added to most properties that use color
b. inline-block added as a valid value to display property

Standard colors
Selectors
Properties

<?xml version="1.0" encoding="utf-8" ?>
<mercury-css-whitelist-rules>
<!--
Whitelist XML v4.0.1.254
-->
<directives>
<directive name="maxInputSize" value="24000" />
</directives>
<common-regexps>
<regexp name="absolute-size" value="^(xx-small|x-small|small|medium|large|x-large|xx-
large)$" />
<regexp name="alphaNumeric" value="^[A-Za-z0-9 @\-_]*$" />
<regexp name="backgroundPos" value="^(0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?$" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 91 of 118
2014 Mercury

<regexp name="boxShadow_colorCode" value="^(0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?( #([0-9a-fA-F]{6}|[0-9a-fA-F]{3}))?( inset)?$" />
<regexp name="boxShadow_rgb" value="^(0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?(( rgb\((\d{1,3}),( )?(\d{1,3}),( )?(\d{1,3})\))?)(
inset)?$" />
<regexp name="boxShadow_rgba" value="^(0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?( (0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)))?(( rgba\((\d{1,3})\,( )?(\d{1,3})\,( )?(\d{1,3})\,(
)?(0?(\.\d+)?|1(\.0+)?)\))?)( inset)?$" />
<regexp name="colorName"
value="^(aqua|black|blue|fuchsia|gray|green|lime|maroon|navy|olive|purple|red|silver|
teal|white|yellow|orange)$" />
<!--
These are the 17 standard colors.
-->
<regexp name="colorCode" value="^(#([0-9a-fA-F]{6}|[0-9a-fA-F]{3}))$" />
<regexp name="cssSelector" value="^[a-z\.#][a-zA-Z0-9:_\. ]*$" />
<regexp name="cssProperty" value="^[a-z\-][a-z\-]*$" />
<regexp name="cssComment" value="^(\/\*[^*]*\*+([^/*][^*]*\*+)*\/)$" />
<regexp name="cssOffsiteUri"
value="^(url\((\s)*('http(s?)://)[\p{L}\p{N}]+[~\p{L}\p{N}\p{Zs}\-
_\.@#$%&;:,\?=/\+!]*\.(?:jpg|gif|png|bmp|jpeg|tif|pbm|pcd|pct|pcx|pdf|pds|pic|ps|pub|
ico)(\s)*'\))$" />
<regexp name="duration" value="^(0|([0-9]+(\.[0-9]+)?)(s|ms))$" />
<regexp name="filter" value="^(alpha\(opacity\=(\d{1,2}|100)\))$" />
<regexp name="length" value="^((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))$" />
<regexp name="linearGradient" value="^((linear-gradient\()(to
(top|bottom|left|right|top left| bottom left|top right|bottom right),( )?)?(#([0-9a-
fA-F]{6}|[0-9a-fA-F]{3}))((,( )?(#([0-9a-fA-F]{6}|[0-9a-fA-F]{3}))))+(\)))$" />
<regexp name="webkitLinearGradient" value="^(((-webkit|-o|-moz)-linear-
gradient\()((top|bottom|left|right|top left| bottom left|top right|bottom right),(
)?)?(#([0-9a-fA-F]{6}|[0-9a-fA-F]{3}))((,( )?(#([0-9a-fA-F]{6}|[0-9a-fA-
F]{3}))))+(\)))$" />
<regexp name="number" value="^(-|\+)?([0-9]+(\.[0-9]+)?)$" />
<regexp name="numberOrPercent" value="^(\d)+(%{0,1})$" />
<regexp name="opacity" value="^(0?(\.\d+)?|1(\.0+)?)$" />
<regexp name="percentage" value="^(-|\+)?([0-9]+(\.[0-9]+)?)%$" />
<regexp name="positiveLength" value="^((\+)?0|(\+)?([0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc))$" />
<regexp name="positivePercentage" value="^(\+)?([0-9]+(\.[0-9]+)?)%$" />
<regexp name="relative-size" value="^(larger|smaller)$" />
<regexp name="rgbCode" value="^(rgb\((\d{1,3}),( )?(\d{1,3}),( )?(\d{1,3})\))$" />
<regexp name="rgbaCode" value="^(rgba\((\d{1,3}),( )?(\d{1,3}),( )?(\d{1,3}),(
)?(0?(\.\d+)?|1(\.0+)?)\))$" />
<regexp name="systemColor"
value="^(activeborder|activecaption|appworkspace|background|buttonface|buttonhighligh
t|buttonshadow|buttontext|captiontext|graytext|highlight|highlighttext|inactiveborder
|inactivecaption|inactivecaptiontext|infobackground|infotext|menu|menutext|scrollbar|
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 92 of 118
2014 Mercury

threeddarkshadow|threedface|threedhighlight|threedlightshadow|threedshadow|window|win
dowframe|windowtext)$" />
<regexp name="textShadow_rgba" value="^((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) ((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) )?(rgba\((\d{1,3}),( )?(\d{1,3}), (\d{1,3}),(
)?(0?(\.\d+)?|1(\.0+)?)\))$" />
<regexp name="textShadow_rgb" value="^((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) ((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) )?(rgb\((\d{1,3}),( )?(\d{1,3}),( )?(\d{1,3})\))$"
/>
<regexp name="textShadow_colorCode" value="^((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) ((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) (((-|\+)?0|(-|\+)?((\.)?[0-9]+(\.[0-
9]+)?)(em|ex|px|in|cm|mm|pt|pc)) )?#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$" />
<regexp name="transition" value="^()$" />
</common-regexps>

<!--
These are the selectors that will be allowed.
-->
<selector-list>
<selector name="a" />
<selector name="a:hover" />
<selector name="#bodyCheckout" />
<selector name="body.bodyECommRedirect" />
<selector name="body.bodyECommIFrame" />
<selector name="body.bodyMobile" />
<selector name="body.bodyPOS" />
<selector name="body.bodyPOSIFrame" />
<selector name="body.bodyMobileIFrame" />
<selector name=".bodyECommRedirect" />
<selector name=".bodyECommIFrame" />
<selector name=".bodyMobile" />
<selector name=".bodyPOS" />
<selector name=".bodyPOSIFrame" />
<selector name=".bodyMobileIFrame" />
<selector name="#btnCancel" />
<selector name="#btnCancel:hover" />
<selector name="#btnCancel:active" />
<selector name="#btnCancel:disabled" />
<selector name="#btnCancel:first-child" />
<selector name="#btnCancel:focus" />
<selector name="#btnCancelPOS" />
<selector name="#btnCancelPOS:hover" />
<selector name="#btnCancelPOS:active" />
<selector name="#btnCancelPOS:disabled" />
<selector name="#btnCancelPOS:first-child" />
<selector name="#btnCancelPOS:focus" />
<selector name="#btnCancelMobile" />
<selector name="#btnCancelMobile:hover" />
<selector name="#btnCancelMobile:active" />
<selector name="#btnCancelMobile:disabled" />
<selector name="#btnCancelMobile:first-child" />
<selector name="#btnCancelMobile:focus" />
<selector name=".btnCSCHelp" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 93 of 118
2014 Mercury

<selector name=".btnCSCHelp:active" />
<selector name=".btnCSCHelp:hover" />
<selector name=".btnCSCHelp:disabled" />
<selector name=".btnCSCHelp:first-child" />
<selector name=".btnCSCHelp:focus" />
<selector name=".btnDefault" />
<selector name=".btnDefault:active" />
<selector name=".btnDefault:hover" />
<selector name=".btnDefault:disabled" />
<selector name=".btnDefault:first-child" />
<selector name=".btnDefault:focus" />
<selector name=".btnDefaultPOS" />
<selector name=".btnDefaultPOS:active" />
<selector name=".btnDefaultPOS:hover" />
<selector name=".btnDefaultPOS:disabled" />
<selector name=".btnDefaultPOS:first-child" />
<selector name=".btnDefaultPOS:focus" />
<selector name=".btnDefaultIFrame" />
<selector name=".btnDefaultIFrame:active" />
<selector name=".btnDefaultIFrame:hover" />
<selector name=".btnDefaultIFrame:disabled" />
<selector name=".btnDefaultIFrame:first-child" />
<selector name=".btnDefaultIFrame:focus" />
<selector name=".btnDefaultIFramePOS" />
<selector name=".btnDefaultIFramePOS:active" />
<selector name=".btnDefaultIFramePOS:hover" />
<selector name=".btnDefaultIFramePOS:disabled" />
<selector name=".btnDefaultIFramePOS:first-child" />
<selector name=".btnDefaultIFramePOS:focus" />
<selector name=".btnDefaultMobile" />
<selector name=".btnDefaultMobile:active" />
<selector name=".btnDefaultMobile:hover" />
<selector name=".btnDefaultMobile:disabled" />
<selector name=".btnDefaultMobile:first-child" />
<selector name=".btnDefaultMobile:focus" />
<selector name=".btnDefaultMobileIFrame" />
<selector name=".btnDefaultMobileIFrame:active" />
<selector name=".btnDefaultMobileIFrame:hover" />
<selector name=".btnDefaultMobileIFrame:disabled" />
<selector name=".btnDefaultMobileIFrame:first-child" />
<selector name=".btnDefaultMobileIFrame:focus" />
<selector name=".btnDialog" />
<selector name=".btnDialog:active" />
<selector name=".btnDialog:hover" />
<selector name=".btnDialog:disabled" />
<selector name=".btnDialog:first-child" />
<selector name=".btnDialog:focus" />
<selector name=".btnDisabledPOS" />
<selector name=".btnKeypad" />
<selector name=".btnKeypad:hover" />
<selector name=".btnKeypad:active" />
<selector name=".btnKeypad:disabled" />
<selector name=".btnKeypad:first-child" />
<selector name=".btnKeypad:focus" />
<selector name=".btnKeypad0" />
<selector name=".btnKeypad0:hover" />
<selector name=".btnKeypad0:active" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 94 of 118
2014 Mercury

<selector name=".btnKeypad0:disabled" />
<selector name=".btnKeypad0:first-child" />
<selector name=".btnKeypad0:focus" />
<selector name="#btnPayment" />
<selector name="#btnPayment:hover" />
<selector name="#btnPayment:active" />
<selector name="#btnPayment:disabled" />
<selector name="#btnPayment:first-child" />
<selector name="#btnPayment:focus" />
<selector name="#btnSubmitMobile" />
<selector name="#btnSubmitMobile:hover" />
<selector name="#btnSubmitMobile:active" />
<selector name="#btnSubmitMobile:disabled" />
<selector name="#btnSubmitMobile:first-child" />
<selector name="#btnSubmitMobile:focus" />
<selector name="#btnSubmitPOS" />
<selector name="#btnSubmitPOS:hover" />
<selector name="#btnSubmitPOS:active" />
<selector name="#btnSubmitPOS:disabled" />
<selector name="#btnSubmitPOS:first-child" />
<selector name="#btnSubmitPOS:focus" />
<selector name=".btnTermsOfUse" />
<selector name=".btnTermsOfUse:active" />
<selector name=".btnTermsOfUse:hover" />
<selector name=".btnTermsOfUse:disabled" />
<selector name=".btnTermsOfUse:first-child" />
<selector name=".btnTermsOfUse:focus" />
<selector name="#btnUpdateMobile" />
<selector name="#btnUpdateMobile:hover" />
<selector name="#btnUpdateMobile:active" />
<selector name="#btnUpdateMobile:disabled" />
<selector name="#btnUpdateMobile:first-child" />
<selector name="#btnUpdateMobile:focus" />
<selector name="#btnUpdateCard" />
<selector name="#btnUpdateCard:hover" />
<selector name="#btnUpdateCard:active" />
<selector name="#btnUpdateCard:disabled" />
<selector name="#btnUpdateCard:first-child" />
<selector name="#btnUpdateCard:focus" />
<selector name="#btnUpdatePOS" />
<selector name="#btnUpdatePOS:hover" />
<selector name="#btnUpdatePOS:active" />
<selector name="#btnUpdatePOS:disabled" />
<selector name="#btnUpdatePOS:first-child" />
<selector name="#btnUpdatePOS:focus" />
<selector name="#divButtons" />
<selector name="#divButtonsIFrame" />
<selector name="#divButtonsMobile" />
<selector name="#divButtonsMobileIFrame" />
<selector name="#divButtonsPOS" />
<selector name=".divCSCHelpDialog" />
<selector name="#divCSCHelpText" />
<selector name="#divDiners" />
<selector name="#divFooter" />
<selector name="#divFooterMobile" />
<selector name="#divFooterMobileIFrame" />
<selector name="#divHeaderImage" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 95 of 118
2014 Mercury

<selector name="#divHeaderImageMobile" />
<selector name="#divHeaderImagePOS" />
<selector name="#divHeaderImageIFrame" />
<selector name="#divHeaderImageMobileIFrame" />
<selector name="#divHeaderMobile" />
<selector name="#divHeaderLine" />
<selector name="#divHeaderPOS" />
<selector name="#divHeaderPOSIFrame" />
<selector name=".divHeaderText" />
<selector name=".divHeaderTextIFrame" />
<selector name="#divHelpButton" />
<selector name=".divHR" />
<selector name="#divJCB" />
<selector name="#divKeypad" />
<selector name="#divKeypadIFrame" />
<selector name=".divKeypad" />
<selector name=".divKeypadAddCard" />
<selector name=".divKeypadIFrame" />
<selector name=".divLabel" />
<selector name=".divLabelIFrame" />
<selector name=".divLabelMobile" />
<selector name=".divLabelMobileIFrame" />
<selector name=".divLabelPOS" />
<selector name=".divLine" />
<selector name=".divLineIFrame" />
<selector name=".divLineMobile" />
<selector name=".divLineMobileIFrame" />
<selector name=".divLinePOS" />
<selector name=".divLogo" />
<selector name=".divLogoMobile" />
<selector name=".divLogoMobileIFrame" />
<selector name="#divLogoContainer" />
<selector name="#divLogoContainerIFrame" />
<selector name="#divLogoContainerMobile" />
<selector name=".divLogoContainerMobileIFrame" />
<selector name="#divMain" />
<selector name="#divMainIFrame" />
<selector name="#divMainMobileIFrame" />
<selector name="#divMainMobile" />
<selector name="#divMainPOS" />
<selector name="#divMainPOSIFrame" />
<selector name="#divProgress" />
<selector name="#divProgressMobile" />
<selector name="#divProgressMobileIFrame" />
<selector name="#divProgressImage" />
<selector name="#divProgressImageMobile" />
<selector name="#divProgressImageMobileIFrame" />
<selector name="#divProgressOverlay" />
<selector name="#divProgressOverlayMobile" />
<selector name="#divProgressOverlayMobileIFrame" />
<selector name="#divProgressText" />
<selector name="#divProgressTextMobile" />
<selector name="#divProgressTextMobileIFrame" />
<selector name="#divRadioButtonsPOS" />
<selector name=".divSecurityLogo" />
<selector name=".divSecurityLogoIFrame" />
<selector name="#divSpacing" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 96 of 118
2014 Mercury

<selector name="#divSummaryError" />
<selector name="#divSummaryErrorIFrame" />
<selector name="#divSummaryErrorMobile" />
<selector name="#divSummaryErrorMobileIFrame" />
<selector name="#divTermsOfUse" />
<selector name="#divTermsOfUseContainer" />
<selector name="#divTermsOfUseHeader" />
<selector name="#divTermsOfUseLegal" />
<selector name="#divTermsOfUseSubHeader" />
<selector name="#divTermsOfUseText" />
<selector name=".divTextBox" />
<selector name=".divTextBoxIFrame" />
<selector name=".divTextBoxMobile" />
<selector name=".divTextBoxMobileIFrame" />
<selector name=".divTextBoxPOS" />
<selector name="#divTimer" />
<selector name="#divTimerIFrame" />
<selector name="#divTimerMobile" />
<selector name="#divTimerPOS" />
<selector name=".divTotalDefault" />
<selector name=".divTotalMobileDefault" />
<selector name=".divTotalMobileIFrameDefault" />
<selector name=".divTotalPOSDefault" />
<selector name=".divTotalIFrameDefault" />
<selector name=".divTotalPOSIFrameDefault" />
<selector name="#divUserInput" />
<selector name="#divUserInputPOS" />
<selector name="#divUserInputPOSIFrame" />
<selector name=".divValidatorIFrame" />
<selector name=".divValidators" />
<selector name=".divValidatorsPOS" />
<selector name=".imgCardLogo" />
<selector name=".imgCardLogoIFrame" />
<selector name="#imgHeader" />
<selector name=".imgHeaderMobile" />
<selector name=".imgLogoMobile" />
<selector name=".imgMercurySecurityLogo" />
<selector name="#keypadContainer" />
<selector name=".lblDefault" />
<selector name=".lblDefaultPOS" />
<selector name=".lblFooter" />
<selector name=".lblFooterMobile" />
<selector name=".lblFooterMobileIFrame" />
<selector name=".lblGeneralError" />
<selector name=".lblGeneralErrorMobile" />
<selector name=".lblGeneralErrorMobileIFrame" />
<selector name=".lblHeader" />
<selector name=".lblHeaderPOS" />
<selector name=".lblMobile" />
<selector name=".lblMobileIFrame" />
<selector name="#lblNameMobileIFrame" />
<selector name="#lblProgress" />
<selector name=".lblTimeout" />
<selector name=".lblTimeoutIndicator" />
<selector name=".lblTimeoutIndicatorMobile" />
<selector name=".lblTimeoutMobile" />
<selector name=".lblTimeoutMobileIFrame" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 97 of 118
2014 Mercury

<selector name=".lblTimeoutIndicatorMobileIFrame" />
<selector name=".lblTotalAmount" />
<selector name=".lblTotalAmountMobile" />
<selector name=".lblTotalAmountMobileIFrame" />
<selector name=".lblTotalAmountPOS" />
<selector name="#lblTotalAmountValue" />
<selector name=".lblValidationError" />
<selector name=".lblValidatorMobile" />
<selector name=".lblValidatorMobileIFrame" />
<selector name="#popup_container" />
<selector name="#popup_content" />
<selector name="#popup_content.alert" />
<selector name="#popup_content.confirm" />
<selector name="#popup_content.prompt" />
<selector name="#popup_container input" />
<selector name="#popup_container input:hover" />
<selector name="#popup_message" />
<selector name="#popup_panel" />
<selector name="#popup_prompt" />
<selector name="#popup_title" />
<selector name=".radioButtonSelected" />
<selector name=".radioButtonDefault" />
<selector name=".radioBtnListPOS" />
<selector name=".txtCustom" />
<selector name="#txtAddress" />
<selector name="#txtAddressPOS" />
<selector name="#txtAuthCodePOS" />
<selector name="#txtCardSwipePOS" />
<selector name=".txtDefaultMobile" />
<selector name=".txtDefaultMobileIFrame" />
<selector name=".txtDisabledPOS" />
<selector name="#txtCardNumber" />
<selector name="#txtCardNumberPOS" />
<selector name="#txtExpirationDate" />
<selector name="#txtExpirationDatePOS" />
<selector name="#txtCSCValue" />
<selector name="#txtCSCValuePOS" />
<selector name="#txtNameOnCard" />
<selector name=".txtPOS" />
<selector name="#txtZip" />
<selector name="#txtZipPOS" />
<selector name="#uctlKeyPad_btn1" />
<selector name="#uctlKeyPad_btn1:active" />
<selector name="#uctlKeyPad_btn1:hover" />
<selector name="#uctlKeyPad_btn1:disabled" />
<selector name="#uctlKeyPad_btn1:first-child" />
<selector name="#uctlKeyPad_btn1:focus" />
<selector name="#uctlKeyPad_btn2" />
<selector name="#uctlKeyPad_btn2:active" />
<selector name="#uctlKeyPad_btn2:hover" />
<selector name="#uctlKeyPad_btn2:disabled" />
<selector name="#uctlKeyPad_btn2:first-child" />
<selector name="#uctlKeyPad_btn2:focus" />
<selector name="#uctlKeyPad_btn3" />
<selector name="#uctlKeyPad_btn3:active" />
<selector name="#uctlKeyPad_btn3:hover" />
<selector name="#uctlKeyPad_btn3:disabled" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 98 of 118
2014 Mercury

<selector name="#uctlKeyPad_btn3:first-child" />
<selector name="#uctlKeyPad_btn3:focus" />
<selector name="#uctlKeyPad_btn4" />
<selector name="#uctlKeyPad_btn4:active" />
<selector name="#uctlKeyPad_btn4:hover" />
<selector name="#uctlKeyPad_btn4:disabled" />
<selector name="#uctlKeyPad_btn4:first-child" />
<selector name="#uctlKeyPad_btn4:focus" />
<selector name="#uctlKeyPad_btn5" />
<selector name="#uctlKeyPad_btn5:active" />
<selector name="#uctlKeyPad_btn5:hover" />
<selector name="#uctlKeyPad_btn5:disabled" />
<selector name="#uctlKeyPad_btn5:first-child" />
<selector name="#uctlKeyPad_btn5:focus" />
<selector name="#uctlKeyPad_btn6" />
<selector name="#uctlKeyPad_btn6:active" />
<selector name="#uctlKeyPad_btn6:hover" />
<selector name="#uctlKeyPad_btn6:disabled" />
<selector name="#uctlKeyPad_btn6:first-child" />
<selector name="#uctlKeyPad_btn6:focus" />
<selector name="#uctlKeyPad_btn7" />
<selector name="#uctlKeyPad_btn7:active" />
<selector name="#uctlKeyPad_btn7:hover" />
<selector name="#uctlKeyPad_btn7:disabled" />
<selector name="#uctlKeyPad_btn7:first-child" />
<selector name="#uctlKeyPad_btn7:focus" />
<selector name="#uctlKeyPad_btn8" />
<selector name="#uctlKeyPad_btn8:active" />
<selector name="#uctlKeyPad_btn8:hover" />
<selector name="#uctlKeyPad_btn8:disabled" />
<selector name="#uctlKeyPad_btn8:first-child" />
<selector name="#uctlKeyPad_btn8:focus" />
<selector name="#uctlKeyPad_btn9" />
<selector name="#uctlKeyPad_btn9:active" />
<selector name="#uctlKeyPad_btn9:hover" />
<selector name="#uctlKeyPad_btn9:disabled" />
<selector name="#uctlKeyPad_btn9:first-child" />
<selector name="#uctlKeyPad_btn9:focus" />
<selector name="#uctlKeyPad_btn0" />
<selector name="#uctlKeyPad_btn0:active" />
<selector name="#uctlKeyPad_btn0:hover" />
<selector name="#uctlKeyPad_btn0:disabled" />
<selector name="#uctlKeyPad_btn0:first-child" />
<selector name="#uctlKeyPad_btn0:focus" />
<selector name="#uctlKeyPad_btnErase" />
<selector name="#uctlKeyPad_btnErase:active" />
<selector name="#uctlKeyPad_btnErase:hover" />
<selector name="#uctlKeyPad_btnErase:disabled" />
<selector name="#uctlKeyPad_btnErase:first-child" />
<selector name="#uctlKeyPad_btnErase:focus" />
<selector name=".watermarkCustom" />
<selector name=".watermarkDefault" />
</selector-list>

Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 99 of 118
2014 Mercury

<!--
This is the list of allowed properties
-->
<property-list>
<property name="background-color">
<literal-list>
<literal value="transparent" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="background-image">
<literal-list>
<literal value="none" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="cssOffsiteUri" />
<regexp name="linearGradient" />
<regexp name="webkitLinearGradient" />
</regexp-list>
</property>
<property name="background-position">
<literal-list>
<literal value="left top" />
<literal value="left center" />
<literal value="left bottom" />
<literal value="right top" />
<literal value="right center" />
<literal value="right bottom" />
<literal value="center top" />
<literal value="center center" />
<literal value="center bottom" />
<literal value="left" />
<literal value="center" />
<literal value="top" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="backgroundPos" />
</regexp-list>
</property>
<property name="background-repeat">
<literal-list>
<literal value="repeat" />
<literal value="repeat-x" />
<literal value="repeat-y" />
<literal value="no-repeat" />
<literal value="inherit" />
</literal-list>
</property>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 100 of 118
2014 Mercury

<!--
background-size is a CSS3 property, not supported in all browsers
-->
<property name="background-size">
<literal-list>
<literal value="inherit" />
<literal value="cover" />
</literal-list>
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border-collapse">
<literal-list>
<literal value="collapse" />
<literal value="separate" />
<literal value="inherit" />
</literal-list>
</property>
<property name="border-color">
<literal-list>
<literal value="transparent" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-top-left-radius">
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border-top-right-radius">
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border-bottom-left-radius">
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 101 of 118
2014 Mercury

</regexp-list>
</property>
<property name="border-bottom-right-radius">
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border-radius">
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border-top-color">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-right-color">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-bottom-color">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-left-color">
<literal-list>
<literal value="inherit" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 102 of 118
2014 Mercury

</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-spacing">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="bottom">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="box-shadow">
<literal-list>
<literal value="none" />
</literal-list>
<regexp-list>
<regexp name="boxShadow_rgba" />
<regexp name="boxShadow_rgb" />
<regexp name="boxShadow_colorCode" />
</regexp-list>
</property>
<property name="clear">
<literal-list>
<literal value="none" />
<literal value="left" />
<literal value="right" />
<literal value="both" />
<literal value="inherit" />
</literal-list>
</property>
<property name="color">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 103 of 118
2014 Mercury

</regexp-list>
</property>
<property name="cursor">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
<literal value="crosshair" />
<literal value="default" />
<literal value="e-resize" />
<literal value="help" />
<literal value="move" />
<literal value="n-resize" />
<literal value="ne-resize" />
<literal value="nw-resize" />
<literal value="pointer" />
<literal value="progress" />
<literal value="s-resize" />
<literal value="se-resize" />
<literal value="sw-resize" />
<literal value="text" />
<literal value="w-resize" />
<literal value="wait" />
</literal-list>
</property>
<property name="direction">
<literal-list>
<literal value="ltr" />
<literal value="rtl" />
<literal value="inherit" />
</literal-list>
</property>
<property name="display">
<literal-list>
<literal value="inline" />
<literal value="inline-block" />
<literal value="block" />
<literal value="list-item" />
<literal value="run-in" />
<literal value="compact" />
<literal value="marker" />
<literal value="table" />
<literal value="inline-table" />
<literal value="table-row-group" />
<literal value="table-header-group" />
<literal value="table-footer-group" />
<literal value="table-row" />
<literal value="table-column-group" />
<literal value="table-column" />
<literal value="table-cell" />
<literal value="table-caption" />
<literal value="none" />
<literal value="inherit" />
</literal-list>
</property>
property name="filter">
<regexp-list>
<regexp name="filter" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 104 of 118
2014 Mercury

</regexp-list>
</property>
<property name="float">
<literal-list>
<literal value="left" />
<literal value="right" />
<literal value="none" />
<literal value="inherit" />
</literal-list>
</property>
<property name="font-size">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="font-size-adjust">
<literal-list>
<literal value="none" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="number" />
</regexp-list>
</property>
<property name="font-stretch">
<literal-list>
<literal value="normal" />
<literal value="wider" />
<literal value="narrower" />
<literal value="ultra-condensed" />
<literal value="extra-condensed" />
<literal value="condensed" />
<literal value="semi-condensed" />
<literal value="semi-expanded" />
<literal value="expanded" />
<literal value="extra-expanded" />
<literal value="ultra-expanded" />
<literal value="inherit" />
</literal-list>
</property>
<property name="font-style">
<literal-list>
<literal value="normal" />
<literal value="italic" />
<literal value="oblique" />
<literal value="inherit" />
</literal-list>
</property>
<property name="font-variant">
<literal-list>
<literal value="normal" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 105 of 118
2014 Mercury

<literal value="small-caps" />
<literal value="inherit" />
</literal-list>
</property>
<property name="font-weight">
<literal-list>
<literal value="normal" />
<literal value="bold" />
<literal value="bolder" />
<literal value="lighter" />
<literal value="100" />
<literal value="200" />
<literal value="300" />
<literal value="400" />
<literal value="500" />
<literal value="600" />
<literal value="700" />
<literal value="800" />
<literal value="900" />
<literal value="inherit" />
</literal-list>
</property>
<property name="height">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="left">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="letter-spacing">
<literal-list>
<literal value="normal" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="line-height">
<literal-list>
<literal value="normal" />
<literal value="inherit" />
</literal-list>
<regexp-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 106 of 118
2014 Mercury

<regexp name="number" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="max-height">
<literal-list>
<literal value="none" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="max-width">
<literal-list>
<literal value="none" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="min-height">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="min-width">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="opacity">
<regexp-list>
<regexp name="opacity" />
</regexp-list>
</property>
<property name="outline-color">
<literal-list>
<literal value="invert" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 107 of 118
2014 Mercury

<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="outline-offset">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="outline-style">
<literal-list>
<literal value="none" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
<literal value="inherit" />
</literal-list>
</property>
<property name="outline-width">
<literal-list>
<literal value="thin" />
<literal value="thick" />
<literal value="medium" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="overflow">
<literal-list>
<literal value="visible" />
<literal value="hidden" />
<literal value="scroll" />
<literal value="auto" />
<literal value="inherit" />
</literal-list>
</property>
<property name="padding-top">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-right">
<literal-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 108 of 118
2014 Mercury

<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-bottom">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-left">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="position">
<literal-list>
<literal value="static" />
<!--
possible to perform phishing attacks with the following
-->
<!--
<literal value="relative"/>
<literal value="absolute"/>
<literal value="fixed"/>

-->
<literal value="inherit" />
</literal-list>
</property>
<property name="right">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="size">
<literal-list>
<literal value="auto" />
<literal value="portrait" />
<literal value="landscape" />
<literal value="inherit" />
</literal-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 109 of 118
2014 Mercury

<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="text-indent">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="text-transform">
<literal-list>
<literal value="capitalize" />
<literal value="uppercase" />
<literal value="lowercase" />
<literal value="none" />
<literal value="inherit" />
</literal-list>
</property>
<property name="top">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="vertical-align">
<literal-list>
<literal value="baseline" />
<literal value="sub" />
<literal value="super" />
<literal value="top" />
<literal value="text-top" />
<literal value="middle" />
<literal value="bottom" />
<literal value="text-bottom" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="percentage" />
<regexp name="length" />
</regexp-list>
</property>
<property name="visibility">
<literal-list>
<literal value="visible" />
<literal value="hidden" />
<literal value="collapse" />
<literal value="inherit" />
</literal-list>
</property>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 110 of 118
2014 Mercury

<property name="white-space">
<literal-list>
<literal value="normal" />
<literal value="pre-line" />
<literal value="nowrap" />
<literal value="inherit" />
<literal value="pre-wrap" />
<literal value="pre" />
</literal-list>
</property>
<property name="width">
<literal-list>
<literal value="auto" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="word-spacing">
<literal-list>
<literal value="normal" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<!--
end simple properties
-->
<property name="border-style">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="hidden" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
</literal-list>
</property>
<property name="border-top-style">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="hidden" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 111 of 118
2014 Mercury

<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
</literal-list>
</property>
<property name="border-right-style">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="hidden" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
</literal-list>
</property>
<property name="border-bottom-style">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="hidden" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
</literal-list>
</property>
<property name="border-left-style">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="hidden" />
<literal value="dotted" />
<literal value="dashed" />
<literal value="solid" />
<literal value="double" />
<literal value="groove" />
<literal value="ridge" />
<literal value="inset" />
<literal value="outset" />
</literal-list>
</property>
<property name="border-top-width">
<literal-list>
<literal value="inherit" />
<literal value="thin" />
<literal value="medium" />
<literal value="thick" />
</literal-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 112 of 118
2014 Mercury

<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="border-right-width">
<literal-list>
<literal value="inherit" />
<literal value="thin" />
<literal value="medium" />
<literal value="thick" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="border-bottom-width">
<literal-list>
<literal value="inherit" />
<literal value="thin" />
<literal value="medium" />
<literal value="thick" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="border-left-width">
<literal-list>
<literal value="inherit" />
<literal value="thin" />
<literal value="medium" />
<literal value="thick" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="border-width">
<literal-list>
<literal value="inherit" />
<literal value="thin" />
<literal value="medium" />
<literal value="thick" />
</literal-list>
<regexp-list>
<regexp name="length" />
</regexp-list>
</property>
<property name="margin">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="positivePercentage" />
</regexp-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 113 of 118
2014 Mercury

</property>
<property name="margin-top">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="positivePercentage" />
</regexp-list>
</property>
<property name="margin-right">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="positivePercentage" />
</regexp-list>
</property>
<property name="margin-bottom">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="positivePercentage" />
</regexp-list>
</property>
<property name="margin-left">
<literal-list>
<literal value="inherit" />
<literal value="auto" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="positivePercentage" />
</regexp-list>
</property>
<property name="padding">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-top">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 114 of 118
2014 Mercury

</regexp-list>
</property>
<property name="padding-right">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-bottom">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="padding-left">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="border">
<literal-list>
<literal value="inherit" />
<literal value="none" />
<literal value="0" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-top">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-right">
<literal-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 115 of 118
2014 Mercury

<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-bottom">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="border-left">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="colorName" />
<regexp name="colorCode" />
<regexp name="rgbCode" />
<regexp name="rgbaCode" />
<regexp name="systemColor" />
</regexp-list>
</property>
<property name="font-size">
<literal-list>
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="absolute-size" />
<regexp name="relative-size" />
<regexp name="length" />
<regexp name="percentage" />
</regexp-list>
</property>
<property name="text-decoration">
<literal-list>
<literal value="none" />
<literal value="underline" />
<literal value="overline" />
<literal value="line-through" />
<literal value="blink" />
<literal value="inherit" />
</literal-list>
</property>
<property name="text-shadow">
<literal-list>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 116 of 118
2014 Mercury

<literal value="none" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="textShadow_rgba" />
<regexp name="textShadow_rgb" />
<regexp name="textShadow_colorCode" />
</regexp-list>
</property>
<property name="font-family">
<literal-list>
<literal value="serif" />
<literal value="arial" />
<literal value="lucida console" />
<literal value="sans-serif" />
<literal value="cursive" />
<literal value="verdana" />
<literal value="fantasy" />
<literal value="monospace" />
</literal-list>
<regexp-list>
<regexp name="alphaNumeric" />
</regexp-list>
</property>
<property name="text-align">
<!--
For safety, ignoring string alignment which can be used to line table cells on
characters
-->
<literal-list>
<literal value="left" />
<literal value="right" />
<literal value="center" />
<literal value="justify" />
<literal value="inherit" />
</literal-list>
</property>
<property name="transition-delay">
<regexp-list>
<regexp name="duration" />
</regexp-list>
</property>
<property name="-webkit-transition-delay">
<regexp-list>
<regexp name="duration" />
</regexp-list>
</property>
<property name="transition-duration">
<regexp-list>
<regexp name="duration" />
</regexp-list>
</property>
<property name="-webkit-transition-duration">
<regexp-list>
<regexp name="duration" />
</regexp-list>
</property>
Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 117 of 118
2014 Mercury

<property name="transition-property">
<literal-list>
<literal value="none" />
<literal value="all" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="alphaNumeric" />
</regexp-list>
</property>
<property name="-webkit-transition-property">
<literal-list>
<literal value="none" />
<literal value="all" />
<literal value="inherit" />
</literal-list>
<regexp-list>
<regexp name="alphaNumeric" />
</regexp-list>
</property>
<property name="transition-timing-function">
<literal-list>
<literal value="linear" />
<literal value="ease" />
<literal value="ease-in" />
<literal value="ease-out" />
<literal value="ease-in-out" />
</literal-list>
</property>
<property name="-webkit-transition-timing-function">
<literal-list>
<literal value="linear" />
<literal value="ease" />
<literal value="ease-in" />
<literal value="ease-out" />
<literal value="ease-in-out" />
</literal-list>
</property>
</property-list>
</mercury-css-whitelist-rules>


Hosted Checkout for eCommerce Integration Guide

HostedCheckout eCom Integration Guide 03262014 Page 118 of 118
2014 Mercury

Appendix 5: List of Acronyms

Acronym Definition
AVS Address Verification Service
BID Business ID
BIN Bank Identification Number
CRC Cycle Redundancy Check
CVV Cardholder Verification Value
FSA Flexible Spending Account
MID Merchant ID
PA-DSS Payment Application Data Security Standard
PCI Payment Card Industry
POS Point of Sale
QSR Quick Service Restaurant
SOAP Simple Object Access Protocol
TID Terminal ID