Hosted Payments Overview

Document created by Chris Jennings on Aug 8, 2016Last modified by jeff.gross@vantiv.com on Jan 9, 2017
Version 2Show Document
  • View in full screen mode

Introduction

This document contains information on processing via the Hosted Payments solution on the Express payment platform.  The use of Cascading Style Sheets with Hosted Payments is now available, and details regarding this type of implementation are discussed later in this document.

 

Notes

    • Hosted Payments does not support unlinked refund transactions (i.e. CreditCardCredit) due to security risks involved with that transaction type.
    • Hosted Payments does not support Check/ACH processing because Check/ACH data does not fall under PCI scope.
    • The Hosted Payments page can be displayed in a number of different ways, including a full-page redirect, an iFrame, a popup, etc.
    • The Hosted Payments page can be displayed in an embedded or non-embedded format.  Refer to the TransactionSetup method in the interface specification for additional details.
    • If TransactionQuery (using the TransactionSetupID) is utilized to obtain additional transaction details immediately following a Hosted Payments transaction, please note that there may be more than one transaction associated with a single TransactionSetupID (such as both a Decline and Approval received during the single Hosted Payments session). Because of this, during the TransactionQuery, integrators should review the appropriate TransactionType and approval response to obtain transaction details regarding the successful Hosted Payments transaction.
    • Hosted Payments Youtube Video: https://www.youtube.com/watch?v=LZQxn8y3-4w

Helpful Links

 

 

Hosted Payments Sample Flows

 

Single Sale Transaction

  1. Your application collects the non-sensitive transaction details such as amount, transaction type, and address information where necessary, and submits a programmatic request using the TransactionSetup method in the interface specification (e.g. TransactionSetupMethod of 1/CreditCardSale for a single sale transaction).
  2. Express responds with a TransactionSetupID (a GUID) if the request was successful.
  3. Your application performs a redirect (full, popup, or iFrame, etc.) to our Hosted Payments URL and appends the TransactionSetupID to the end of that URL.  For example, it might be: https://certtransaction.hostedpayments.com/?TransactionSetupID=INSERTHERE
  4. The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.
  5. Express redirects the response details to the ReturnURL you originally provided in your initial TransactionSetup request from the first step (we append the response details in name/value pairs to the end of your ReturnURL).
  6. Your application receives the URL and parses out the response details, which you can then display on your own page/application.

 

 

Store Card Data in PASS to Tokenize (and subsequently submit Sale using Token)

  1. Your application collects the non-sensitive transaction details such as the address information, etc., and submits a programmatic request using the TransactionSetup method in the interface specification (e.g. TransactionSetupMethod of 7/PaymentAccountCreate to store card data).
  2. Express responds with a TransactionSetupID (a GUID) if the request was successful.
  3. Your application performs a redirect (full, popup, or iFrame, etc.) to our Hosted Payments URL and appends the TransactionSetupID to the end of that URL.  For example, it might be: https://certtransaction.hostedpayments.com/?TransactionSetupID=INSERTHERE
  4. The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.
  5. Express redirects the response details to the ReturnURL you originally provided in your initial TransactionSetup request from the first step (we append the response details, such as the PaymentAccountID reference pointer, in name/value pairs to the end of your ReturnURL).
  6. Your application receives the URL and parses out the response details, and you can store the PaymentAccountID in your own application.
  7. When you are ready to charge the card, you simply submit the PaymentAccountID (instead of the card number) using the ExtendedParameters object/class of the CreditCardSale method, for example, and the transaction is processed like any normal sale.
  8. Express responds with the appropriate response details, which you can then display on your own page/application.

 

Single Sale Transaction using Embedded Browser Control

  1. Your application collects the non-sensitive transaction details such as amount, transaction type, and address information where necessary, and submits a programmatic request using the TransactionSetup method in the interface specification (e.g. TransactionSetupMethod of 1/CreditCardSale for a single sale transaction).
  2. Express responds with a TransactionSetupID (a GUID) if the request was successful.
  3. Your application performs a redirect (embedded browser control, full, popup, or iFrame, etc.) to our Hosted Payments URL and appends the TransactionSetupID to the end of that URL.  For example, it might be: https://certtransaction.hostedpayments.com/?TransactionSetupID=INSERTHERE
  4. The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.
  5. Express redirects the response details to the ReturnURL you originally provided in your initial TransactionSetup request from the first step (we append the response details in name/value pairs to the end of your ReturnURL).  If using the embedded browser control, the Navigation URL in the object contains the response values that can be parsed.
  6. Your application receives the URL and parses out the response details, which you can then display on your own page/application.

 

Cascading Style Sheets (CSS)

 

Implementation

Using CSS requires no changes to the Hosted Payments flow. A new input field called CustomCss, containing the custom CSS, can simply be submitted in the programmatic TransactionSetup method request in the interface specification.

  • The CustomCss input field has a max length of 10,000 characters.
  • The CustomCss input field can only be utilized with the XML interface option on the Express platform. It is not supported with the SOAP interface option.

 

Example CSS

The following is a very basic example of CSS to pass into the CustomCss input field. This example modifies the body tag to use the Comic Sans MS font and sets background-color to aqua. It also sets the font for the Card Number input textbox and Expiration Date dropdown list to use Comic Sans MS.

 

body {

font-family: Comic Sans MS;

font-size: 12px;

margin: 0px;

background-color: aqua;

}

.selectOption {

font-family:Comic Sans MS

}

.inputText {

font-family:Comic Sans MS

}

 

CSS Whitelist Appendix

The valid/allowed CSS selectors and attributes are defined in the associated CSS Whitelist Appendix. This can be provided as an XML file so that it will be properly formatted when viewed in a browser. Additional details regarding this file are included below:

  • There is a <selector-list> that defines the CSS selectors allowed by an ID, css class name, and element name. Three examples are below:
    • <selector name="body" /> (select by html elment)
    • <selector name=".divMainForm" /> (select by css class name)
    • <selector name="#cardNumber" /> (select by ID)
    • etc., etc.
  • There is a <property-list> that defines what css attributes (aka properties) and associated values are allowed. In this example, the property allowed is background-color, and its allowed values are defined by either a literal or by a regular expression.
    • body {background-color: transparent} is valid css.
    • body {background-color: aqua} is valid css because aqua is in the regular expression "colorName".
    • body {background-color: #ffffff} is valid css because #ffffff is allowed by the regular expression "colorCode".
    • body {background-color: whatIsThis} is "not" valid css because it will not pass the regular expression checks.

<property name="background-color">

<literal-list>

<literal value="transparent" />

<literal value="inherit" />

</literal-list>

<regexp-list>

<regexp name="colorName" />

<regexp name="colorCode" />

<regexp name="rgbCode" />

<regexp name="rgbaCode" />

<regexp name="systemColor" />

</regexp-list>

</property>

  • The regular expressions used to validate the values of a property are listed in the <common-regexps> section.

 

Additional Notes

  • Any invalid CSS submitted will be removed and the remaining CSS will apply and the web page will display using the updated CSS. The only time the TransactionSetup method may be rejected is if the CustomCss field is improperly formatted to the point where it cannot be properly parsed. Once the web page is displayed, the page markup may be inspected using the developer tools in the browser (F12) to see what CSS was applied.

Outcomes