hostedcheckout ecom integration guide 03262014 pdf

Hosted CheckoutTM for eCommerce Integration Guide

With Integrated MTokenTM 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.



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 to

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.



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.


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 - 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



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



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



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



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.



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



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




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




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




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



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

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"];

HCService.InitPaymentRequest hcRequest = new HCService.InitPaymentRequest();

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";

HCService.HCService hcWS = new HCService.HCService(); HCService.InitPaymentResponse response = hcWS.InitializePayment(hcRequest);



if (response.ResponseCode == 0) { txtPaymentID.Text = response.PaymentID; }

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)


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.

String hostedCheckoutURL = ConfigurationManager.AppSettings[HostedCheckoutURL]; string paymentID = this.txtPaymentID.Text; Response.Clear(); Response.Write(); Response.Write(); Response.Write(); Response.Write();



Response.Write(); Response.Write(); 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)


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: 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.

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.



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.


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




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


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:




Input Parameters


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



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.



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



VerifyPayment Web Method Sample Code

This sample calls the VerifyPayment web method and displays the response information. HCService.PaymentInfoRequest verifyPaymentRequest = new HCService.PaymentInfoRequest(); verifyPaymentRequest.MerchantID = System.Configuration.ConfigurationManager.AppSettings["MerchantID"]; verifyPaymentRequest.Password = System.Configuration.ConfigurationManager.AppSettings["HCPassword"]; verifyPaymentRequest.PaymentID = txtPaymentID.Text; HCService.HCService hcService = new HCService.HCService(); HCService.PaymentInfoResponse response = hcService.VerifyPayment(verifyPaymentRequest); this.lblVerifyInfo.Text = "ResponseCode=" + response.Status + ""; this.lblVerifyInfo.Text += "Status=" + response.Status + ""; this.lblVerifyInfo.Text += "StatusMessage=" + response.Status + ""; this.lblVerifyInfo.Text += "DisplayMessage=" + response.Status + ""; this.lblVerifyInfo.Text += "Token=" + response.Token + ""; this.lblVerifyInfo.Text += "AuthCode=" + response.AuthCode + ""; this.lblVerifyInfo.Text += "AvsResult: " + response.AvsResult + ""; this.lblVerifyInfo.Text += "CvvResult: " + response.CvvResult + ""; this.lblVerifyInfo.Text += "CardType: " + response.CardType + ""; this.lblVerifyInfo.Text += "RefNo: " + response.RefNo + ""; this.lblVerifyInfo.Text += "Invoice: " + response.Invoice + ""; this.lblVerifyInfo.Text += "AcqRefData: " + response.AcqRefData + ""; this.lblVerifyInfo.Text += "TaxAmount: " + response.TaxAmount + ""; this.lblVerifyInfo.Text += "TransPostTime: " + response.TransPostTime + ""; this.lblVerifyInfo.Text += "Masked Acct: " + response.MaskedAccount + ""; this.lblVerifyInfo.Text += "Amount: " + response.Amount + ""; this.lblVerifyInfo.Text += "Cardholder Name: " + response.CardholderName + ""; this.lblVerifyInfo.Text += "AVS Address: " + response.AVSAddress + ""; this.lblVerifyInfo.Text += "AVS Zip: " + response.AVSZip + ""; this.lblVerifyInfo.Text += "Tran Type: " + response.TranType + ""; this.lblVerifyInfo.Text += "Payment ID Expired: " + response.PaymentIDExpired.ToString() + ""; this.lblVerifyInfo.Text += "Customer Code: " + response.CustomerCode + ""; this.lblVerifyInfo.Text += "Memo: " + response.Memo + "";

Figure 11. Code Example: VerifyPayment Web Method



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:




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




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




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


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 unlimited

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



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

string returnURL = "http://localhost:4307/CardInfo_SampleCode.aspx"; string orderCompleteURL = "http://localhost:4307/CardInfo_SampleCode.aspx"; string logoURL = ConfigurationManager.AppSettings["LogoURL"];

HCService.InitCardInfoRequest hcRequest = new HCService.InitCardInfoRequest();

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";

HCService.HCService hcWS = new HCService.HCService(); HCService.InitCardInfoResponse response = hcWS.InitializeCardInfo(hcRequest); if (response.ResponseCode == 0) { txtCardID.Text = response.CardID; } 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."



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.

string addCardURL = ConfigurationManager.AppSettings["CardInfoURL"]; string CardID = this.txtCardID.Text;

Response.Clear(); Response.Write(""); Response.Write(""); Response.Write(""); Response.Write(""); Response.Write(""); Response.Write(""); 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.



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.

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.

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.


src= https://hc.mercurydev.net/CardInfoiFrame.aspx?cardID=e727bd2e-c1ae-43c9-aadb-e20fd604ae4e;ReturnMethod=get

Example HTML



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.



Fields Returned in Form Post to the ProcessCompleteURL


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


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



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:




Input Parameters


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



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 res

hostedcheckout ecom integration guide 03262014 pdf

Documents

llc mercury

mercury products

mercury platform

mercury hosted checkout

mercury payment systems

restricted use terms

available integration

hosted checkouttm