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 OpenAPI description
Overview
License

Worldpay

Languages
Servers
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

An object containing Payment Facilitator information. This information is required for every authorization only if you are a Payment Facilitator

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.

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

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

paymentInstrumentobject
typestring
cardBinstring
lastFourstring
countryCodestring
expiryDateobject

Contains your customer's card or token expiry date.

cardBrandstring
fundingTypestring
categorystring
issuerNamestring
paymentAccountReferencestring
updatedPaymentInstrumentobject

Details of the updated payment instrument.

appliedNetworkTokenboolean

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

typestring
Enum"card/plain""card/plain+masked"
Example: "card/plain+masked"
accountUpdaterMessagestring

Details on the type of payment instrument update.

Enum"The merchant is not registered in the update program""The account number was changed""The account was closed""The expiry was changed""The issuing bank does not participate in the update program""Contact the cardholder for updated information""No match found""The account number was changed"
Example: "The account number was changed"
cardNumberstring
cardBinstring

The updated card BIN (Bank Identification Number).

Example: "444433"
lastFourstring

The four digits of the updated card. Some characters may be obfuscated with a * if the PAN length is less than 16 characters.

Example: "1111"
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

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

ECIMeaning
02 or 05Fully Authenticated Transaction
01 or 06Attempted Authentication Transaction
00 or 07Non 3-D Secure Transaction
SchemeValue
Mastercard02, 01, 00
Visa05, 06, 07
Amex05, 06, 07
JCB05, 06, 07
Diners05, 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.

Enumtruefalse
placementstring

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

ValueDescription
authorization

Exemption applied in the payment authorization.

typestring

The type of applied exemption.

Enum ValueDescription
lowValue

Applied a lowValue exemption

lowRisk

Applied a lowRisk exemption

resultstring

The result of the exemption placement request.

Enum ValueDescription
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

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