The Verifications API from Worldpay — 3 operation(s) for verifications.
openapi: 3.0.1
info:
title: 3DS 3DS actions Verifications API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Verifications
paths:
/verifications/customers/3ds/deviceDataInitialization:
post:
summary: Generate required data for 3DS Device Data Collection
description: 'Allow card issuers to perform Device Data Collection to fingerprint your customer''s device.
'
operationId: deviceDataInitialize
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
- in: header
name: Accept
required: true
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
requestBody:
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_deviceDataInitialize'
examples:
card/front:
$ref: '#/components/examples/ddc-card'
card/tokenized:
$ref: '#/components/examples/ddc-token'
card/networkToken:
$ref: '#/components/examples/ddc-networktoken'
card/wallet+googlepay:
$ref: '#/components/examples/ddc-googlepay'
No payment instrument provided (only jwt returned):
$ref: '#/components/examples/ddc-request'
responses:
'200':
description: The data for the device data collection has been generated
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_deviceDataInitialize_200_response'
examples:
card/front:
$ref: '#/components/examples/ddc-jwt-bin'
card/tokenized:
$ref: '#/components/examples/ddc-jwt-bin'
card/networkToken:
$ref: '#/components/examples/ddc-jwt-bin'
Wallet token already authenticated:
$ref: '#/components/examples/already-authenticated'
No payment instrument provided (only jwt returned):
$ref: '#/components/examples/ddc-jwt-only'
'400':
description: The request has encountered validation errors
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_deviceDataInitialize_400_response'
examples:
The request is missing a mandatory field `transactionReference`:
description: The request does not have a mandatory field `transactionReference`
value:
message: The json body provided does not match the expected schema
errorName: bodyDoesNotMatchSchema
validationErrors:
- errorName: stringIsTooShort
jsonPath: $.transactionReference
message: Transaction reference must be between 1 and 64 characters inclusive
_links:
3ds:deviceDataInitialize:
href: $serverUrl/verifications/customers/3ds/deviceDataInitialization
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
The request contains an invalid `Content-Type` header:
description: The request contains an invalid `Content-Type` header
value:
message: Provided request contains a header with an invalid value
errorName: headerHasInvalidValue
headerName: Content-Type
_links:
3ds:deviceDataInitialize:
href: $serverUrl/verifications/customers/3ds/deviceDataInitialization
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
'502':
description: Invalid response received from upstream
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_deviceDataInitialize_502_response'
examples:
An invalid response is received from upstream:
description: An invalid response is received from upstream
value:
path: /verifications/customers/3ds/deviceDataInitialization
status: 502
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:deviceDataInitialize:
href: $serverUrl/verifications/customers/3ds/deviceDataInitialization
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
'503':
description: The requested service is unavailable
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_deviceDataInitialize_503_response'
examples:
The requested service is unavailable:
description: The requested service is unavailable
value:
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:deviceDataInitialize:
href: $serverUrl/verifications/customers/3ds/deviceDataInitialization
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
tags:
- Verifications
/verifications/customers/3ds/authentication:
post:
summary: Initiate the 3DS authentication
description: 'Authenticate your customer by submitting order and risk data.
'
operationId: authenticate
parameters:
- in: header
name: Content-Type
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
- in: header
name: Accept
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
requestBody:
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate'
examples:
card/front:
$ref: '#/components/examples/authentication-card'
card/tokenized:
$ref: '#/components/examples/authentication-token'
card/networkToken:
$ref: '#/components/examples/authentication-networktoken'
card/wallet+googlepay:
$ref: '#/components/examples/authentication-googlepay'
Minimum Recommended (web):
$ref: '#/components/examples/authentication-card-recommended-web'
Minimum Recommended (native):
$ref: '#/components/examples/authentication-card-recommended-native'
responses:
'200':
description: The authentication has been created
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
anyOf:
- $ref: '#/components/schemas/3DS_authenticate_200_response'
- $ref: '#/components/schemas/3DS_authenticate_200_response_cartes_bancaires'
- $ref: '#/components/schemas/3DS_authenticate_challenged_200_response'
- $ref: '#/components/schemas/3DS_authenticate_200_response_authentication_failed'
- $ref: '#/components/schemas/3DS_authenticate_200_response_unavailable'
- $ref: '#/components/schemas/3DS_authenticate_200_response_bypassed'
- $ref: '#/components/schemas/3DS_authenticate_200_response_authentication_outage'
examples:
authenticated:
$ref: '#/components/examples/authentication-authenticated'
authenticated (Cartes Bancaires):
$ref: '#/components/examples/authentication-authenticated-cartesbancaires'
alreadyAuthenticated:
$ref: '#/components/examples/already-authenticated'
challenged:
$ref: '#/components/examples/authentication-challenged'
authenticationFailed:
$ref: '#/components/examples/authentication-authentication-failed'
unavailable:
$ref: '#/components/examples/authentication-unavailable'
authenticationOutage:
$ref: '#/components/examples/authentication-authentication-outage'
bypassed:
$ref: '#/components/examples/authentication-bypassed'
'400':
description: The request has encountered validation errors
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate_400_response'
examples:
The request is missing a mandatory field `merchant`:
description: The request does not have a mandatory field `merchant`
value:
message: The json body provided does not match the expected schema
errorName: bodyDoesNotMatchSchema
validationErrors:
- errorName: fieldIsMissing
jsonPath: $.merchant
message: Merchant must be provided
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
The request contains an invalid `Content-Type` header:
description: The request contains an invalid `Content-Type` header
value:
message: Provided request contains a header with an invalid value
errorName: headerHasInvalidValue
headerName: Content-Type
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
The request is using an invalid HTTP method:
description: The request is using an invalid HTTP method
value:
errorName: methodNotAllowed
allowedMethods:
- POST
message: Method GET not allowed for this request
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
'502':
description: Invalid response received from upstream
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate_502_response'
examples:
An invalid response is received from upstream:
description: An invalid response is received from upstream
value:
path: /verifications/customers/3ds/authentication
status: 502
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
'503':
description: The requested service is unavailable
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate_503_response'
examples:
The requested service is unavailable:
description: The requested service is unavailable
value:
path: /verifications/customers/3ds/authentication
status: 503
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
tags:
- Verifications
/verifications/customers/3ds/verification:
post:
summary: Verify the 3DS challenge response
description: 'Verify the results of a challenged authentication.
'
operationId: verify
parameters:
- in: header
name: Content-Type
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
- in: header
name: Accept
schema:
type: string
example: application/vnd.worldpay.verifications.customers-v3.hal+json
requestBody:
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_verify'
examples:
Verification:
$ref: '#/components/examples/verification-request'
responses:
'200':
description: The challenge was successful - obtain the authentication data for onward use
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
anyOf:
- $ref: '#/components/schemas/3DS_verify_200_response'
- $ref: '#/components/schemas/3DS_verify_200_response_failed'
- $ref: '#/components/schemas/3DS_verify_200_response_unavailable'
- $ref: '#/components/schemas/3DS_verify_200_response_signature_failed'
examples:
authenticated:
$ref: '#/components/examples/verification-authenticated'
authenticationFailed:
$ref: '#/components/examples/verification-authentication-failed'
unavailable:
$ref: '#/components/examples/verification-unavailable'
signatureFailed:
$ref: '#/components/examples/verification-signature-failed'
'400':
description: The request has encountered validation errors
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_verify_400_response'
examples:
The request contains invalid characters:
description: The request contains invalid characters in `transactionReference` and `merchant.entity` fields
value:
path: /verifications/customers/3ds/verification
status: 400
message: The json body provided does not match the expected schema
errorName: bodyDoesNotMatchSchema
validationErrors:
- errorName: stringFailedRegexCheck
jsonPath: $.merchant.entity
message: Entity must be alphanumeric with optional spaces
- errorName: stringFailedRegexCheck
jsonPath: $.transactionReference
message: 'Transaction reference characters must be alphanumeric or one of the following: _!@#$%()*=-.:;?[]{}~`/+'
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
The request contains an invalid `Content-Type` header:
description: The request contains an invalid `Content-Type` header
value:
path: /verifications/customers/3ds/verification
status: 400
message: Provided request contains a header with an invalid value
errorName: headerHasInvalidValue
headerName: Content-Type
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
name: 3ds
templated: true
The request is using an invalid HTTP method:
description: The request is using an invalid HTTP method
value:
message: Method GET not allowed for this request
errorName: methodNotAllowed
allowedMethods:
- POST
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
'502':
description: Invalid response received from upstream
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate_502_response'
examples:
An invalid response is received from upstream:
description: An invalid response is received from upstream
value:
path: /verifications/customers/3ds/authentication
status: 502
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
'503':
description: The requested service is unavailable
content:
application/vnd.worldpay.verifications.customers-v3.hal+json:
schema:
$ref: '#/components/schemas/3DS_authenticate_503_response'
examples:
The requested service is unavailable:
description: The requested service is unavailable
value:
path: /verifications/customers/3ds/authentication
status: 503
message: Service Unavailable
errorName: serviceUnavailable
_links:
3ds:authenticate:
href: $serverUrl/verifications/customers/3ds/authentication
3ds:verify:
href: $serverUrl/verifications/customers/3ds/verification
curies:
- href: $serverUrl/rels/verifications/customers/3ds/{rel}
templated: true
name: 3ds
tags:
- Verifications
components:
schemas:
3DS_verify_200_response_unavailable:
title: unavailable
type: object
properties:
outcome:
enum:
- authenticated
- authenticationFailed
- unavailable
- signatureFailed
type: string
description: Outcome of the previously posted authentication request.
transactionReference:
maxLength: 64
minLength: 1
type: string
description: A unique reference for authentication that was passed in the request.
status:
$ref: '#/components/schemas/status'
_links:
$ref: '#/components/schemas/links'
3DS_authenticate:
required:
- transactionReference
- merchant
- instruction
- deviceData
- challenge
type: object
properties:
transactionReference:
$ref: '#/components/schemas/transactionReference'
merchant:
required:
- entity
type: object
description: An object that contains information about the merchant and API level configuration.
properties:
entity:
maxLength: 64
minLength: 1
pattern: ^[A-Za-z0-9 ]*$
type: string
description: Used to route the request in Access Worldpay, created as part of on-boarding.
overrideName:
type: string
maxLength: 25
minLength: 1
pattern: ^[^><&'\"]*
description: Used to override the merchant name that's both submitted to issuers as well as displayed to the customer in the authentication process. PayFac merchants should submit the name of their submerchant.
acquirerId:
type: string
maxLength: 20
minLength: 1
example: '01234567'
pattern: ^[0-9]*$
description: Instructs the issuer that the following authorization will be completed with an external acquirer
instruction:
required:
- value
- paymentInstrument
type: object
description: The object that contains all the payment information related to the authentication request.
properties:
value:
required:
- amount
- currency
type: object
description: An object that contains information about the value of the authentication.
properties:
amount:
maximum: 99999999999
minimum: 0
type: integer
description: The authentication amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). The authentication amount should be equal to the authorization amount. We recommend you delay authentication until the amount is known, or ensure it's greater than the total transaction amount.
currency:
maxLength: 3
minLength: 3
pattern: ^[A-Z]{3}$
type: string
description: The three digit currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes)
paymentInstrument:
oneOf:
- $ref: '#/components/schemas/card_front'
- $ref: '#/components/schemas/card_tokenized'
- $ref: '#/components/schemas/card_networktoken'
- $ref: '#/components/schemas/card_wallet_googlepay'
description: An object that contains the card details or token location.
discriminator:
mapping:
card/front: '#/components/schemas/card_front'
card/tokenized: '#/components/schemas/card_tokenized'
card/networkToken: '#/components/schemas/card_networktoken'
card/wallet+googlepay: '#/components/schemas/card_wallet_googlepay'
propertyName: type
deviceData:
required:
- acceptHeader
- userAgentHeader
type: object
description: Object containing device data information.
properties:
acceptHeader:
maxLength: 2048
minLength: 1
type: string
description: Used by the issuer to check if the customer's browser is compatible with the issuer challenge display.
userAgentHeader:
maxLength: 2048
minLength: 1
type: string
description: Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321 E.g. `Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)`.
collectionReference:
maxLength: 200
type: string
description: For web this is the `sessionId` in the post message response from the Device Data Collection form. For iOS/Android SDK this is the `consumerSessionId` returned as part of SDK initialization. It is __highly recommended__ you provide this, not doing so will increase issuer challenges.
browserLanguage:
maxLength: 8
minLength: 1
type: string
description: ' Your customer''s browser language that can be used by the issuer in risk analysis. Must conform to the language tags defined by IETF. E.g. en-GB, fr-FR. '
ipAddress:
type: string
description: " A unique identifier for your customer's physical location that\n can be used by the issuer in risk analysis. Must be in IPv4 or IPv6 format.\nE.g. 192.0.0.0. "
browserJavaEnabled:
type: boolean
description: Defines whether Java is enabled on your customers browser.
browserColorDepth:
type: string
description: The color depth of your customers browser
enum:
- '1'
- '4'
- '8'
- '15'
- '16'
- '24'
- '32'
- '48'
browserScreenHeight:
type: integer
pattern: ^[0-9]{1,6}$
description: Defines the pixel height of the customers browser.
browserScreenWidth:
type: integer
pattern: ^[0-9]{1,6}$
description: Defines the pixel width of the customers browser.
timeZone:
pattern: ^[+-]?\d{1,4}$
type: string
description: " Time zone offset in minutes between UTC and your customer's browser local time. \nExample time zone offset values in minutes: \nIf UTC -5 hours: \n`300` \n`+300` \nIf UTC +5 hours: \n`-300` \n "
browserJavascriptEnabled:
type: boolean
description: Defines whether Javascript is enabled on your customers browser.
challenge:
required:
- returnUrl
type: object
description: An object that contains challenge related information.
properties:
returnUrl:
minLength: 1
type: string
format: uri
description: URL the issuer will use to notify the challenge has been completed.
preference:
enum:
- noPreference
- noChallengeRequested
- challengeRequested
- challengeMandated
- noChallengeRequestedTRAPerformed
type: string
description: Preference regarding issuer displaying challenge to the customer. The interpretation of this field varies from issuer to issuer, so we cannot guarantee any particular behavior on their part as a result of you setting this field.
x-enumDescriptions:
noPreference: Default (decision to challenge owned by issuer)
noChallengeRequested: Prefer no challenge performed
challengeRequested: Prefer challenge is performed
challengeMandated: Local or regional mandates meaning a challenge must be performed. For SCA mandated countries you should use `challengeMandated` in the authentication request as part of the first CIT payment in an MIT series
noChallengeRequestedTRAPerformed: Prefer no challenge performed due to an exemption to SCA. Only use this when Transaction Risk Analysis (TRA) has been performed using an approved third party vendor and an SCA exemption has been recommended for the authentication.
windowSize:
default: 390x400
enum:
- 390x400
- 250x400
- 500x600
- 600x400
- fullPage
type: string
description: Specify the challenge window size (width x height)
# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-verifications-api-openapi.yml