Last Updated: 09 June 2025 | Change Log

Setup a Payment

SMB (Worldpay eCommerce)

Our Hosted Payment Pages API generates a URL in the response. Redirect your customer to this URL to take a payment.

Integration overview

Get-your-credentials
Set-your-headers
Post-your-request
Redirect-your-customer
Payment-is-autosettled

Prerequisites

Pull your credentials from your dashboard.

Set your headers

Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.

Authorization: {your_credentials}
Content-Type: application/vnd.worldpay.payment_pages-v1.hal+json
Accept: application/vnd.worldpay.payment_pages-v1.hal+json
HeaderDescription
AuthorizationThe mandatory Authorization header is used for authentication and identification of our merchants within Access Worldpay. Replace {your_credentials} with your base64-encoded Basic Auth username and password you have received from us.
Content-TypeThe Content-Type header is required if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT.
AcceptUse the mandatory Accept header to identify which version of our Hosted Payment Pages API you are using.
Info

If you're using both the Content-Type and Accept headers, they must match.

Send your request

POST your request to the payment_pages:setup action link to setup a payment.

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

Example request with minimum required fields:

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

Mandatory parameters

ParameterDescriptionData typeField Length
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format.StringMust be between 1 to 64 characters.
merchantAn object that contains information about the merchant.ObjectN/A
merchant.entityYou can find your entity in your Dashboard under "Developer Tools". Using your own entity reference causes the transaction to fail.StringMust be between 1 and 32 characters.
narrativeAn object that helps your customers better identify you on their statement.ObjectN/A
narrative.line1An object that helps your customers better identify you on their statement.StringMust be between 1 and 24 characters
valueAn object that contains information about the payment transaction.ObjectN/A
value.currencyThe 3 character ISO currency code.String3 character ISO currency code
value.amountThe payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.IntegerN/A

Store a card

You can save your customer's card as part of a payment request by creating a token. You can use this card for any subsequent payments using this token. This is known as a Customer Initiated Transaction (CIT) or card on file transaction.

Code examples with minimum and all fields:

{
  "transactionReference": "MyTransaction123",
  "merchant": {
    "entity": "POxxxxxxxxx"
  },
  "narrative": {
    "line1": "Mind Palace Ltd"
  },
  "value": {
    "currency": "GBP",
    "amount": 123
  },
  "createToken": {
    "type": "worldpay",
    "namespace": "SHOPPER_ID_1234567890",
    "description": "Test Token Description",
    "optIn": "ASK"
  }
}
ValueRequired?Description
createTokenAn object that instructs us to create a token for the payment details supplied.
typeThe type of token. The value is "worldpay".
namespaceA namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.
descriptionA description of your token. If not supplied, a default description is created for you.
optIn
  • "Silent" - (default value) The card details will always be saved (you must already have their consent to do this)
  • "Notify" - The card details will always be 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 will be 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.
Note
If your customer does not consent, then no card details are saved.

The below table contains fields required for the first transaction in the series of Merchant Initiated Transactions.

ValueRequired?Description
customerAgreementAn object that contains specific customer agreements for the transaction.
typeThe processing arrangement agreed with your customer. The value is "cardOnFile".
storedCardUsageSet to "first" to store a card or "subsequent" to use a previously stored card.
Note

We return the token via a webhook.

Take a payment from a stored card (card on file)

Use a previously stored card (Customer Initiated Transaction (CIT)) to take a payment. We capture the CVC as part of this flow.

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

Successful response

{ "url": "https://payments.worldpay.com/app/hpp/integration/transaction/xxxxxxxxxxxxxxxxxxxx&cs=yyyyyy", "_links": { "self": { "href": "https://access.worldpay.com/paymentQueries/payments?transactionReference=174420000000000" } } }
ValueRequiredDescription
paymentInstrumentAn object that contains the payment type and details.
typeThe payment type details. Value is "card/tokenized".
hrefWe return this after token creation via the webhook.

Optional parameters

We handle 3DS authentication and fraud assessments on your behalf. However, supplying the additional optional fields below, increases the chance of a frictionless flow for your customer.

Info

The result URLs are required to redirect your customer to your defined URL at the end of their payment journey.

