Hosted Payments Overview

Introduction to Hosted Payment Pages

This document details how to process payments via the Hosted Payments solution on the Worldpay Express payment platform. The use of Cascading Style Sheets (CSS) with Hosted Payments is now available with details regarding this type of implementation. Also covered are Hosted Payments Sample Flows for a single sale transaction through Express. Plus, Store Card Data in PASS to manage tokenization and single sale transactions using embedded browser control are also covered.

There is considerable payments developer documentation on hosted payments using CSS (Cascading Style Sheets) to customize presentation fields as well as managing other parameters. Also download our External Hosted Payments CSS Whitelist for further information on managing payment methods.

Hosted Payment Page Highlights

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.

Through the use of the Boolean AddressEditAllowed input parameter within the TransactionSetup method Address node (XML interface only), both the standard Hosted Payments page (Non-Embedded only) and the mobile Hosted Payments page (Non-Embedded only) can allow the individual entering the card information to edit the Billing Address details prior to submission to Express. This is supported for card-present and card-not-present transactions, regardless of whether or not the Billing Address information is initially submitted in TransactionSetup. Set AddressEditAllowed to “1” to allow users to edit the Billing Address details directly on the Hosted Payments page, and set AddressEditAllowed to “0” (or leave out entirely) if no Billing Address edits are allowed.

Helpful Links

Hosted Payments Sample Flows

Single Sale Transaction

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

Express responds with a TransactionSetupID (a GUID) if the request was successful.

The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.

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

Your application receives the URL and parses out the response details, which you can then display on your own page/application.

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

Express responds with a TransactionSetupID (a GUID) if the request was successful.

The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.

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

Your application receives the URL and parses out the response details, and you can store the PaymentAccountID in your own application.

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.

Express responds with the appropriate response details, which you can then display on your own page/application.

Single Sale Transaction using Embedded Browser Control

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

Express responds with a TransactionSetupID (a GUID) if the request was successful.

The end user swipes or keys the card into the Hosted Payments page/popup and clicks Submit.

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.

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)

CSS Use

Using CSS allows integrators to:

Customize and change the presentation of the fields to collect the CC data.

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.

When you are ready to charge the card, you simply submit the PaymentAccountID (instead of the card number) using the ExtendedParametersobject/class of the CreditCardSale method, for example, and the transaction is processed like any normal sale.