Payments (2024-06-01)

Use a single API that orchestrates the payment flow to include FraudSight, 3DS and Token creation.

Authentication

Set your headers

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

Replace {your_credentials} with your base64-encoded Basic Auth username and password.

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.

API Collection

A full set of API examples based on different scenarios.

Download Postman Collection

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License Worldpay

Servers

Try

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

Live

https://access.worldpay.com/

Payment

Take a payment

Operations

3DS Actions

If 3DS is enabled additional actions are required

Operations

Continue with payment after 3DS challenge

Request

Verify authentication challenge

Path

linkDatastringrequired

Headers

WP-Api-Versionstringrequired

The API version

Value"2024-06-01"

Example: 2024-06-01

No request payload

Responses

Created

Bodyapplication/json

outcomestring

Enum"3dsDeviceDataRequired""authorized""3dsChallenged""sentForSettlement""sentForCancellation""refused""3dsAuthenticationFailed""3dsUnavailable""fraudHighRisk""sentForRefund"

Discriminator

transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

A unique reference generated by you that is used to identify a payment throughout its lifecycle.

issuerobject

An object containing information returned by the issuer.

authorizationCodestring

riskFactorsArray of objects

Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified.

riskstring

Enum"notChecked""notMatched""notSupplied""verificationFailed"

detailstring

Enum"address""postcode"

typestring

Enum"avs""cvc""riskProfile"

fraudobject

Details of the outcome of the Fraud assessment

outcomestring

outcome of the fraud assessment. highRisk outcomes stop the transaction before payment.

Enum"lowRisk""highRisk""review""error""lowRisk(silentMode)""highRisk(silentMode)""review(silentMode)""error(silentMode)"

scorenumber(double)

The score calculated by the fraud assessment, set score thresholds are used to define lowRisk, highRisk and review outcomes

Example: 44

threeDSobject

Details of the outcome of the 3DS authentication

outcomestring

If the request was authenticated successfully

Default "authenticated"

issuerResponsestring

If the issuer decides to challenge the customer or proceed (frictionless)

Enum"frictionless""challenged"

exemptionobject

An object containing information about the exemption.

grantedboolean

Was an exemption returned by Worldpay's TRA assessment.

Enumtruefalse

placementstring

Indicates whether the exemption has been placed in a payment authorization request or 3DS authentication request.

Value	Description
authorization	Exemption applied in the payment authorization.

typestring

The type of applied exemption.

Enum Value	Description
lowValue	Applied a `lowValue` exemption
lowRisk	Applied a `lowRisk` exemption

resultstring

The result of the exemption placement request.

Enum Value	Description
rejected	Possible reason: `issuerRejected`, `highRisk`, `invalid`, `unsupportedScheme`, `notSubscribed`, `unsupportedAcquirer` or `unknown`
honored	Possible reason: `issuerHonored` or `unknown`
outOfScope	Possible reason: `merchantInitiatedTransaction`, `oneLegOut`, `moto`, `contactless` or `unknown`
unknown	Possible reason: `unknown`

reasonstring

The reason returned by the card issuer.

Enum"issuerHonored""merchantInitiatedTransaction""oneLegOut""issuerHonored""moto""contactless""issuerRejected""highRisk""invalid""unsupportedScheme"

tokenobject

Details of the token created

hrefstring

Example: "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiUW5rZHBXZDZ1MzBBY0I0MTVJQUdPeGE3ZkFobE1lTjJyYk05eDZxQUJ2RT0ifQ"

tokenIdstring

Example: "9997095516055002467"

tokenExpiryDateTimestring

Example: "2024-04-12T11:49:56Z"

cardNumberstring

Example: "4000********1091"

cardHolderNamestring

Example: "Sherlock Holmes"

cardExpiryobject

Contains your customer's card or token expiry date.

binstring

Example: "400000"

fundingTypestring

Example: "debit"

countryCodestring

schemeReferencestring

Example: "060720116005060"

conflictsobject

schemeReferencestring

An object containing information returned by the scheme.

_linksobject

Return details about the status of the payment

selfobject

_actionsobject

cancelPaymentobject

Cancel the payment. See details

settlePaymentobject

Fully settle the payment. See details

partiallySettlePaymentobject

Partially settle the payment. See details including what to add in the request body.

paymentInstrumentobject

typestring

cardBinstring

lastFourstring

countryCodestring

expiryDateobject

Contains your customer's card or token expiry date.

cardBrandstring

fundingTypestring

categorystring

issuerNamestring

paymentAccountReferencestring

Response

application/json

Example of a authorized response following a successful 3DS challenge, use the action settlePayment to complete the transaction

includes fraud, token and threeDS objects