ParameterRequired?DescriptionData typeField Length
descriptionAn optional text, when supplied is displayed to your customer on payment pages.StringMaximum of 128 characters.
billingAddressAn object containing the billingAddress information.ObjectN/A
billingAddress.firstNameCustomer's first name.StringMaximum of 22 characters
billingAddress.lastNameCustomer's last name.StringMaximum of 22 characters
billingAddress.address1Only required when billing address is provided.StringMaximum of 85 characters.
billingAddress.address2Only required when billing address is provided.StringMaximum of 85 characters.
billingAddress.address3Only required when billing address is provided.StringMaximum of 85 characters.
billingAddress.postalCodeOnly required when billing address is provided.StringMaximum of 15 characters.
billingAddress.cityOnly required when billing address is provided.StringMaximum of 50 characters.
billingAddress.stateOnly required when billing address is provided.
For the United States or China (must be ISO-3611-2, only provide two characters after "US-" or "CN-", e.g. FL for Florida or BJ for Beijing).
StringMaximum of 50 characters.
billingAddress.countryCodeOnly required when billing address is provided.StringMust be a valid ISO3166-1 alpha-2 country code.
resultURLsAn 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.ObjectN/A
resultURLs.successURLWhen we receive the payment result for a successful payment, we redirect your customer to the success URL.StringN/A
resultURLs.pendingURLWhen we receive the payment result for a pending payment transaction, we redirect your customer to the pending URL.StringN/A
resultURLs.failureURLWhen a payment fails, we redirect your customer to the failure URL.StringN/A
resultURLs.errorURLWhen we receive the payment result for an erroneous payment, we redirect your customer to the error URL.StringN/A
resultURLs.cancelURLWhen your customer cancels a transaction, we redirect that customer to the cancel URL.StringN/A
resultURLs.expiryURLWhen a customer leaves the payment transaction uncompleted within the maximum allowed time frame, we redirect your customer to the expiry URL.StringN/A
customAn object containing all data that can be used to configure manual fraud rules.ObjectN/A
custom.string1-99 available slots for custom string values you can use to configure manual fraud rules.StringN/A
riskDataTo increase the chances of a frictionless flow, we recommend sending additional data in the riskData object.ObjectN/A
settlementAn object containing information relating to whether auto settlement is turned on or off.ObjectN/A
settlement.autoA value when specified allows you to turn auto settlement off. The default behaviour is always on and there is nothing to specify.BooleanN/A
cancelOnAn object containing configuration for when a payment is sent for cancellation automatically.ObjectN/A
cancelOn.cvcNotMatchedA value when specified allows you to continue to sent for settlement. By default a payment will be sent for cancellation if the CVC is not matched and there is nothing to specify for the default behaviour.StringN/A
expiryAllows you to configure the duration your customer can access the payment link. If not provided, defaults to 3600 seconds.Objectmin 300 seconds - max 2,592,000 seconds
customisation_idA unique value that identifies which customization should be used for this transaction. Set it to null to use the default customization.String21 characters
localeWhen we receive one of the supported locale values, the payment pages are loaded in the language of the locale. If locale is not specified, the payment pages load in English.StringMaximum of 5 characters
hostedCustomizationAn object containing CSS customization.StringN/A
hostedPropertiesAn object containing functional properties customization.StringN/A

Risk data

There are three riskData objects you can include in your request:

Account

ParameterDescription
accountObject containing all customer account related risk data.
account.previousSuspiciousActivity
  • true
  • false
account.type
  • guestUser - Order placed without full merchant account registration (no password)
  • registeredUser- Order placed with full merchant account registration (password entered)
  • federatedAccount - Using a Federated ID
  • issuerCredentials- Using issuer credentials
  • thirdPartyAuthentication - Using third party authentication
  • fidoAuthenticator - FIDO authentication standard
account.emailThe customer's email address.
account.history.createdAtWhen the account was created.
account.history.modifiedAtWhen the account was last modified.
account.history.passwordModifiedAtWhen the account password was last changed.
account.history.paymentAccountEnrolledAtDate the payment account was added to the cardholder account.

Transaction

ParameterDescription
transactionObject containing all customer transaction related risk data.
transaction.reorderRepeat of a previous order :
  • true
  • false
