Passed
Hosted Payment Pages (HPP) API

Hosted Payment Pages (HPP) API (1)

An API to use the Worldpay Hosted Payment Pages (HPP) product.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License Worldpay
Languages
Servers
Try
https://try.access.worldpay.com/
Live
https://access.worldpay.com/

Create a new transaction

Request

Headers
WP-CorrelationIdstring^[0-9a-zA-Z_-]{1,64}$required

Used to identify individual requests made to our API.

User-Agentstring

The name of the client calling the API.

Bodyapplication/vnd.worldpay.payment_pages-v1.hal+json

The Transaction to create

transactionReferencestring[ 1 .. 64 ] characters^[a-zA-Z0-9\-\_\/\!\@\#\$\%\(\)\*\=\.\:\;\?\[...required

A unique reference generated by you that is used to identify a payment throughout its lifecycle.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$required

Used to route the request in Access Worldpay, created as part of on-boarding.

descriptionstring[ 0 .. 128 ] characters

An optional text, when supplied is displayed to your customer on payment pages.

narrativeobjectrequired

The text that appears on your customer's statement. Used to identify the merchant.

line1string^[a-zA-Z0-9\-\.\,\ ]*$required

line1 is used to provide basic details about the merchant.

billingAddressobject

An object containing the billing address information.

firstNamestring[ 1 .. 22 ] characters

The customer's first name

lastNamestring[ 1 .. 22 ] characters

The customer's last name

address1string[ 0 .. 85 ] characters

Address line 1

address2string[ 0 .. 85 ] characters

Address line 2

address3string[ 0 .. 85 ] characters

Address line 3

postalCodestring[ 0 .. 15 ] characters

Required for all countries except the following: * IE

citystring[ 0 .. 50 ] characters

Address city

statestring[ 0 .. 50 ] characters

Address state or region

countryCodestring

The supported ISO 3166-1 alpha-2 country code

valueobjectrequired

The payment amount.

currencystring
amountinteger(int64)>= 1required

The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.

resultURLsobject

An object containing the different URLs we redirect your customers to when we receive the payment result. We recommend that you provide us with your custom result URLs.

successURLstring

When we receive the payment result for a successful payment, we redirect your customer to the success URL.

pendingURLstring

When we receive the payment result for a pending payment transaction, we redirect your customer to the pending URL.

failureURLstring

When a payment fails, we redirect your customer to the failure URL.

errorURLstring

When we receive the payment result for an erroneous payment, we redirect your customer to the error URL.

cancelURLstring

When your customer cancels a transaction, we redirect that customer to the cancel URL.

expiryURLstring

When a customer leaves the payment transaction uncompleted within the maximum allowed time frame, we redirect your customer to the expiry URL.

riskDataobject

Data used for fraud and risk protection.

accountobject

Object containing all customer account related risk data.

transactionobject

Object containing all customer transaction related risk data.

shippingobject

Object containing all data related to how the order will be shipped.

customobject

An object containing all data that can be used to configure manual fraud rules.

expiryinteger(int64)[ 300 .. 2592000 ]

Allows you to configure the duration, in seconds, your customer can access the payment link.

Default 3600
createTokenobject

An object that instructs us to create a token for the payment details supplied.

typestringrequired

The type of token to be created.

Value"worldpay"
namespacestring[ 1 .. 64 ] characters

A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.

descriptionstring[ 1 .. 255 ] characters^([^&<]*)$

A description of your token. If not supplied, a default description is created for you.

optInstringrequired

Used to choose how the customer could opt into their payment details being tokenized.

SILENT - (default value) The card details are always saved (you must already have their consent to do this)

NOTIFY - The card details are always saved (you must already have their consent to do this) and your customer will see this within our hosted payment pages

ASK - The card details are saved if your customer provides their consent. This adds a "Save payment details" tickbox to the page, which they tick to opt-in, or ignore to opt-out.

Enum"SILENT""NOTIFY""ASK"
customerAgreementobject

Contains specific customer agreements for the transaction. If this is present, then the creationToken must also be present

typestringrequired

The processing arrangement agreed with your customer. Supported value:

cardOnFile

Value"cardOnFile"
storedCardUsagestringrequired

How the card is being used.

first - to store a card, this is applicable when the type is "subscription" or "cardOnFile"

subsequent - using a previously stored card, this is applicable when the type is "cardOnFile"

Enum"first""subsequent"
paymentInstrumentTokenPaymentInstrument (object)
One of:

An object that contains the payment type and details.

typestringrequired

The type of instrument.

hrefstringrequired

The URL to an Access Token, we return this after token creation via the API or webhook callback.

hostedCustomizationobject

Add CSS options for each payment to customise the look and feel of the payment page.

backgroundColorstring^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

Background color for the payment page in hex format. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

colorstring^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

Text color for the payment page in hex format. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

pageobject

Represents styling and customizations applied to the entire payment page, including colors, fonts, and borders.

buttonsobject

Defines hover and focus styling for buttons on the HPP page

inputsobject

Defines custom styling for input fields when hovered over or focused

fontsobject

Defines font styling options for text displayed on the payment pages, including the list of preferred font families

threeDSobject

An object containing 3DS authentication preferences, which can be used to turn 3DS off.

typestring

The 3DS type should only accept 'disabled'

fraudobject
typestring

The Fraud type should only accept 'disabled'

customisation_idstring= 21 characters^[A-Za-z0-9\_\-]*$

A unique value that identifies which customization should be use for this transaction. Set it to null to use the default customization.

application/vnd.worldpay.payment_pages-v1.hal+json

Create transaction request, all key:values

{
  "transactionReference": "MyTransaction123",
  "merchant": {
    "entity": "POxxxxxxxxx"
  },
  "narrative": {
    "line1": "Mind Palace Ltd"
  },
  "value": {
    "currency": "GBP",
    "amount": 123
  }
}

Responses

Transaction creation was successful

Bodyapplication/vnd.worldpay.payment_pages-v1.hal+json
urlstring

The URL of HPP, where the customer can be redirected to complete their payment.

Response
application/vnd.worldpay.payment_pages-v1.hal+json

Successful response

{
  "url": "https://payments.worldpay.com/app/hpp/integration/transaction/xxxxxxxxxxxxxxxxxxxx&cs=yyyyyy"
}