APM API (2024-07-01)

Authentication Set your headers

    Authorization: {your_credentials}
    Content-Type: application/json
    WP-Api-Version: 2024-07-01

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.

You must use the Authorization header for any request you send to our Account APIs, unless you are using client certificate authenticating with SSL/TLS.

DNS Whitelisting

Whitelist the following URLs:

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

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License Worldpay

Servers

Try

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

Live

https://access.worldpay.com/

Create an APM payment

Request

Perform a sale.

Headers

Content-Typestringrequired

The content type of the request body.

Value"application/json"

WP-Api-Versionstringrequired

The API version.

Value"2024-07-01"

Bodyapplication/jsonrequired

transactionReferencestring[ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$required

merchantobjectrequired

entitystring[ 1 .. 32 ] characters^([a-zA-Z0-9]*)$required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"

instructionobjectrequired

Object that contains the payment type and details.

methodstringrequired

Identifies the type of payment. More payment types are available on version 2023-06-01.

Value"paypal"

Discriminator

valueobjectrequired

The value of the payment.

narrativeobjectrequired

paymentInstrumentobjectrequired

settlementobject

Indicates whether the transaction should be sent for settlement now = true, or later = false at a time of your choosing.

resultUrlsobject

shippingobject

customerobject

application/json

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "paypal",
    "value": {
      "amount": 35,
      "currency": "GBP"
    },
    "narrative": {
      "line1": "MindPalace"
    },
    "paymentInstrument": {
      "type": "direct",
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "settlement": {
      "auto": true
    },
    "resultUrls": {
      "cancel": "https://example.com/cancel",
      "failure": "https://example.com/failure",
      "pending": "https://example.com/pending",
      "success": "https://example.com/success"
    },
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "address1": "The Palatine Centre",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB"
      }
    },
    "customer": {
      "email": "moriarty@example.com"
    }
  }
}

Responses

Request successful

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

reverseobject

Link to resources to reverse operation.

partialReverseobject

Link to resources to reverse operation.

settleobject

Link to resources to reverse operation.

partialSettleobject

Link to resources to reverse operation.

confirmPaymentobject

Link to resources to reverse operation.

redirectstring

The URL to redirect your customer to.

paymentInstrumentobject

methodstring

typestring

sdkReferencestring

SDK token used for PayPal Smart Button flow

Response

application/json

{
  "paymentId": "HZ75WBkfRwmD9YzLSZFnQ--xazN30hqhileEoUF53VKlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2K6uz6RKmSmP_m7-TgEHezOhzH5eLvBJHPh6ir8ugqJqGjb7dlrQPJ4byuGHVAMZ8",
  "lastEvent": "pending",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/HZ75WBkfRwmD9YzLSZFnQ--xazN30hqhileEoUF53VKlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2K6uz6RKmSmP_m7-TgEHezOhzH5eLvBJHPh6ir8ugqJqGjb7dlrQPJ4byuGHVAMZ8"
    }
  },
  "_actions": {},
  "redirect": "https://mock.hpp.worldpay.com/app/hpp/xyz/integration/wpg?Ticket=12345678&OrderKey=blah",
  "paymentInstrument": {
    "method": "paypal",
    "type": "redirect"
  }
}

Operational

Operations

Payment Lifecycle

Operations

Get the last event for an APM payment

Request

Lookup the state of a payment, including the available action that can be performed.

Path

paymentIdstringrequired

The identifier of the payment resource.

Headers

WP-Api-Versionstringrequired

The API version

Value"2024-07-01"

No request payload

Responses

Request successful

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

reverseobject

Link to resources to reverse operation.

partialReverseobject

Link to resources to reverse operation.

settleobject

Link to resources to reverse operation.

partialSettleobject

Link to resources to reverse operation.

Response

application/json

{
  "paymentId": "HZ75WBkfRwmD9YzLSZFnQ0aww_aMF9fAHidQrEC483OlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2pzlfJNMqKvq0mYDWxvR0iOhzH5eLvBJHPh6ir8ugqJmt5VJZ_vcfGLqPgLOBUAk4",
  "lastEvent": "authorized",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/HZ75WBkfRwmD9YzLSZFnQ0aww_aMF9fAHidQrEC483OlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2pzlfJNMqKvq0mYDWxvR0iOhzH5eLvBJHPh6ir8ugqJmt5VJZ_vcfGLqPgLOBUAk4"
    }
  },
  "_actions": {
    "reverse": {
      "href": "https://try.access.worldpay.com/apmPayments/HZ75WBkfRwmD9YzLSZFnQ0aww_aMF9fAHidQrEC483OlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2pzlfJNMqKvq0mYDWxvR0iOhzH5eLvBJHPh6ir8ugqJmt5VJZ_vcfGLqPgLOBUAk4/reversals",
      "method": "POST"
    },
    "partialReverse": {
      "href": "https://try.access.worldpay.com/apmPayments/HZ75WBkfRwmD9YzLSZFnQ0aww_aMF9fAHidQrEC483OlDSUrxrcX5x_wn93uYUZB26bWaGtSc4n1mbKHCn5p1tAsrh_YcN6kEXom71Xl4C2pzlfJNMqKvq0mYDWxvR0iOhzH5eLvBJHPh6ir8ugqJmt5VJZ_vcfGLqPgLOBUAk4/reversals",
      "method": "POST"
    }
  }
}

