Skip to content

Last updated: 01 October 2025 | Change log

Get started

Make yourself familiar with our API Principles to ensure a resilient integration.

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/json
WP-Api-Version: 2023-06-01
HeaderDescription
AuthorizationWe use the Authorization header to identify and authenticate you within Access Worldpay. You must use the Authorization header for any request you send to our APM API.
Content-TypeWe 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.
WP-Api-VersionWe use the WP-Api-Version header to identify which version of our APM API you are using. You must use the WP-Api-Version header for any request you send to our API.

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

Note

Replace {your_credentials} with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.

Take a payment

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

Example request:

{
  "instruction": {
    "narrative": {
      "line1": "Mind Palace"
    },
    "paymentInstrument": {
      "type": "paypal",
      "country": "GB",
      "language": "aa",
      "failureURL": "https://example.com/failure",
      "cancelURL": "https://example.com/cancel",
      "pendingURL": "https://example.com/pending",
      "successURL": "https://example.com/success"
    },
    "value": {
      "amount": 25,
      "currency": "GBP"
    }
  },
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "Memory265-13/08/1876"
}

Parameters

ParameterRequired?DescriptionData typeLength
instruction✅An object that contains all the information related to the payment.ObjectN/A
instruction.narrative✅An object that helps your customers better identify you on their statement.ObjectSee our formatting rules
instruction.narrative.line1✅The first line of the narrative which appears on your customer's statement (If a character is not supported it is replaced with a space.).
See narrative line1 format for more details.		Object24
instruction.paymentInstrument✅An object that contains information about the payment method.ObjectN/A
instruction.paymentInstrument.type✅An object that contains the payment type and details. It defines which alternative payment method you wish to use. For PayPal the value is paypal.ObjectN/A
instruction.paymentInstrument.country❌An object that contains the country of your customer. Follows alpha 2 ISO 3166-1 standard.Object2
instruction.paymentInstrument.language❌An object that contains the language of your customer. Follows ISO 639-1 standard.String2
instruction.paymentInstrument.cancelURL❌When your customer cancels a transaction, we redirect your customer to that cancel URL.StringN/A
instruction.paymentInstrument.failureURL❌When a payment fails, we redirect your customer to the failure URL.StringN/A
instruction.paymentInstrument.pendingURL❌When we receive the payment result for a pending payment transaction, we redirect your customer to that pending URL.StringN/A
instruction.paymentInstrument.successURL❌When we receive the payment result for a successful payment, we redirect your customer to that success URL.StringN/A
instruction.value✅An object that contains information about the payment transaction.ObjectN/A
instruction.value.amount✅The 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
instruction.value.currency✅The payment currency. Refer to the individual APM page for supported currencies.Integer3
merchant✅An object that contains information about the merchant.ObjectN/A
merchant.entity✅Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries.
Contact your Implementation Manager for more details.		StringMust be between 1 and 32 characters.
transactionReference✅A 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.
Recommendation

We suggest you provide the cancelURL,failureURL, pendingURL and successURL attribute to redirect your customer to, once you have received the payment result.

Response

Successful request response

  • an HTTP code 201
  • an id which is unique to the payment - we recommend storing the "id" as this can be used to manage the payment later
  • a url to redirect your customer to the APM provider to complete the payment
  • a link to query the payment status

Example response:

{
  "id": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "url": "https://hpp.worldpay.com/app/hpp/xyz/integration/wpg?Ticket=12345678&OrderKey=blah",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apms/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  }
}
Note

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

List of available APMS

PayPal