Payments API

Payments API (2024-06-01)

Authentication

Set your headers

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

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 Insomnia Collection	Setup & environment config
Download Postman Collection	Setup & environment config

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License Worldpay

Servers

Try

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

Live

https://access.worldpay.com/

Submit a payment request

Request

Initiate Payment

Headers

WP-Api-Versionstringrequired

The API version

Value"2024-06-01"

Example: 2024-06-01

Bodyapplication/jsonrequired

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.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$required

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

Example: "default"

mccstring^\d{4}$

You can apply a merchant category code (mcc) to an individual request. You can only provide an mcc if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, merchant.mcc defaults to a configured value.

instructionobjectrequired

An object that contains all information related to the payment and API configurations.

methodstringrequired

The method of instruction.

Value"card"

Discriminator

paymentInstrumentobjectrequired

narrativeobjectrequired

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

tokenCreationobject

Use this object if you want to create a token after the payment. Can only be used with paymentInstrument.type: card/plain & checkout.

valueobjectrequired

debtRepaymentboolean

A flag which identifies a payment as being for the purpose of repaying a debt.

fraudobject

Fraud assessment to detect potential fraud and prevent the transaction from proceeding.

threeDSobject

An object containing 3DS authentication preferences.

settlementobject

Automatically settle a payment following authorization. If any of the AVS/CVC response riskFactors are marked as notMatched the payment will be sentForCancellation automatically.

customerobject

shippingobject

customerAgreementobject

Contains specific customer agreements for the transaction.

recipientobject

An object containing information about the recipient of financial services. Required for MCC 6012 transactions in the Visa Europe region. The recipient may or may not be the cardholder.

consumerBillPaymentboolean

An attribute that identifies a bill payment paid by providers on behalf of consumers. If you are registered with Visa as a Consumer of the Bill Payment Service (CBPS), you must set this to true for any payments associated with the CBPS.

application/json

A one-off card payment using a plain card number

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "card",
    "paymentInstrument": {
      "type": "plain",
      "cardHolderName": "Sherlock Holmes",
      "cardNumber": "4000000000001091",
      "expiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "SW1 1AA",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      },
      "cvc": "123"
    },
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    }
  }
}

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"

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

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

cardBrandstring

fundingTypestring

categorystring

issuerNamestring

paymentAccountReferencestring

Response

application/json

Example of an authorized response. Use the action settlePayment to complete the transaction

3DS is not enabled
includes fraud and token objects

{
  "outcome": "authorized",
  "transactionReference": "Memory265-13/08/1876",
  "issuer": {
    "authorizationCode": "675725"
  },
  "riskFactors": [
    {
      "risk": "notChecked",
      "type": "cvc"
    },
    {
      "risk": "notChecked",
      "detail": "address",
      "type": "avs"
    },
    {
      "risk": "notChecked",
      "detail": "postcode",
      "type": "avs"
    }
  ],
  "fraud": {
    "outcome": "lowRisk",
    "score": 44.6
  },
  "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",
    "countryCode": "GB",
    "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"
    }
  }
}

3DS Actions

Operations

Payments Lifecycle

Operations

Payments API (2024-06-01)

Submit a payment request

RequestExpand all

Responses

Do you like our page?

3DS Actions

Payments Lifecycle

Request