{
  "outcome": "authorized",
  "transactionReference": "Memory265-13/08/1876",
  "riskFactors": [
    {
      "risk": "notChecked",
      "type": "cvc"
    },
    {
      "risk": "notChecked",
      "detail": "address",
      "type": "avs"
    },
    {
      "risk": "notChecked",
      "detail": "postcode",
      "type": "avs"
    }
  ],
  "fraud": {
    "outcome": "lowRisk",
    "score": 44.6
  },
  "threeDS": {
    "outcome": "authenticated",
    "issuerResponse": "challenged"
  },
  "token": {
    "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiRVl3SDBtNnpEVmVTR3UzRUV3VEJEVDExTkxuVDVydXNiREdLR01hUXUwVT0ifQ",
    "tokenId": "9968110159504301628",
    "tokenExpiryDateTime": "2024-04-11T15:59:23Z",
    "cardNumber": "4000********1000",
    "cardHolderName": "test",
    "cardExpiry": {
      "year": 2035,
      "month": 5
    },
    "bin": "400000",
    "fundingType": "debit",
    "schemeReference": "060720116005060",
    "conflicts": {
      "conflictsExpiryDateTime": "2024-07-04T06:40:32.310316518Z",
      "paymentInstrument": {
        "cardHolderName": "John Snow"
      }
    }
  },
  "paymentInstrument": {
    "type": "card/plain+masked",
    "cardBin": "400000",
    "lastFour": "1000",
    "countryCode": "GB",
    "expiryDate": {
      "year": 2035,
      "month": 5
    },
    "cardBrand": "mastercard",
    "fundingType": "debit",
    "category": "consumer",
    "issuerName": "BANK LIMITED",
    "paymentAccountReference": "3001DBT34Q41D6J7PFC5W0UACOT4C"
  },
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D"
    }
  },
  "_actions": {
    "cancelPayment": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/cancellations",
      "method": "POST"
    },
    "settlePayment": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/settlements",
      "method": "POST"
    },
    "partiallySettlePayment": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/partialSettlements",
      "method": "POST"
    }
  }
}

Supply 3DS device data

Request

Gather additional device data

Path

linkDatastringrequired

Headers

WP-Api-Versionstringrequired

The API version

Value"2024-06-01"

Example: 2024-06-01

Bodyapplication/json

collectionReferencestring

Add the sessionId provided in the postMessage for the device data collection form (web) or for native (iOS/Android), returned as consumerSessionId as part of SDK initialization.

Note: If device data collection fails you can attempt the payment without this value, but you will see an increased number of challenged and even authenticationFailed outcomes, if this happens for a lot of requests.

application/json

{
  "collectionReference": "string"
}

Responses

Created

Bodyapplication/json

outcomestring

Enum"3dsDeviceDataRequired""authorized""3dsChallenged""sentForSettlement""sentForCancellation""refused""3dsAuthenticationFailed""3dsUnavailable""fraudHighRisk""sentForRefund"

Discriminator

transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

A unique reference generated by you that is used to identify a payment throughout its lifecycle.

issuerobject

An object containing information returned by the issuer.

authorizationCodestring

riskFactorsArray of objects

Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified.

riskstring

Enum"notChecked""notMatched""notSupplied""verificationFailed"

detailstring

Enum"address""postcode"

typestring

Enum"avs""cvc""riskProfile"

fraudobject

Details of the outcome of the Fraud assessment

outcomestring

outcome of the fraud assessment. highRisk outcomes stop the transaction before payment.

Enum"lowRisk""highRisk""review""error""lowRisk(silentMode)""highRisk(silentMode)""review(silentMode)""error(silentMode)"

scorenumber(double)

The score calculated by the fraud assessment, set score thresholds are used to define lowRisk, highRisk and review outcomes

Example: 44

threeDSobject

Details of the outcome of the 3DS authentication

outcomestring

If the request was authenticated successfully

Default "authenticated"

issuerResponsestring

If the issuer decides to challenge the customer or proceed (frictionless)

Enum"frictionless""challenged"

exemptionobject

An object containing information about the exemption.

grantedboolean

Was an exemption returned by Worldpay's TRA assessment.

Enumtruefalse

placementstring

Indicates whether the exemption has been placed in a payment authorization request or 3DS authentication request.

Value	Description
authorization	Exemption applied in the payment authorization.

typestring

The type of applied exemption.

Enum Value	Description
lowValue	Applied a `lowValue` exemption
lowRisk	Applied a `lowRisk` exemption

resultstring

The result of the exemption placement request.

