Hosted Payment Pages (HPP) API (1)

Our low-code integration to take payments securely.

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

address1string[ 0 .. 85 ] charactersrequired

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

Address city

statestring[ 0 .. 50 ] characters

Address state or region

countryCodestringrequired

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

An object that contains the payment type and details.

typestringrequired

The type of instrument.

Discriminator
hrefstringrequired

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

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

Create transaction request, required key:values

{
  "transactionReference": "MyTransaction123",
  "merchant": {
    "entity": "POxxxxxxxxx"
  },
  "narrative": {
    "line1": ""
  },
  "value": {
    "currency": "GBP",
    "amount": 123
  },
  "description": "Mind Palace Ltd",
  "billingAddressName": "Sherlock Holmes",
  "billingAddress": {
    "address1": "221B Baker Street",
    "address2": "Marylebone",
    "address3": "Westminster",
    "postalCode": "NW1 6XE",
    "city": "London",
    "state": "Greater London",
    "countryCode": "GB"
  },
  "resultURLs": {
    "successURL": "https://mindpalace-website/result/success",
    "pendingURL": "https://mindpalace-website/result/pending",
    "failureURL": "https://mindpalace-website/result/failure",
    "errorURL": "https://mindpalace-website/result/error",
    "cancelURL": "https://mindpalace-website/result/cancel",
    "expiryURL": "https://mindpalace-website/result/expiry"
  },
  "riskData": {
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "city": "Durham",
        "address1": "The Palatine Centre",
        "address2": "Durham University",
        "address3": "Stockton Road",
        "state": "County Durham",
        "countryCode": "GB",
        "postalCode": "DH1 3LE",
        "phoneNumber": "01189998819999197253"
      },
      "method": "verifiedAddress",
      "nameMatchesAccountName": false,
      "email": "james.moriarty@example.com",
      "timeFrame": "nextDay"
    },
    "custom": {
      "string1": "foo",
      "number1": "1",
      "string2": "foo",
      "number2": "1",
      "string3": "foo",
      "number3": "1",
      "string4": "foo",
      "number4": "1",
      "string5": "foo",
      "number5": "1",
      "string6": "foo",
      "number6": "1",
      "string7": "foo",
      "number7": "1",
      "string8": "foo",
      "number8": "1",
      "string9": "foo",
      "number9": "1"
    },
    "account": {
      "dateOfBirth": "1835-04-01",
      "history": {
        "createdAt": "1876-06-01",
        "modifiedAt": "1876-08-13",
        "paymentAccountEnrolledAt": "1876-06-01",
        "passwordModifiedAt": "1876-06-01"
      },
      "type": "fidoAuthenticator",
      "previousSuspiciousActivity": false,
      "email": "sherlock.holmes@example.com"
    },
    "transaction": {
      "firstName": "James",
      "lastName": "Moriarty",
      "phoneNumber": "01189998819999197253",
      "preOrderDate": "1876-08-13",
      "reorder": false,
      "history": {
        "attemptsLastYear": 3,
        "completedLastSixMonths": 4,
        "attemptsLastDay": 2,
        "shippingAddressFirstUsedAt": "1876-06-01",
        "addCardsLastDay": 1
      },
      "giftCardsPurchase": {
        "totalValue": {
          "amount": 10000,
          "currency": "GBP"
        },
        "quantity": 1
      }
    }
  },
  "expiry": "600"
}

Responses

Transaction creation was successful

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

The URL of HPP, where your 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"
}