Skip to content
APIs/APMs/
/
Confirm payment

APMs (2024-07-01)

Pay using eWallets, bank transfers, direct debits, local card schemes, Postpay and eInvoice/ Buy Now Pay Later.

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 APMs API.

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
Languages
Servers
Try
https://try.access.worldpay.com/
Live
https://access.worldpay.com/

Create an APM payment

Request

Perform a sale.

Security
BasicAuth
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[ 3 .. 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

Type of payment method

Value"ach"
Discriminator
valueobjectrequired

The value of the payment.

narrativeobjectrequired
paymentInstrumentobjectrequired
customerobjectrequired
application/json
{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "ach",
    "narrative": {
      "line1": "MindPalace"
    },
    "value": {
      "amount": 750,
      "currency": "USD"
    },
    "paymentInstrument": {
      "type": "direct",
      "accountType": "checking",
      "accountNumber": "01234567890123456",
      "routingNumber": "012345678",
      "checkNumber": "012345678901234",
      "companyName": "Worldpay",
      "billingAddress": {
        "address1": "8500 Govenors Hill Drive",
        "address2": "Symmes Township",
        "postalCode": "45249",
        "city": "Ohio",
        "state": "US-OH",
        "countryCode": "US"
      }
    },
    "customer": {
      "firstName": "John",
      "lastName": "Johnson",
      "customerId": "43424",
      "email": "john@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

commandIdstring

An action ID generated by us identifying a single merchant interaction

Example: "cmdYNdIHBPJwbkjLiykzTx0"
Response
application/json
{
  "paymentInstrument": {
    "method": "ach",
    "type": "direct"
  },
  "paymentId": "eyJrIjoiYXBtLXNlcnZpY2UtZGVmYXVsdCIsImxpbmtWZXJzaW9uIjoiNi4wLjAifQ==.BnnxxcMle38OazhwbF8J+4rtJi8CAq:Y3zUOn1dw6VWfvx:PHL5L0S+5ara5vz6ouV5yBmVUQCiSwQjs+1x5qJIJxAKWMWc2Mlb1doricEYlzsZIRIGCflvnYu1Ns8g1S0+66n6wCELiB9OHfX7cdDZM8QaH19DiFbmMAchPSTyxQUry+EjhI+4Av0FZgKybTQW8Eq5Lj6LFzcEh8YV9gKLyAJXKJwZGztDqfCZz9C54i7Qm6PznXY+lb8gjX08QbPuM7eN9CDfUDc8S4J3uauHV:lzKfpwhCpCj20XtN:AkTEXfvJEm8PKFuVlX10AbTZIsCMVbuMS1sIqrgbendo:b1Rfx8XquR8u:dBYr5a70wYkewsxOvrYXmLip3FvyJdzRzXf3LyUgHUqZh:ulvr2BwGjsfY6y32HN+osTE4dworCDzhGpsvEwJ:GRwLUNfeKBzVqK6WhJGqM+s8XpCA==",
  "lastEvent": "authorized",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/eyJrIjoiYXBtLXNlcnZpY2UtZGVmYXVsdCIsImxpbmtWZXJzaW9uIjoiNi4wLjAifQ==.BnnxxcMle38OazhwbF8J+4rtJi8CAq:Y3zUOn1dw6VWfvx:PHL5L0S+5ara5vz6ouV5yBmVUQCiSwQjs+1x5qJIJxAKWMWc2Mlb1doricEYlzsZIRIGCflvnYu1Ns8g1S0+66n6wCELiB9OHfX7cdDZM8QaH19DiFbmMAchPSTyxQUry+EjhI+4Av0FZgKybTQW8Eq5Lj6LFzcEh8YV9gKLyAJXKJwZGztDqfCZz9C54i7Qm6PznXY+lb8gjX08QbPuM7eN9CDfUDc8S4J3uauHV:lzKfpwhCpCj20XtN:AkTEXfvJEm8PKFuVlX10AbTZIsCMVbuMS1sIqrgbendo:b1Rfx8XquR8u:dBYr5a70wYkewsxOvrYXmLip3FvyJdzRzXf3LyUgHUqZh:ulvr2BwGjsfY6y32HN+osTE4dworCDzhGpsvEwJ:GRwLUNfeKBzVqK6WhJGqM+s8XpCA=="
    }
  },
  "_actions": {},
  "redirect": "",
  "commandId": "cmdSQBwMoFu3i2bNWmLGZLid0"
}

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.

Security
BasicAuth
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.

Security
BasicAuth
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.

Security
BasicAuth
Path
paymentIdstringrequired

The identifier of the payment resource.

Headers
Content-Typestringrequired

The content type of the request body.

Value"application/json"
WP-Api-Versionstring

The API version.

Value"2024-07-01"
Bodyapplication/json
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: 12
currencystringrequired

The supported ISO 4217 currency codes.

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

Mandatory for PIX payment method, not relevant for other payment methods.

Enum"BE08""FR01""MD06""SL02"
application/json
{
  "reference": "string",
  "value": {
    "amount": 12,
    "currency": "AED"
  }
}

Responses

OK

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.

Security
BasicAuth
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: 12
currencystringrequired

The supported ISO 4217 currency codes.

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

Mandatory for PIX payment method, not relevant for other payment methods.

Enum"BE08""FR01""MD06""SL02"
application/json
{
  "reference": "string",
  "value": {
    "amount": 12,
    "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

Security
BasicAuth
Path
paymentIdstringrequired
Bodyapplication/json
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: 12
currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"
application/json
{
  "reference": "string",
  "value": {
    "amount": 12,
    "currency": "AED"
  }
}

Responses

OK

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
commandIdstring
Response
application/json
{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForSettlement",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {},
  "commandId": "cmdEy5vwB0krLe9eMwAcE66c0"
}

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.

Security
BasicAuth
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: 12
currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"
application/json
{
  "reference": "string",
  "value": {
    "amount": 12,
    "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
commandIdstring
Response
application/json
{
  "paymentId": "3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f",
  "lastEvent": "sentForSettlement",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/3Ihrz_xFV1nTRAHhJABserDF09eNdqnSHh2H8qlv7QIZ4iW8JjMy1wo4b2GozzFtfnOUMIZGm4eSqTixJe1tGDzD3NTuoxp7Ud1N920NPyBiaK1MePsYPNh4StVn5GLv9dz9tm3t0o9KS2dze2cQ2iJdjRiX7-j4OEhFc5W4W6hK1prAjyQIHthwfovFL63f"
    }
  },
  "_actions": {},
  "commandId": "cmdEy5vwB0krLe9eMwAcE66c0"
}