Menu

Setup a Payment

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 from yourdashboard.
Set your request headers, so we can identify and authenticate you.
POST your sale request to https://try.access.worldpay.com/payment_pages.
Use the URL received in the response to redirect your customer to complete their payment.
Once completed, we will auto-settle the payment.

Prerequisites

Pull your credentials from yourdashboard.

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.

Copied!
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 manadatory Accept header to identify which version of our Hosted Payment Pages API you are using.

Note: 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:

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant":
    {
        "entity": "POxxxxxxxxx"
    },
    "narrative":
    {
        "line1": "Mind Palace Ltd"
    },
    "value":
    {
        "currency": "GBP",
        "amount": 42
    }
}

Mandatory parameters

ParameterDescriptionData typeField Length
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. Seetransaction 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 yourDashboardunder the currency tab in settings. 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 characterISO 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 ourcurrency table.IntegerN/A

Optional parameters

Hosted Payment Pages handles 3DS authentication and fraud assessments on your behalf. However, supplying the additional optional fields below, increases the chances of a frictionless flow for your customer.

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

ParameterRequiredDescriptionData 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.address1Only mandatory 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 mandatory when billing address is provided.StringMaximum of 15 characters.
billingAddress.cityOnly mandatory when billing address is provided.StringMaximum of 50 characters.
billingAddress.stateOnly mandatory 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 mandatory when billing address is provided.StringMust be a validISO3166-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

Risk data

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

Full example request

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant":
    {
        "entity": "POxxxxxxxxx"
    },
    "narrative":
    {
        "line1": ""
    },
    "value":
    {
        "currency": "GBP",
        "amount": 42
    },
    "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
            }
        }
    }
}

Response

Copied!
{
"url": "https://hpp.worldpay.com/session/8536a950-e04d-48bb-a7f8-129573e1ccd7"
}

Use the link in the url element to redirect your customer to the payment pages and complete the payment.

Note: In case of an error, you can get further information in ourerror reference.

Next steps

Redirect your customer