Create a new transaction

Hosted Payment Pages (HPP) (1)

Our low-code integration to take payments securely.

Authentication Header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to your by your Implementation Manager.

You must use the Authorization header for any request you send to our Hosted Payment Pages API, unless you are using client certificate authenticating with SSL/TLS.

Accept Header

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

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our Hosted Payment Pages API.

DNS Whitelisting
Whitelist the following URLs:

https://try.access.worldpay.com/
https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License Worldpay

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

The three character currency code. See list of supported currencies.

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",
  "x-parsed-md-description": {
    "result": {
      "$$mdtype": "Node",
      "errors": [],
      "lines": [],
      "inline": false,
      "attributes": {},
      "children": [
        {
          "$$mdtype": "Node",
          "errors": [],
          "lines": [ … ],
          "inline": false,
          "attributes": {},
          "children": [ … ],
          "type": "paragraph",
          "annotations": [],
          "slots": {},
          "location": { … }
        }
      ],
      "type": "document",
      "annotations": [],
      "slots": {}
    },
    "raw": "Mind Palace Ltd"
  }
}

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

Hosted Payment Pages (HPP) (1)

Create a new transaction

RequestExpand all

Responses

Do you like our page?

Request