cresecure hpp integration guide

Document Revision 100609

HOSTED PAYMENT PAGE (HPP) WITH HTML CLONE™

INTEGRATION GUIDE

Copyright Information

The information contained herein is the confidential and proprietary property of CRE Secure Payments, LLC. and may not be used, distributed, modified, disclosed, or reproduced without the express written permission of CRE Secure Payments, LLC.

Copyright 2009 CRE Secure Payments, LLC. All rights reserved.

CRE SECURE HOSTED PAYMENT PAGE | INTEGRATION GUIDE

DOCUMENT REVISION 100609

TABLE OF CONTENTS - I

Copyright 2009 CRE Secure Payments, LLC. All rights reserved.

TABLE OF CONTENTS About This Document ......................................................................................................... 1

Purpose of this Document ................................................................................................................ 1 Intended Audiences ......................................................................................................................... 1 Document Conventions .................................................................................................................... 1

Additional Resources .......................................................................................................... 2 Merchant Guides .............................................................................................................................. 2 Developer Support ........................................................................................................................... 2

Introduction ........................................................................................................................ 3 How It Works ...................................................................................................................... 4

Step-by-step of How CRE Secure HPP Works with HTML Clone Technology .................................. 4 Payment Request Form: Posting to the Hosted Payment Page............................................. 5 Merchant Payment Template Page...................................................................................... 8 Transaction Success Response Page ............................................................................... 12 Live Demos of CRE Secure HPP....................................................................................... 13 Sample of the CRE Secure HPP payment form HTML ....................................................... 13 Sample Merchant HTML Code for Payment Request Form ................................................ 16 Sandbox and Testing Environment .................................................................................... 18 Test Credit Card Numbers ................................................................................................ 19

LIST OF FIGURES Figure 1: Unstyled Payment Form ............................................................................................................ 9 Figure 2: Styled Payment Form Example ................................................................................................. 9 Figure 3: Before: Sample merchant payment template page as retrieved by CRE Secure HPP server.... 10 Figure 4: After: Sample CRE Secure HPP incorporating the merchant payment template page presented to the customer ...................................................................................................................................... 11

LIST OF TABLES Table 1: Style Conventions Used in This Document ................................................................................. 1 Table 2: Transaction Response Data ..................................................................................................... 12 Table 3: Sample payment template pages ............................................................................................. 13 Table 4: Testing Sandbox Credentials ................................................................................................... 18 Table 5: Test Credit Card Numbers........................................................................................................ 19


ABOUT THIS DOCUMENT - 1

About This Document Purpose of this Document This guide provides an overview of the components and concepts related to the development of client applications that utilize CRE Secure Hosted Payment Page, as well as instructions for implementing the Hosted Payment services.

Intended Audiences This guide is for developers who want to implement CRE Secure Hosted Payment Page in order to integrate hosted payment services with their applications.

Document Conventions This guide uses the style conventions listed below:

CONVENTION DESCRIPTION

Hyperlinks Hyperlinks in this document point to web content and internal references related or supporting content within this document.

Code Objects Development objects are presented in Courier New type and highlight API operations and objects such as GetServiceInformation()and ApplicationData.

Supporting Material References to file paths, external files, and supporting documents, appear in italics.

Note: Notes and related resources are presented in Arial 9pt type and are emphasized with a border above and below.

Important! Cautionary notes are designated with a Caution icon that alerts you to circumstances in which a given action may have potentially serious functional implications.

Sample Code Sample code is presented in Courier New 9pt type with a shaded background.

Table 1: Style Conventions Used in This Document


ABOUT THIS DOCUMENT - 2

Additional Resources The following resources provide additional information that can be referenced as supplemental material to this guide.

Merchant Guides Along with this custom integration guide, CRE Secure Payments, LLC provides a PCI Compliance Implementation Guide for merchants. The Implementation Guide is an overview of all the PCI Compliance paperwork and references needed to satisfy the PCI Compliance burden for a merchant.

