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

Servers

Test (Try)

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

Live

https://access.worldpay.com/

Payment

Take a payment

Operations

Payment request

Request

Initiate payment

Security

BasicAuth

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.

paymentFacilitatorobject

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

The value and currency.

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.

Read more on how to set it up under our Fraud Assessment guide.

threeDSobject

An object containing 3DS authentication preferences.

Read more on how to set it up under our 3DS Authentication guide.

exemptionobject

An object used to request or specify an SCA Exemption.

Read more on how to set it up under our SCA Exemptions guide.

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.

Read more on how to set it up under our Auto Settlement guide.

customerobject

shippingobject

Object containing all data related to how the order will be shipped.

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.

Read more on how to set it up under our Financial Services guide.

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.

requestAccountUpdaterboolean

Allows you to request a real-time account update (Visa cards only) when using a previously stored card. You can only use this on subsequent card requests.

splitPaymentobject

Contains details of the split payment request.

fundsTransferobject

Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction (AFT)).

Read more on how to set it up under our Account Funding Transactions guide.

channelstring

Interaction between the cardholder and you. Supply a value of ecom to process an eCommerce authorization. Supply a value of moto to process an authorization as a Mail Order or Telephone Order transaction.

Note: 3DS authentication cannot be supplied for MOTO payments.

Enum"ecom""moto"

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

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.

paymentInstrumentobject

typestring

cardBinstring

lastFourstring

countryCodestring

expiryDateobject

Contains your customer's card or token expiry date.

cardBrandstring

fundingTypestring

categorystring

issuerNamestring

paymentAccountReferencestring

updatedPaymentInstrumentobject

typestringrequired

The type of updated instrument.

Value"card/plain"

Discriminator

appliedNetworkTokenboolean

Returned if the payment instrument was swapped for a network token.

cardNumberstring

accountUpdaterMessagestring

Details on the type of payment instrument update.

Enum Value	Description
The issuing bank does not participate in the update program	Returned for Real Time Account Updater only. It is not known whether an account update is available.
Contact the cardholder for updated information	A match was found but you may need to contact the cardholder for updated card details. This could be due to cardholder opt-out or other reasons.
The account number was changed	A new card has been issued with a change in the card number.
No changes found	No changes to the card account were found.
The account was closed	The account is closed and the card is no longer valid. Ask your customer for an alternative payment method.
The merchant is not registered in the update program	Returned for Real Time Account Updater only. Contact Worldpay to enroll in the service.
The expiry was changed	A new card has been issued with an updated expiry date. In most cases the card number remains unchanged.
No match found	The BIN range is enrolled for account updates, but no match was found for the card account. One reason for this may be that the card issuer has recently changed.

Example: "The account number was changed"

expiryDateobject

Contains your customer's card or token expiry date.

cardBrandstring

The brand of the updated card. In rare circumstances a card may be reissued under a different brand.

fundingTypestring

How the card is funded.

countryCodestring

issuerobject

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 to define lowRisk, highRisk and review outcomes

Example: 44

threeDSobject

outcomestringrequired

If the request was authenticated successfully or an authentication outage exemption was applied in authorization.

Note

The authenticationOutage outcome is not enabled by default. Please contact your Implementation Manager if you would like to be set up to receive authenticationOutage responses.This increases the likelihood of receiving a successful authorization, but is not be eligible for liability shift.

Discriminator

issuerResponsestring

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

Enum"frictionless""challenged"

versionstring[ 1 .. 10 ] characters

The version of 3DS used to process the transaction.

ecistring[ 1 .. 2 ] characters

Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication.

ECI	Meaning
02 or 05	Fully Authenticated Transaction
01 or 06	Attempted Authentication Transaction
00 or 07	Non 3-D Secure Transaction

Scheme	Value
Mastercard	02, 01, 00
Visa	05, 06, 07
Amex	05, 06, 07
JCB	05, 06, 07
Diners	05, 06, 07

acsTransactionIdstring[ 1 .. 36 ] characters

An identifier assigned by the Access Control Server (ACS) to identify a single transaction. Used primarily for Mastercard 3RI subsequent transactions to link the subsequent transaction back to a previous cardholder authentication. Can be disregarded unless otherwise needed.

dsTransactionIdstring[ 1 .. 64 ] characters

Directory server transaction Id, if provided should be used in the payment authorization authentication object.

statusstring[ 1 .. 2 ] characters

Indicates the outcome of the authentication or verification request.

Y - Successful authentication
N - Failed authentication
U - Unable to complete authentication
A - Successful attempts authentication
C - Challenged authentication
R - Authentication rejected (merchant must not submit for authorization)
I - Exemption acknowledged

challengePreferencestring[ 1 .. 64 ] characters

Indicates the preferred challenge behavior. Returned for Cartes Bancaires authentications only and must be applied in the following authorization request.

noPreference
noChallengeRequested
challengeRequested
challengeMandated
noChallengeRequestedTRAPerformed

exemptionobject

An object containing information about the exemption.

grantedboolean

Was an exemption returned by Worldpay's TRA assessment.

placementstring

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

Enum Value	Description
authorization	Exemption applied in the payment authorization.
authentication	Exemption applied in the payment authentication.

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"

schemeReferencestring

An object containing information returned by the scheme.

tokenobject

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

splitPaymentobject

An object containing information about the split payment.

outcomestring

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

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

splitPaymentany

An object containing information about the split payment.

splitPaymentIdstring= 25 characters^spl[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a split payment.

lineItemsArray of objects

_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.

Response

application/json

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

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

If 3DS is enabled additional actions are required

Operations

Manage payments

Additional payment actions following authorization

Operations

Payments (2024-06-01)

Payment

Payment request

RequestExpand all

Responses

Do you like our page?

3DS actions

Manage payments

Request