Confirm Payment

Request

Create a confirm payment request for smart button functionality.

Path

paymentIdstringrequired

The identifier of the payment resource.

Headers

WP-Api-Versionstringrequired

The API version

Value"2024-07-01"

No request payload

Responses

Request successful

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

Response

application/json

{
  "paymentId": "uK9Oh5zz4yKhGuFofhhnC_h2WwCXUTVwK1Lx7OP-WOiwgLd0DJ5uYK8NLsKG-rFtM4xXFxk15W-f-R1c3u_fq6rRIVQO_lZhwklop_5RcXz35RD_4TJfbjKQAyEFQXOTgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxpba-zPVQ7PG1AztEwRCfVJ",
  "lastEvent": "authorized",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/uK9Oh5zz4yKhGuFofhhnC_h2WwCXUTVwK1Lx7OP-WOiwgLd0DJ5uYK8NLsKG-rFtM4xXFxk15W-f-R1c3u_fq6rRIVQO_lZhwklop_5RcXz35RD_4TJfbjKQAyEFQXOTgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxpba-zPVQ7PG1AztEwRCfVJ"
    }
  },
  "_actions": {}
}

Reverse an APM payment

Request

Perform a reversal on the funds taken from a sale.

Path

paymentIdstringrequired

The identifier of the payment resource.

Headers

Content-Typestringrequired

The content type of the request body.

Value"application/json"

Bodyapplication/jsonrequired

referencestring[ 1 .. 128 ] characters^[a-zA-Z0-9\\-]*$

valueobjectrequired

The value of the payment.

amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 1234

currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"

application/json

{
  "reference": "string",
  "value": {
    "amount": 1234,
    "currency": "AED"
  }
}

Responses

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

Response

application/json

{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForRefund",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {}
}

Partial reverse an APM payment

Request

Perform a partial reversal on the funds taken from a sale.

Path

paymentIdstringrequired

The identifier of the payment resource.

Headers

Content-Typestringrequired

The content type of the request body.

Value"application/json"

WP-Api-Versionstringrequired

The API version

Value"2024-07-01"

Bodyapplication/jsonrequired

referencestring[ 1 .. 128 ] characters^[a-zA-Z0-9\\-]*$

valueobjectrequired

The value of the payment.

amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 1234

currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"

application/json

{
  "reference": "string",
  "value": {
    "amount": 1234,
    "currency": "AED"
  }
}

Responses

Request successful

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

Response

application/json

{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForRefund",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {}
}

Settle an APM payment

Request

Path

paymentIdstringrequired

Bodyapplication/jsonrequired

string

application/json

"string"

Responses

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

Response

application/json

{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForSettlement",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {}
}

Partial settle an APM payment

Request

Perform a settlement on authorized funds. Not all APMs support this, please check the links returned from querying a payment.

Path

paymentIdstringrequired

The identifier of the payment resource.

Headers

Content-Typestringrequired

The content type of the request body

Value"application/json"

WP-Api-Versionstringrequired

The API version

Value"2024-07-01"

Bodyapplication/jsonrequired

referencestring[ 1 .. 128 ] characters^[a-zA-Z0-9\\-]*$

valueobjectrequired

The value of the payment.

amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 1234

currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"

application/json

{
  "reference": "string",
  "value": {
    "amount": 1234,
    "currency": "AED"
  }
}

Responses

Request successful

Bodyapplication/json

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject

Links to resources related to the request.

selfobject

The URL you can invoke to fetch the last event for the payment.

_actionsobject

Response

application/json

{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForSettlement",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {}
}

APM API (2024-07-01)

Create an APM payment

Request

Responses

Do you like our page?

Operational

Payment Lifecycle

Get the last event for an APM payment

Request

Responses

Do you like our page?

Confirm Payment

Request

Responses

Do you like our page?

Reverse an APM payment

Request

Responses

Do you like our page?

Partial reverse an APM payment

Request

Responses

Do you like our page?

Settle an APM payment

Request

Responses

Do you like our page?

Partial settle an APM payment

Request

Responses

Do you like our page?

APM API (2024-07-01)

Create an APM payment

RequestExpand all

Responses

Do you like our page?

Operational

Payment Lifecycle

Get the last event for an APM payment

Request

Responses

Do you like our page?

Confirm Payment

Request

Responses

Do you like our page?

Reverse an APM payment

RequestExpand all

Responses

Do you like our page?

Partial reverse an APM payment

RequestExpand all

Responses

Do you like our page?

Settle an APM payment

Request

Responses

Do you like our page?

Partial settle an APM payment

RequestExpand all

Responses

Do you like our page?

Request

Request

Request

Request