Developer Support

Download Center Access resources to support your integration from the CRE Secure Download Center by visiting http://www.cresecure.com/pages.php?CDpath=5_8

Support Email [email protected]

Live Chat http://www.cresecure.com

Contact us with any support questions by visiting: http://www.cresecure.com/fss_forms_detail.php?forms_id=4&CDpath=13_27

CRE Secure Payments, LLC. 112 Krog Street, Suite 19 Atlanta, Georgia 30307 USA Phone: (404) 961-9840 Fax: (404) 961-9853

www.cresecure.com

http://www.cresecure.com/pages.php?CDpath=5_8�

mailto:[email protected]�

http://www.cresecure.com/�

http://www.cresecure.com/fss_forms_detail.php?forms_id=4&CDpath=13_27�



CRE SECURE HOSTED CHECKOUT OVERVIEW - 3

Introduction The CRE Secure Hosted Payment Page (HPP) protects your customers credit card information and using Patent Pending HTML Clone™ technology maintains the quality of the customer experience.

CRE Secure is certified as a PCI Compliant Level 1 service provider.

http://usa.visa.com/download/merchants/cisp-list-of-pcidss-compliant-service-providers.pdf

This document outlines the requirements necessary to connect your merchant site to our CRE Secure HPP service.

There are three essential elements to the integration of your merchant site to CRE Secure:

1. A Payment Request Form

2. A Template Payment Page

3. A Transaction Success Response Page

There are three business requirements for the merchant:

1. A CRE Secure account

2. A Merchant Services account for receiving payments via credit card

3. An account with a payment gateway that we support

Note: Merchants can get their CRE Secure account as well as assistance obtaining a merchant services account and a gateway if they do not already have one at www.cresecure.com. For a complete list of supported gateways please go to http://www.cresecure.com/pages.php?CDpath=5_8.

The integration has the following technical prerequisites

1. The merchant site must be accessible via the internet

2. The merchant site must use HTML to generate distinct web pages

3. The merchant site must have an SSL certificate installed (private or shared) in order to post to our service and to have your images and CSS incorporated into our HPP.

http://usa.visa.com/download/merchants/cisp-list-of-pcidss-compliant-service-providers.pdf�


http://www.cresecure.com/pages.php?CDpath=5_8�


CRE SECURE HOSTED CHECKOUT OVERVIEW - 4

How It Works Step-by-step of How CRE Secure HPP works with HTML Clone technology

A. A customer begins to create their order on your site as normal.

B. They proceed to checkout where the CRE Secure HPP is integrated to the Payment Request Form; they select the CRE Secure HPP payment method and choose Checkout.

C. CRE Secure HPP servers receive the order and payment request. In a patent-pending process called HTML Clone technology we retrieve a Template Payment Page from your site in real time, scrub it for any malicious code then combine it with our securely stored credit card collection form.

D. CRE Secure HPP presents to your customer a secure hosted payment page that looks just like your site. With HTML Clone, the customer still has access to all links and live navigation of the merchant’s site because our patent pending technology dynamically matches the merchant’s unique template design from the Template Payment Page on the merchant site.

E. The card holder data and payment transaction is processed in our highly secure PCI Compliant data center and connects directly with the payment gateway and banking payment networks.

F. Once the payment transaction is complete the customer is connected directly back to your shopping cart application to your Transaction Success Response page, where the order status is updated.


IMPLEMENTING CRE SECURE HOSTED PAYMENT PAGE - 5

Payment Request Form: Posting to the Hosted Payment Page To initiate the payment process, use a secure form post to the CRE Secure HPP server production url: https://safe.cresecure.net/securepayments/a1/cc_collection.php

For development and testing use the sandbox url: https://safe.sandbox-cresecure.net/securepayments/a1/cc_collection.php

See Development Sandbox Appendix for test credentials and test credit card numbers.