transaction.preOrderDateExpected date that a pre-ordered purchase will be available.
transaction.firstNameCustomer's first name.
transaction.lastNameCustomer's last name.
transaction.phoneNumberCustomer's phone number.
transaction.historyObject containing details of the last transaction.
history.attemptsLastDayNumber of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
history.attemptsLastYearNumber of transactions (successful or abandoned) for this cardholder account within the last year.
history.completedLastSixMonthsNumber of purchases with this customer account during the previous six months.
history.addCardsLastDayNumber of attempts to add a card in the last 24hrs.
history.shippingAddressFirstUsedAtWhen the shipping address used for the transaction was first used.
transaction.giftCardsPurchaseIf the order is being used to purchase a gift card.
giftCardsPurchase.totalValue.currencyThe three digit currency code. See list of [supported currencies. If provided must include totalValue.amount.
giftCardsPurchase.totalValue.amountThe amount being placed on the gift card. If provided, must include totalValue.currency.
giftCardsPurchase.quantityThe number of gift cards being purchased.
transaction.threeDSObject containing information relating to whether 3DS is turned off.
threeDS.typeA value allowing you to turn off 3DS. The default is "on".
transaction.fraudObject containing information relating to whether FraudSight is turned off.
fraud.typeA value allowing you to turn off FraudSight. The default is "on".

Shipping

ParameterDescription
shippingObject containing all data related to how the order will be shipped.
shipping.nameMatchesAccountNameCustomer name on account is identical to the shipping name:
  • true
  • false
shipping.method
  • billingAddress - Ship to customers billing address
  • verifiedAddress- Ship to another verified address on file with merchant
  • otherAddress- Ship to address that is different than billing address
  • store - Ship to store (store address should be populated on request)
  • digital - Digital goods
  • unshippedTickets - Travel and event tickets, not shipped
  • other - Other
shipping.timeFrame
  • electronic
  • sameDay
  • nextDay
  • twoDaysPlus
shipping.emailThe email address used for an electronic delivery.
shipping.addressAn object containing the shipping address information. If included, you must send at least:

Full example request

{
  "transactionReference": "MyTransaction123",
  "merchant": {
    "entity": "POxxxxxxxxx"
  },
  "narrative": {
    "line1": "line1"
  },
  "value": {
    "currency": "GBP",
    "amount": 123
  },
  "description": "Mind Palace Ltd",
  "billingAddressName": "Sherlock Holmes",
  "billingAddress": {
    "firstName": "John",
    "lastName": "Watson",
    "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": {
      "shopperId": "1234",
      "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
      }
    }
  },
  "hostedCustomization": {
    "fonts": {
      "family": [
        "Comic Sans MS"
      ]
    },
    "buttons": {
      "backgroundColor": "#ff0",
      "border": {
        "style": "solid",
        "color": "#0ff",
        "width": "3px",
        "radius": "0px"
      },
      "hover": {
        "backgroundColor": "#ddf"
      },
      "focus": {
        "backgroundColor": "#dfd"
      }
    },
    "inputs": {
      "backgroundColor": "#ffffff",
      "border": {
        "style": "solid",
        "width": "2px",
        "radius": "2px",
        "color": "#fff"
      },
      "placeholder": {
        "color": "#001"
      },
      "hover": {
        "backgroundColor": "#ff0000",
        "color": "#7f0000",
        "border": {
          "color": "#0ff"
        }
      },
      "focus": {
        "backgroundColor": "#0240ff",
        "color": "#001f7f",
        "border": {
          "color": "#0ff"
        }
      },
      "validation": {
        "ok": {
          "color": "#00f"
        },
        "error": {
          "color": "#f00"
        }
      }
    },
    "page": {
      "backgroundColor": "#333",
      "color": "#fff"
    }
  },
  "hostedProperties": {
    "showBillingAddress": "EDIT",
    "showShippingAddress": "HIDE",
    "showCountryList": "false",
    "showLanguageList": "false",
    "showContactDetails": "HIDE",
    "sendURLParameters": "true",
    "showPoweredByWorldPay": "true",
    "showCancelButton": "true",
    "showChangePaymentMethodButton": "false",
    "disableStrictUrls": "true",
    "showHeader": "true",
    "showFooter": "true",
    "showCardIcons": "false",
    "paymentButtonLabel": "makePayment",
    "showCardholderName": "true",
    "showPaymentDetailsHeader": "true",
    "passBackErrorReasons": "true",
    "maskCardDetails": "false",
    "googlePayButtonColour": "black",
    "googlePayButtonLabel": "long",
    "applePayButtonType": "plain",
    "applePayButtonStyle": "black"
  },
  "settlement": {
    "auto": true,
    "cancelOn": {
      "cvcNotMatched": "disabled"
    }
  },
  "expiry": "600"
}

Response

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

Successful response

{ "url": "https://payments.worldpay.com/app/hpp/integration/transaction/xxxxxxxxxxxxxxxxxxxx&cs=yyyyyy", "_links": { "self": { "href": "https://access.worldpay.com/paymentQueries/payments?transactionReference=174420000000000" } } }

You receive:

  • a url element to redirect your customer to the payment pages and complete the payment
  • a href element to query for next action links once a payment has been made
Important

Worldpay's Hosted Payment Pages use and switch traffic between multiple domains. To prevent disruptions in service, do not whitelist domains.

Info

In case of an error, you can get further information in our error reference.

Next steps


Redirect your customer