The Payment Pages API from Worldpay — 1 operation(s) for payment pages.
openapi: 3.0.1
info:
title: 3DS 3DS actions Payment Pages API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe 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 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Payment Pages
paths:
/payment_pages:
post:
operationId: create
parameters:
- description: Used to identify individual requests made to our API.
in: header
name: WP-CorrelationId
required: true
schema:
type: string
pattern: ^[0-9a-zA-Z_-]{1,64}$
- description: The name of the client calling the API.
in: header
name: User-Agent
required: false
schema:
type: string
requestBody:
content:
application/vnd.worldpay.payment_pages-v1.hal+json:
examples:
Guest Card Payment (all fields):
value:
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:
backgroundColor: '#FFFFFF'
color: '#000000'
page:
backgroundColor: '#333333'
color: '#FFFFFF'
border:
color: '#CCCCCC'
width: 1px
style: solid
radius: 4px
fonts:
family:
- Comic Sans MS
buttons:
backgroundColor: '#FF0'
color: '#333333'
border:
style: solid
color: '#0FF'
width: 3px
radius: 0px
fonts:
family:
- Comic Sans MS
hover:
backgroundColor: '#DDF'
color: '#111111'
border:
color: '#BBBBBB'
width: 2px
style: dotted
radius: 0px
fonts:
family:
- Comic Sans MS
focus:
backgroundColor: '#DFD'
color: '#222222'
border:
color: '#CCCCCC'
width: 2px
style: solid
radius: 0px
fonts:
family:
- Comic Sans MS
inputs:
backgroundColor: '#FFFFFF'
color: '#000000'
border:
style: solid
width: 2px
radius: 2px
color: '#FFF'
fonts:
family:
- Comic Sans MS
placeholder:
color: '#001'
validation:
ok:
color: '#00F'
error:
color: '#F00'
hover:
backgroundColor: '#FF0000'
color: '#7F0000'
border:
color: '#0FF'
width: 1px
style: solid
radius: 2px
fonts:
family:
- Comic Sans MS
placeholder:
color: '#AAAAAA'
validation:
ok:
color: '#00CC00'
error:
color: '#CC0000'
focus:
backgroundColor: '#0240FF'
color: '#001F7F'
border:
color: '#0FF'
width: 1px
style: solid
radius: 2px
fonts:
family:
- Comic Sans MS
placeholder:
color: '#BBBBBB'
validation:
ok:
color: '#009900'
error:
color: '#990000'
fonts:
family:
- Comic Sans MS
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'
Guest Card Payment (mandatory fields):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
Guest card payment (using customisation_id):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
customisation_id: Customisationidvalue1
Request 3DS and FraudSight off:
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
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
fraud:
type: disabled
threeDS:
type: disabled
expiry: '600'
Store a Card - card on file (all fields):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
description: Optional text displayed on HPP to your customer
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: worldpay
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: 123
currency: GBP
quantity: 1
createToken:
type: worldpay
namespace: SHOPPER_ID_1234567890
description: Test Token Description
optIn: ASK
customerAgreement:
type: cardOnFile
storedCardUsage: first
expiry: '600'
Store a Card - card on file (mandatory fields):
value:
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
customerAgreement:
type: cardOnFile
storedCardUsage: first
Store a Card - subscription (all fields):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
description: Optional text displayed on HPP to your customer
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: worldpay
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: 123
currency: GBP
quantity: 1
createToken:
type: worldpay
namespace: SHOPPER_ID_1234567890
description: Test Token Description
optIn: ASK
customerAgreement:
type: subscription
storedCardUsage: first
expiry: '600'
Store a Card - subscription (mandatory fields):
value:
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
customerAgreement:
type: subscription
storedCardUsage: first
Take Payment from a Stored Card - card on file (all fields):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
description: Optional text displayed on HPP to your customer
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:
dateOfBirth: '1835-04-01'
history:
createdAt: '1876-06-01'
modifiedAt: '1876-08-13'
paymentAccountEnrolledAt: '1876-06-01'
passwordModifiedAt: '1876-06-01'
type: guestUser
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
paymentInstrument:
type: card/tokenized
href: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
expiry: '600'
Take Payment from a Stored Card -card on file (mandatory fields):
value:
transactionReference: MyTransaction123
merchant:
entity: POxxxxxxxxx
narrative:
line1: Mind Palace Ltd
value:
currency: GBP
amount: 123
paymentInstrument:
type: card/tokenized
href: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
schema:
$ref: '#/components/schemas/Transaction'
description: The transaction to create.
responses:
'200':
content:
application/vnd.worldpay.payment_pages-v1.hal+json:
examples:
Successful response:
description: Successful response
value:
url: https://payments.worldpay.com/app/hpp/integration/transaction/xxxxxxxxxxxxxxxxxxxx&cs=yyyyyy
_links:
self:
href: https://access.worldpay.com/paymentQueries/payments?transactionReference=174420000000000
schema:
$ref: '#/components/schemas/SuccessfulCreateTransactionResponse'
description: Transaction creation was successful
'400':
content:
application/vnd.worldpay.payment_pages-v1.hal+json:
examples:
Invalid request response:
description: Invalid request response
value:
errorName: invalidRequest
message: Invalid request.
schema:
$ref: '#/components/schemas/AwpApiErrorResponse'
description: Bad request
'401':
content:
application/vnd.worldpay.payment_pages-v1.hal+json:
examples:
Unauthorized response:
description: Unauthorized response
value:
errorName: unauthorized
message: Invalid authentication
schema:
$ref: '#/components/schemas/AwpApiErrorResponse'
description: Unauthorized
'500':
content:
application/vnd.worldpay.payment_pages-v1.hal+json:
examples:
Internal error response:
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-payment-pages-api-openapi.yml