Example HTML code that posts to the HTML CLONE server is provided in the section Sample HTML Code below.

Important! Your website must be using SSL. Posting to the HTML CLONE from a non SSL URL will result in an 404 error because we only accept secure connections to our HPP servers.

Table 1: Payment Request Form Post Value Descriptions

PAYMENT REQUEST FORM POST VALUE DESCRIPTIONS

Post Value Type Requirements Description

CRESecureID Required Provided by CRE Secure

Unique Account Number for CRE Secure Service

CRESecureAPIToken Required Provided by CRE Secure

API Token as part of the authentication chain

total_amt Required Numeric, Decimal 2 places

The amount to authorize or capture in the transaction

return_url Required https url The url on the merchant site where they can process the payment success action

content_template_url Required https url The url where the merchant template resides, must be https accessible

total_weight Optional If no value sent, default = 0

The total weight of the order - determines if Physical or Digital goods

order_desc Optional Minimum 1 char Text description of the purchase

order_id Optional Minimum 1 char System value of the order or payment

customer_id Optional Minimum 1 char The customer identification number

https://safe.cresecure.net/securepayments/a1/cc_collection.php�

https://safe.sandbox-cresecure.net/securepayments/a1/cc_collection.php�




currency_code Optional Must be valid ISO currency code, default = USD

The 3 letter ISO currency of the transaction

lang Optional Text values that matches known supported languages default = English

The language of the text displayed on the payment page

customer_company Optional Minimum 1 chars Customer’s Company Name

customer_firstname Optional Minimum 1 chars Customer First Name

customer_lastname Optional Minimum 1 chars Customer Last Name

customer_address Optional Minimum 1 chars The street number and name of the billing address (Required for AVS by most gateways)

customer_email Optional Must be valid email format

Customer email for the billing address

customer_phone Optional Numeric minimum 10 chars

Phone number for the billing address

customer_city Optional Minimum 1 chars City of the billing address

customer_state Optional 2 letter abbreviation

State or Province of the billing address

customer_postal_code Optional Minimum 5 chars Zip code or Postal Code of the billing address (Required for AVS by most gateways)

customer_country Optional 3 letter ISO, default = USA

The country of the billing address

delivery_company Optional Minimum 1 chars Ship-To Company Name

delivery_firstname Optional Minimum 1 chars Ship-To First Name

delivery_lastname Optional Minimum 1 chars Ship-To Last Name

delivery_address Optional Minimum 1 chars The street number and name of the delivery address

delivery_email Optional Must be valid email format

Ship-To email for the delivery address

delivery_phone Optional Numeric minimum 10 chars

Phone number for the delivery address

delivery_city Optional Minimum 1 chars City of the delivery address

delivery_state Optional 2 letter abbreviation

State or Province of the delivery address

delivery_postal_code Optional Minimum 5 chars Zip code or Postal Code of the delivery address




delivery_country Optional 3 letter abbr. default = USA

The country of the delivery address

allowed_types Optional Text separated by PIPE delimiter

Default values are: Visa, MasterCard

The card types to display on the payment form. Example: Visa|MasterCard|American Express

Valid values are: Visa, MasterCard, American Express, Discover

sess_id Optional Minimum 8 char The unique session identifier for the customer user on the merchant site

sess_name Optional Optional – if no value sent, default = osCsid

The session name for the customer user on the merchant site.

ip_address Optional Valid IP address format

The IP address of the customer



Merchant Payment Template Page The merchant payment template is a page in the merchant site that has all the template and user session logic that will be used for the presentation of the Hosted Payment Page. The page contains the value [[FORM INSERT]] in the content area. The HTML CLONE technology will read the HTML contents of the page and will search for [[FORM INSERT]] and replace with the Credit Card payment form.

The url for this page on your merchant site is passed to us in the content_template_url post variable

The following rules apply to the payment template page:

1. Create a page in your application, either by creating a new physical page or using your applications built-in page manager.

2. Specify the Page Title and any text you want to appear above and/or below the payment form. 3. Place [[FORM INSERT]] where ever you want the credit card form to appear on the page. 4. The url of the payment template page can be any url in your site. 5. The url for the payment template page must be accessible over HTTPS protocol 6. The url for the payment template page must be directly browseble 7. The payment template page must have the BASE tag with the URL of your HTTPS domain or use

absolute urls for CSS and image SCR values 8. The css and images must be accessible via your HTTPS domain 9. The payment template page must allow for the user session to be set via the URL 10. The payment template page should render using your application template logic and

preferences 11. The HTML Clone will sanitize the HTML output from your payment template page and remove

the following tags: a. <script> and <iframe>

Make sure your payment template page renders correctly without these tags present. b. The CRE Secure payment form utilizes the following classes, id’s and tags to style the

payment form located on the Hosted Payment Page. i. H2 (form title)

ii. table iii. tr iv. td.main v. span.main vi. input

vii. select viii. #submit

c. Refer to the next page for an example of the payment form styled using CSS.



Example CSS <style type="text/css"> U{ text-decoration:none; } TABLE TD{ background-color:#333; padding-left:15px; } .main{ color:#AAA; font-family:Arial, Helvetica, sans-serif; } .main a{ color:#999; text-decoration:none; } .main a:hover{ text-decoration:underline; } .main H2{ color:#999; } .main input, .main select { border:2px solid #CCC; background-color:#777; padding:3px; color:#FFF; font-weight:bold; } .main select{ cursor:pointer; } .main #submit{ border:none; cursor:pointer; } </style>

Figure 1: Unstyled Payment Form

Figure 2: Styled Payment Form Example



Figure 3: Before: Sample merchant payment template page as retrieved by CRE Secure HPP server



Figure 4: After: Sample CRE Secure HPP incorporating the merchant payment template page presented to the customer



Transaction Success Response Page The response is returned as key/value pairs as an HTTP $_GET (postback) to the supplied return URL.

Example of a successful transaction (where return.aspx is the return URL) :

https://mydomain.com/return.aspx?order_id=6&code=000&msg=Success&error=&mPAN=XXXXXXXXXXXX3801&name=Salvatore%20F%20Iozzia&type=Visa&exp=1012&ApprovalCode=012345&TxnGUID=1234567890&ProcTxnID=ABCDEFG&osCsid=ddc2e76644e8dde7308d42606f7f7e74

Data Returned:

DATA TYPE DESCRIPTION

order_id This is the order number or id

code This is the success or failure code. 000 = Success.

error If an error is returned, this value = ‘true’

msg In the event that an error is returned, the error message will be here. Success will have the value “Success”

mPAN This is the masked CC number to be stored in orders table.

name This is the cardholder name to be stored in orders table.

type This is CC type to be stored in orders table.

exp This is CC Expire Date to be stored in order table.

osCsid This is the unique session identifier from the merchant site. This is session_name sent in the Post data

ApprovalCode This is the Approval Code for the transaction.

TxnGUID The transaction ID from the gateway. i.e. TxnGUID for Chase or TransID for Authorize.net.

ProcTxnID Diagnostic ID for transactions on specific gateway integrations, optional.

Table 2: Transaction Response Data

Note: You do not need to worry about failed transactions. The HPP only responds to your merchant system when a payment is successfully made. In the event of a failed payment the customer is shown the payment page again with an error message. The customer retries or leaves the page. The customer either cancels by clicking ‘Cancel’ or by clicking any link in your template HTML.

https://mydomain.com/return.aspx?order_id=6&code=000&msg=Success&error=&mPAN=XXXXXXXXXXXX3801&name=Salvatore%20F%20Iozzia&type=Visa&exp=1012&ApprovalCode=012345&TxnGUID=1234567890&ProcTxnID=ABCDEFG&osCsid=ddc2e76644e8dde7308d42606f7f7e74�




Live Demos of CRE Secure HPP You can view online examples of a full integration and a payment template page at the following links:

EXAMPLE URL

Sample merchant site http://demos.cresecure.com/catalog/

Payment template page prepared to be used by the HTML CLONE

http://demos.cresecure.com/catalog/checkout_payment_template.php

Table 3: Sample payment template pages

Sample of the CRE Secure HPP payment form HTML This is the HTML of the credit card collection form that is presented to the customer on the HPP. It will be incorporated into your template payment page where the [[FORM INSERT]] is on the page.

Note: You do not need to generate this HTML, CRE Secure will generate this as part of our HPP, it is provided here as a reference only.

<table border="0" width="100%" cellspacing="0" cellpadding="2"> <tr> <td> <script type="text/javascript"></script> <form id="form1" name="form1" method="post" action="https://yourdomain.cresecure.net/securepayments/a1/cc_collection.php?sid=XXXXXXXXXXXX&action=process"> <table width="100%" border="0"> <tr> <td height="50" valign="bottom" colspan="2" class="main"> <h2>Pay With Credit Card</h2> </td> </tr> <tr> <td class="main" width="148" height="31">

http://demos.cresecure.com/catalog/�

http://demos.cresecure.com/catalog/checkout_payment_template.php�



<span class="main">Cardholder Name</span> </td> <td class="main" width="200"> <span class="main"> <input type="text" name="name" id="name" autocomplete="off"></span> </td> </tr> <tr> <td class="main" width="148" height="31"> <span class="main">Card Type</span></td> <td class="main" width="200"> <span class="main"> <select name="card_type"> <option value="American Express">American Express</option> <option value="Discover">Discover</option> <option value="MasterCard">MasterCard</option> <option value="Visa">Visa</option> </select> </span> </td> </tr> <tr> <td class="main" height="31"> <span class="main">Credit Card Number</span> </td> <td class="main"><span class="main"> <input type="text" name="PAN" id="PAN" autocomplete="off"></label> </span> </td> </tr> <tr> <td class="main" height="30"> <span class="main">Expiration Date</span> </td> <td class="main"> <span class="main"><select name="cresecure_cc_expires_month"> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> <select name="cresecure_cc_expires_year"> <option value="09">2009</option>



<option value="10">2010</option> <option value="11">2011</option> <option value="12">2012</option> <option value="13">2013</option> <option value="14">2014</option> <option value="15">2015</option> <option value="16">2016</option> <option value="17">2017</option> <option value="18">2018</option> </select> </span> </td> </tr> <tr> <td class="main" height="32"> <nobr> <span class="main">CVC number <a href="javascript:CVVPopUpWindow('https://pay.cresecure.net/securepayments/a1/cvv.php')"><u><i>(What is it?)</i></u></a> </span> </nobr> </td> <td class="main"> <span class="main"> <input name="cv_data" type="text" id="cv_data" size="5" autocomplete="off"> </span> </td> </tr> <tr> <td class="main" height="83"> <span class="main"></span> </td> <td class="main"> <div align="center"><span class="main"> <a href="https://creloaded.cresecure.net/securepayments/a1/cc_collection.php?sid=0cl90urkgn7ts0j3g26dauf410&action=cancel&order_id=92">Cancel</a> <input type="submit" name="submit" id="submit" value="Submit"> </span></div> </td> </tr> </table> </form> </td> </tr> </table>



Sample Merchant HTML Code for Payment Request Form The following code is an example of the form data that must be sent to the CRE Secure HPP server to initiate the payment process.

<form name="form1" method="post" action="https://sandbox-cresecure.net/securepayments/a1/cc_collection.php"> <input type="hidden" name="session" value="e91dd8af53j35k072s0bubjtn7" /> <input type="hidden" name="sess_name" value ="session" /> <input type="hidden" name="allowed_types" value="Visa|MasterCard|American Express" /> <input type="hidden" name="CRESecureID" value="cre78640391SB"/> <input type="hidden" name="CRESecureAPIToken" value="9671b7e350e1effac5ea9195ad4a528d" /> <p> <label>Street Address: <input type="text" name="street" value="1000 1st Av"/> </label> </p> <p> <label>Postal Code: <input type="text" name="postal_code" value="10101"/> </label> </p> <p> <label>Phone Number: <input type="text" name="customer_phone" value="1234567890" /> </label> </p> <p> <label>Email Address: <input type="text" name="customer_email" value="[email protected]" /> </label> </p> <p> <label>Order Amount: <input type="text" name="total_amt" value="123.00" /> </label> </p> <p> <label>Total Weight <input type="text" name="total_weight" value="7" /> </label> </p> <p> <label>Order Number: <input type="text" name="order_num" value="336" />

</label> </p> <p> <label>Order ID: <input type="text" name="order_id" value="336" /> </label> </p>  <input type="hidden" name="currency_code" value="USD" />  <input type="hidden" name="lang" value="english" />  <input type="hidden" name="content_template_url" value="https://mydomain.com/content_template.aspx" />  <input type="hidden" name="return_url" value="https://mydomain.com/return.aspx" /> <p> <label> <input type="submit" name="submit" value="Submit" /> </label> </p> </form>



Sandbox and Testing Environment We have setup a sandbox server environment for developers to test their integrations with. The sandbox connects to all the gateways we support. The connections to the supported gateways are routed to the gateway’s sandbox.

Note: We limit transactions to known test card numbers. Any transaction that is using a real card will be ignored by our system and treated an error at the payment page.

Sandbox Account Credentials

Post the form data to the sandbox server at the following url:

https://sandbox-cresecure.net/securepayments/a1/cc_collection.php

Credentials are provided that are connected to each gateway. Different gateways provide different response that are passed back to your merchant system. Also different gateways respond differently to specific conditions such as AVS data and Ip address requirement. So pick the gateway credentials that match to the gateway you will be using when you go live.

SANDBOX CREDENTIALS AUTHORIZE.NET GATEWAY

CRESecureID cre78640391SB

CRESecureAPIToken 9671b7e350e1effac5ea9195ad4a528d

SANDBOX CREDENTIALS CHASE ORBITAL TAMPA


CRESecureAPIToken d9703b3578b7d1dbab5b0dbe61aac106

SANDBOX CREDENTIALS CHASE ORBITAL SALEM


CRESecureAPIToken 2439e7307b40ccc4212ddb3abc3d1a0a

Table 4: Testing Sandbox Credentials

https://sandbox-cresecure.net/securepayments/a1/cc_collection.php�



Test Credit Card Numbers When using the sandbox for test we only accept transactions with valid test credit card numbers. Any card numbers that do not match those listed below will dropped from server memory and the process will respond with an error.

TEST CARD NUMBERS CHASE SALEM AND TAMPA

CREDIT CARD TEST DATA

Visa 4111111111111111

MasterCard 5454545454545454

Amex 371449635398456

Discover 6011000995504101

TEST CARD NUMBERS AUTHORIZE.NET

CREDIT CARD TEST DATA

Visa 4111111111111111, 4007000000027, 4012888818888

MasterCard 5424000000000015

Amex 370000000000002

Discover 6011000000000012

JCB 3088000000000017

Diners Club 38000000000006 , 4007000000027

Table 5: Test Credit Card Numbers

Note: Transactions with amounts that do not end with .00 will be declined on the development HTML CLONE. This is the expected behavior to allow for negative-path testing.

cresecure hpp integration guide

Documents

sample cre secure hpp

hosted payment services

cre secure hpp works

cre secure hpp server

payment request form

unstyled payment form

sample payment template

live demos of cre secure