Skip to content
APIs/
Hosted Payment Pages (HPP...
/
Create a new transaction

Create a new transaction

Request

Security
BasicAuth
Headers
WP-CorrelationIdstring^[0-9a-zA-Z_-]{1,64}$required

Used to identify individual requests made to our API.

User-Agentstring

The name of the client calling the API.

Bodyapplication/vnd.worldpay.payment_pages-v1.hal+json

The transaction to create.

billingAddressobject

An object containing the billing address information.

createTokenobject

An object that instructs us to create a token for the payment details supplied.

customerAgreementobject

Contains specific customer agreements for the transaction. If this is present, then the creationToken must also be present.

customisation_idstring, = 21 characters^[A-Za-z0-9\_\-]*$

A unique value generated by us that represents the channel in the Payment Page Designer. If not sent, the "default" channel settings apply. You can overwrite individual customization styles and properties by using the hostedCustomization and hostedProperties objects.

descriptionstring, [ 0 .. 128 ] characters

An optional text, when supplied is displayed to your customer on payment pages.

expiryinteger, (int64), [ 300 .. 2592000 ]

Allows you to configure the duration, in seconds, your customer can access the payment link.

Default:3600
fraudobject
fundsTransferobject

Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction (AFT)).

Read more in the Account Funding Transactions guide.

hostedCustomizationobject

Add CSS options for each payment to customize the look and feel of the payment page.

hostedPropertiesobject

Add properties customization to allow merchants to specify the look of the payment page.

localestring

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

An object that contains information about the merchant.

narrativeobjectrequired

The text that appears on your customer's statement. Used to identify the merchant.

paymentInstrumentTokenPaymentInstrument (object)
One of:

An object that contains the payment type and details.

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.

riskDataobject

Data used for fraud and risk protection.

settlementobject

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

threeDSobject

An object containing 3DS authentication preferences, which you can use to turn 3DS off.

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.

valueobjectrequired

The payment amount.

Create transaction request including optional cross-border fundsTransfer with recipient bankAccount details

{
  "transactionReference": "fundsTransferTx005",
  "merchant": {
    "entity": "POxxxxxxxxx"
  },
  "narrative": {
    "line1": "Cross border bank account"
  },
  "value": {
    "currency": "USD",
    "amount": 2500
  },
  "fundsTransfer": {
    "type": "personToPerson",
    "purpose": "familySupport",
    "sender": {
      "firstName": "Jane",
      "middleName": "Alice",
      "lastName": "Doe",
      "dateOfBirth": "1989-04-09",
      "documentReference": "TAX-998877",
      "address": {
        "address1": "120 Main Street",
        "address2": "Apartment 5",
        "city": "New York",
        "postalCode": "10001",
        "state": "NY",
        "countryCode": "US"
      }
    },
    "recipient": {
      "firstName": "John",
      "middleName": "David",
      "lastName": "Doe",
      "dateOfBirth": "1987-11-21",
      "phoneNumber": "+1 416 555 0111",
      "documentReference": "ID-445566",
      "account": {
        "type": "bankAccount",
        "identifierType": "swift",
        "iban": "DE89370400440532013000",
        "accountNumber": "123456789012",
        "swiftBic": "BOFAUS3NXXX",
        "routingNumber": "021000021"
      },
      "address": {
        "address1": "25 Queen Street",
        "address2": "Suite 8",
        "city": "Toronto",
        "postalCode": "M5H 2N2",
        "state": "ON",
        "countryCode": "CA"
      }
    }
  }
}

Responses

Transaction creation was successful

Bodyapplication/vnd.worldpay.payment_pages-v1.hal+json
urlstring

The URL where your customer can be redirected to, to complete their payment.

Response

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