Enum Value	Description
rejected	Possible reason: `issuerRejected`, `highRisk`, `invalid`, `unsupportedScheme`, `notSubscribed`, `unsupportedAcquirer` or `unknown`
honored	Possible reason: `issuerHonored` or `unknown`
outOfScope	Possible reason: `merchantInitiatedTransaction`, `oneLegOut`, `moto`, `contactless` or `unknown`
unknown	Possible reason: `unknown`

reasonstring

The reason returned by the card issuer.

Enum"issuerHonored""merchantInitiatedTransaction""oneLegOut""issuerHonored""moto""contactless""issuerRejected""highRisk""invalid""unsupportedScheme"

tokenobject

Details of the token created

hrefstring

Example: "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiUW5rZHBXZDZ1MzBBY0I0MTVJQUdPeGE3ZkFobE1lTjJyYk05eDZxQUJ2RT0ifQ"

tokenIdstring

Example: "9997095516055002467"

tokenExpiryDateTimestring

Example: "2024-04-12T11:49:56Z"

cardNumberstring

Example: "4000********1091"

cardHolderNamestring

Example: "Sherlock Holmes"

cardExpiryobject

Contains your customer's card or token expiry date.

binstring

Example: "400000"

fundingTypestring

Example: "debit"

countryCodestring

schemeReferencestring

Example: "060720116005060"

conflictsobject

schemeReferencestring

An object containing information returned by the scheme.

_linksobject

Return details about the status of the payment

selfobject

_actionsobject

cancelPaymentobject

Cancel the payment. See details

settlePaymentobject

Fully settle the payment. See details

partiallySettlePaymentobject

Partially settle the payment. See details including what to add in the request body.

paymentInstrumentobject

typestring

cardBinstring

lastFourstring

countryCodestring

expiryDateobject

Contains your customer's card or token expiry date.

cardBrandstring

fundingTypestring

categorystring

issuerNamestring

paymentAccountReferencestring

Response

application/json

As an additional fraud measure the issuer requests a 3DS challenge to be performed

{
  "outcome": "3dsChallenged",
  "transactionReference": "Memory265-13/08/1876",
  "authentication": {
    "version": "2.1.0"
  },
  "challenge": {
    "reference": "706hovL8DK1tIGGzQUV1",
    "url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJPYmplY3RpZnlQYXlsb2FkIjpmYWxzZSwiaXNzIjoiNjYwMzAwN2ExNmRkOWE3ZTZhMDMzNDA3IiwiUmV0dXJuVXJsIjoiaHR0cDovL3BheW1lbnQuZXhhbXBsZS5jb20iLCJQYXlsb2FkIjoie1wiUGF5bG9hZFwiOlwiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUppTkRKbE5UWmpaaTAyWkRrMkxUUXpNek10T0dJMk5DMWlNbVU0TldZMFpURTFaVGtpTENKaFkzTlVjbUZ1YzBsRUlqb2laV1ZqWldZeE1ETXRNRE13TVMwMFpUbGtMVGsxTmpFdE56ZGlNbVkzTlRFMk5HUmhJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQTBJbjBcIixcIkFDU1VybFwiOlwiaHR0cHM6XFwvXFwvMW1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbVxcL01lcmNoYW50QUNTV2ViXFwvY3JlcS5qc3BcIixcIlRyYW5zYWN0aW9uSWRcIjpcIjcwNmhvdkw4REsxdElHR3pRVVYxXCJ9IiwiZXhwIjoxNzEyMzA2MDk0LCJpYXQiOjE3MTIzMDU0OTQsImp0aSI6IjE4YTIwYzNkLTZhZmMtNDA5My04NGEwLTQ2OGEyYTY5MTE0OCJ9.YEpOuTxnqrXRiHan-givWBd6FfTDJOfNg-h2dF2yA6A",
    "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJiNDJlNTZjZi02ZDk2LTQzMzMtOGI2NC1iMmU4NWY0ZTE1ZTkiLCJhY3NUcmFuc0lEIjoiZWVjZWYxMDMtMDMwMS00ZTlkLTk1NjEtNzdiMmY3NTE2NGRhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0"
  },
  "_actions": {
    "complete3dsChallenge": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiZXlOaXNtU0lzQnVLTm5BQkt1WjEyMVFxeXg2bUZtb2hEcEpFeDdyYXZ3SDE3NFBpUTBsWUpwekptbW9hR3VVSyJ9/3dsChallenges",
      "method": "POST"
    }
  }
}

Manage Payments

Additional payment actions following authorization

Operations

Payments (2024-06-01)

Payment

3DS Actions

Continue with payment after 3DS challenge

Request

Responses

Do you like our page?

Supply 3DS device data

Request

Responses

Do you like our page?

Manage Payments