# Create a new transaction

Endpoint: POST /payment_pages
Version: 1
Security: BasicAuth

## Header parameters:

  - `WP-CorrelationId` (string, required)
    Used to identify individual requests made to our API.

  - `User-Agent` (string)
    The name of the client calling the API.

## Request fields (application/vnd.worldpay.payment_pages-v1.hal+json):

  - `billingAddress` (object)
    An object containing the billing address information.

  - `billingAddress.address1` (string)
    Address line 1.

  - `billingAddress.address2` (string)
    Address line 2.

  - `billingAddress.address3` (string)
    Address line 3.

  - `billingAddress.city` (string)
    Address city.

  - `billingAddress.countryCode` (string)
    The supported ISO 3166-1 alpha-2 country code.

  - `billingAddress.firstName` (string)
    The customer's first name.

  - `billingAddress.lastName` (string)
    The customer's last name.

  - `billingAddress.postalCode` (string)
    Required for all countries except the following: * IE

  - `billingAddress.state` (string)
    Address state or region.

  - `createToken` (object)
    An object that instructs us to create a token for the payment details supplied.

  - `createToken.description` (string)
    A description of your token. If not supplied, a default description is created for you.

  - `createToken.namespace` (string)
    A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.

  - `createToken.optIn` (string, required)
    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"

  - `createToken.type` (string, required)
    The type of token to be created.
    Enum: "worldpay"

  - `customerAgreement` (object)
    Contains specific customer agreements for the transaction. If this is present, then the creationToken must also be present.

  - `customerAgreement.storedCardUsage` (string, required)
    How the card is being used.
    Enum: "first", "subsequent"

  - `customerAgreement.type` (string, required)
    The processing arrangement agreed with your customer.
    Enum: "cardOnFile", "subscription"

  - `customisation_id` (string)
    A unique value that identifies which customization should be use for this transaction. Set it to null to use the default customization.

  - `description` (string)
    An optional text, when supplied is displayed to your customer on payment pages.

  - `expiry` (integer)
    Allows you to configure the duration, in seconds, your customer can access the payment link.

  - `fraud` (object)

  - `fraud.type` (string)
    You can use this to disable FraudSight for this request.
    Enum: "disabled"

  - `hostedCustomization` (object)
    Add CSS options for each payment to customize the look and feel of the payment page.

  - `hostedCustomization.backgroundColor` (string)
    Background color for the payment page in hex format. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.buttons` (object)
    Defines hover and focus styling for buttons on the HPP page.

  - `hostedCustomization.buttons.backgroundColor` (string)
    Hex color code for background color. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.buttons.border` (object)
    Defines border styling options for elements on the payment page, including color, width, radius and style.

  - `hostedCustomization.buttons.border.color` (string)
    Defines border color in HEX format. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.buttons.border.radius` (string)
    Defines border radius in pixels (0-30), must include px suffix.

  - `hostedCustomization.buttons.border.style` (string)
    Border style allowed values: solid, none, dotted, dashed, double.

  - `hostedCustomization.buttons.border.width` (string)
    Defines border width in pixels (0-30), must include px suffix.

  - `hostedCustomization.buttons.color` (string)
    Hex color code for text color. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.buttons.focus` (object)
    Defines custom styling options for buttons on the HPP page. Including color, border and text styles.

  - `hostedCustomization.buttons.focus.fonts` (object)
    Defines font styling options for text displayed on the payment pages, including the list of preferred font families.

  - `hostedCustomization.buttons.focus.fonts.family` (array)
    List of preferred font families for text on the payment page (e.g Arial, Times New Roman).

  - `hostedCustomization.buttons.hover` (object)
    Defines custom styling options for buttons on the HPP page. Including color, border and text styles.

  - `hostedCustomization.color` (string)
    Text color for the payment page in hex format. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.inputs` (object)
    Defines custom styling for input fields when hovered over or focused.

  - `hostedCustomization.inputs.focus` (object)
    Defines custom styling options for input fields including placeholder text and validation messages.

  - `hostedCustomization.inputs.focus.placeholder` (object)
    Defines styling options for placeholder text in input fields.

  - `hostedCustomization.inputs.focus.placeholder.color` (string)
    Hex color code for the placeholder text. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.inputs.focus.validation` (object)
    Styling properties for validation messages in input fields, including success and error indicators.

  - `hostedCustomization.inputs.focus.validation.error` (object)
    Styling properties for validation status messages, defining colors for success or error states.

  - `hostedCustomization.inputs.focus.validation.error.color` (string)
    Hex color code defining the style of the validation messages. You can use three digit or six digit codes (e.g. #FFO or #DD99CC).

  - `hostedCustomization.inputs.focus.validation.ok` (object)
    Styling properties for validation status messages, defining colors for success or error states.

  - `hostedCustomization.inputs.hover` (object)
    Defines custom styling options for input fields including placeholder text and validation messages.

  - `hostedCustomization.page` (object)
    Represents styling and customizations applied to the entire payment page, including colors, fonts, and borders.

  - `hostedProperties` (object)
    Add properties customization to allow merchants to specify the look of the payment page.

  - `hostedProperties.applePayButtonStyle` (string)
    Change the color displayed on the Apple Pay button. Accepts values: black, white-outline, white.

  - `hostedProperties.applePayButtonType` (string)
    Change the text displayed on the Apple Pay button. Accepts values: plain, book, buy, check-out, donate, set-up, subscribe, add-money, contribute, order, reload, rent, support, tip, top-up.

  - `hostedProperties.disableStrictUrls` (string)
    When set to true/false, append the additional information after/before the result URL query string. Accepts boolean values: true or false.

  - `hostedProperties.googlePayButtonColour` (string)
    Change the color displayed on the Google Pay button. Accepts values: white or black.

  - `hostedProperties.googlePayButtonLabel` (string)
    Change the text displayed on the Google Pay button. Accepts values: long or short.

  - `hostedProperties.maskCardDetails` (string)
    Hidden card and CVC number as they are typed. Accepts boolean values: true or false.

  - `hostedProperties.passBackErrorReasons` (string)
    Append error reasons to the result URL. Accepts boolean values: true or false.

  - `hostedProperties.paymentButtonLabel` (string)
    Options to change the payment button text. Accepts values: makePayment, submitPayment, buyNow, payNow, pay, saveAccount, saveCard, save, add, addCard, bookNow, continue.

  - `hostedProperties.sendURLParameters` (string)
    Send url parameters in the callback. Accepts boolean values: true or false.

  - `hostedProperties.showBillingAddress` (string)
    Displays the billing address of the customer on the payment pages. Accepts ENUM values: SHOW, HIDE, and EDIT.

  - `hostedProperties.showCancelButton` (string)
    Display the cancel button that lets customer cancel the payment. Accepts boolean values: true or false.

  - `hostedProperties.showCardIcons` (string)
    Display logos for card payments on the payment page. Accepts boolean values: true or false.

  - `hostedProperties.showCardholderName` (string)
    Display the card holder name on the payment page. Accepts boolean values: true or false.

  - `hostedProperties.showChangePaymentMethodButton` (string)
    Display the change payment method button to let customer return to the payment method selection page. Accepts boolean values: true or false.

  - `hostedProperties.showContactDetails` (string)
    Displays the contact details of the customer on the payment pages. Accepts ENUM values: SHOW, HIDE, and EDIT.

  - `hostedProperties.showCountryList` (string)
    Displays a drop-down list of countries on the payment pages. Accepts boolean values: true or false.

  - `hostedProperties.showFooter` (string)
    Display the worldpay copyright information footer on the payment page. Accepts boolean values: true or false.

  - `hostedProperties.showHeader` (string)
    Display the selected logo and associated space around the logo Accepts boolean values: true or false.

  - `hostedProperties.showLanguageList` (string)
    Displays a drop-down list of languages on the payment pages. Accepts boolean values: true or false.

  - `hostedProperties.showPaymentDetailsHeader` (string)
    Display the payment header on the payment page. Accepts boolean values: true or false.

  - `hostedProperties.showPoweredByWorldPay` (string)
    The "Powered by Worldpay" logo (referring to "worldpay" on the payment pages) is displayed while content is being displayed on a payment page. Accepts boolean values: true or false.

  - `hostedProperties.showShippingAddress` (string)
    Displays the shipping address of the customer on the payment pages. Accepts ENUM values: SHOW, HIDE, and EDIT.

  - `locale` (string)
    A BCP 47 locale tag, from the specified list. If set to null or absent from the request, will default to English (en).
    Enum: "ar", "bg", "bs", "ca", "cs", "cy", "da", "de", "en", "el", "es", "es-CO", "et", "fi", "fr", "ga", "he", "hi", "hr", "hu", "it", "ja", "ko", "lt", "lv", "nl", "no", "pl", "pt", "pt-BR", "ro", "ru", "si", "sk", "sl", "sv", "th", "tr", "ua", "zh", "zh-TW"

  - `merchant` (object, required)
    An object that contains information about the merchant.

  - `merchant.entity` (string, required)
    Used to route the request in Access Worldpay, created as part of on-boarding.

  - `narrative` (object, required)
    The text that appears on your customer's statement. Used to identify the merchant.

  - `narrative.line1` (string, required)
    line1 is used to provide basic details about the merchant.

  - `paymentInstrument` (any)

  - `resultURLs` (object)
    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.

  - `resultURLs.cancelURL` (string)
    When your customer cancels a transaction, we redirect that customer to the cancel URL.

  - `resultURLs.errorURL` (string)
    When we receive the payment result for an erroneous payment, we redirect your customer to the error URL.

  - `resultURLs.expiryURL` (string)
    When a customer leaves the payment transaction uncompleted within the maximum allowed time frame, we redirect your customer to the expiry URL.

  - `resultURLs.failureURL` (string)
    When a payment fails, we redirect your customer to the failure URL.

  - `resultURLs.pendingURL` (string)
    When we receive the payment result for a pending payment transaction, we redirect your customer to the pending URL.

  - `resultURLs.successURL` (string)
    When we receive the payment result for a successful payment, we redirect your customer to the success URL.

  - `riskData` (object)
    Data used for fraud and risk protection.

  - `riskData.account` (object)
    Object containing all customer account related risk data.

  - `riskData.account.dateOfBirth` (string)
    The date of birth of the customer.

  - `riskData.account.email` (string)
    The customer's email address.

  - `riskData.account.history` (object)
    History of the customer's account.

  - `riskData.account.history.createdAt` (string)
    The ISO 8601 date of when the customer's account was created.

  - `riskData.account.history.modifiedAt` (string)
    The ISO 8601 date of when the customer's account was last modified.

  - `riskData.account.history.passwordModifiedAt` (string)
    The ISO 8601 date of when the customer's account password was last modified.

  - `riskData.account.history.paymentAccountEnrolledAt` (string)
    The ISO 8601 date of when the payment account was added to the customer's account.

  - `riskData.account.previousSuspiciousActivity` (boolean)
    Indicates whether there's been suspicious activity in the past.

  - `riskData.account.shopperId` (string)
    A unique identifier of the customer.

  - `riskData.account.type` (string)
    The type of account being used by the customer.

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

  - `riskData.custom` (object)
    An object containing all data that can be used to configure manual fraud rules.

  - `riskData.custom.number1` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number2` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number3` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number4` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number5` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number6` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number7` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number8` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.number9` (string)
    Custom numeric value you can use to configure manual fraud rules.

  - `riskData.custom.string1` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string2` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string3` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string4` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string5` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string6` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string7` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string8` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.custom.string9` (string)
    Custom string value you can use to configure manual fraud rules.

  - `riskData.shipping` (object)
    Object containing all data related to how the order will be shipped.

  - `riskData.shipping.address` (object)

  - `riskData.shipping.address.phoneNumber` (string)
    Address phone number.

  - `riskData.shipping.address.postalCode` (string, required)
    Address postal code or zip number.

  - `riskData.shipping.email` (string)
    The email address used for an electronic delivery.

  - `riskData.shipping.firstName` (string)
    The first name of the shipping address.

  - `riskData.shipping.lastName` (string)
    The last name of the shipping address.

  - `riskData.shipping.method` (string)
    The shipping method used.

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

  - `riskData.shipping.nameMatchesAccountName` (boolean)
    Indicates whether the customer's name matches the name used for the shipping address.

  - `riskData.shipping.timeFrame` (string)
    The timeframe to ship the purchased goods.

  - `riskData.transaction` (object)
    Object containing all customer transaction related risk data.

  - `riskData.transaction.firstName` (string)
    Customer's first name.

  - `riskData.transaction.giftCardsPurchase` (object)
    Provided when the order is being used to purchase a gift card.

  - `riskData.transaction.giftCardsPurchase.quantity` (integer)
    The number of gift cards being purchased.

  - `riskData.transaction.giftCardsPurchase.totalValue` (object)
    The payment amount.

  - `riskData.transaction.giftCardsPurchase.totalValue.amount` (integer, required)
    The amount being placed on the gift card.

  - `riskData.transaction.giftCardsPurchase.totalValue.currency` (string, required)
    The three character currency code. See list of supported currencies.

  - `riskData.transaction.history` (object)
    Object containing details of the last transaction.

  - `riskData.transaction.history.addCardsLastDay` (integer)
    Number of attempts to add a card in the last 24hrs.

  - `riskData.transaction.history.attemptsLastDay` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.

  - `riskData.transaction.history.attemptsLastYear` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last year.

  - `riskData.transaction.history.completedLastSixMonths` (integer)
    Number of purchases with this customer account during the previous six months.

  - `riskData.transaction.history.shippingAddressFirstUsedAt` (string)
    The ISO 8601 date of when the shipping address, used for this transaction, was first used.

  - `riskData.transaction.lastName` (string)
    Customer's last name.

  - `riskData.transaction.phoneNumber` (string)
    Customer's phone number.

  - `riskData.transaction.preOrderDate` (string)
    Expected ISO 8601 date that a pre-ordered purchase will be available.

  - `riskData.transaction.reorder` (boolean)
    Indicates whether this transaction is a reorder of a previous order.

  - `settlement` (object)
    A value when specified allows you to turn auto settlement off. The default behavior is "true" and there is nothing to specify.

  - `settlement.auto` (boolean)

  - `settlement.cancelOn` (object)
    Optional object to control skip auto-cancel behavior for CVC mismatch.

  - `settlement.cancelOn.cvcNotMatched` (string)
    Must be disabled to skip auto-cancel on CVC mismatch.
    Example: "disabled"

  - `threeDS` (object)
    An object containing 3DS authentication preferences, which you can use to turn 3DS off.

  - `threeDS.type` (string)
    The 3DS type.
    Enum: "disabled"

  - `transactionReference` (string, required)
    A unique reference generated by you that is used to identify a payment throughout its lifecycle.

  - `value` (object, required)
    The payment amount.

  - `value.amount` (integer, required)
    The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.

## Response 200 fields (application/vnd.worldpay.payment_pages-v1.hal+json):

  - `_links` (object)
    The next action link, where merchants can perform certain actions (e.g., querying a payment).

  - `_links.self` (object)

  - `_links.self.href` (string)

  - `url` (string)
    The URL where your customer can be redirected to, to complete their payment.

## Response 400 fields (application/vnd.worldpay.payment_pages-v1.hal+json):

  - `errorName` (string)

  - `message` (string)

## Response 401 fields (application/vnd.worldpay.payment_pages-v1.hal+json):

  - `errorName` (string)

  - `message` (string)

## Response 500 fields (application/vnd.worldpay.payment_pages-v1.hal+json):

  - `errorName` (string)

  - `message` (string)