The CardVerifications API from Worldpay — 2 operation(s) for cardverifications.
openapi: 3.0.1
info:
title: 3DS 3DS actions CardVerifications 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: CardVerifications
paths:
/cardVerifications:
post:
summary: Card Verification / Name Inquiry
description: Verify your customer's card.<br> Perform a name inquiry to verify the name of the cardholder.
operationId: cardVerify
parameters:
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/contentTypeHeader'
requestBody:
description: Card verification or Cardholder Name Inquiry.
content:
application/vnd.worldpay.cardverifications-v6+json:
schema:
$ref: '#/components/schemas/type'
examples:
Successful card verification for payfac and card on file:
value:
type: cardVerification
merchant:
entity: default
mcc: '6012'
paymentFacilitator:
schemeId: '12345678901'
independentSalesOrganizationId: '12345678901'
subMerchant:
name: Merchant Plc
reference: '12345'
address:
street: 123 Street
state: CA
city: San Francisco
countryCode: US
postalCode: '94101'
taxReference: '12345'
phoneNumber: 0123456789
email: test@email.com
url: developer.worldpay.com
transactionReference: Memory265-13/08/1876
instruction:
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
customerAgreement:
type: cardOnFile
paymentInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
cardNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
cvc: '101'
Successful card verification with a token:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
consumerBillPayment: true
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/token
href: https://tokens/token
cvc: '101'
Successful card verification with a token, 3DS data and customer agreement:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
value:
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/token
href: https://access.worldpay.com/tokens/eyJrIjoxLCJkIjoiYzg4bnE5eXNvMStUV094UGdnS25KcHdpYXhaRVpYRi8wVVVvK1JvbFIvcDRteUt6Z21BN3FxdDW6DEYxeWNieSJ9
cvc: '123'
customerAgreement:
type: cardOnFile
storedCardUsage: first
authentication:
threeDS:
version: 2.2.0
authenticationValue: kADeKlfHWpHFFaRMCSPajbeBiDsa
eci: '02'
transactionId: 3re97c8b-9641-4270-aa2c-02c7abb743a9
Successful card verification with a network token:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
consumerBillPayment: true
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/networkToken
tokenNumber: '4444333322221111'
expiryDate:
month: 5
year: 2050
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
cardHolderName: John Appleseed
customerAgreement:
type: cardOnFile
storedCardUsage: first
authentication:
threeDS:
eci: '05'
version: 2.1.0
authenticationValue: MAAAAAAAAAAAAAAAAAAAAAAAAAA=
transactionId: c5b808e7-1de1-4069-a17b-f70d3b3b1645
networkToken:
cryptogram: MAAAAAAAAAAAAAAAAAAAAAAAAAB=
eci: '06'
Successful card verification for one-time and nominal retry:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
nominalRetry: true
value:
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
cardNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
Successful card verification for one-time with no nominal retry:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
value:
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
cardNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
Successful card verification with 3DS2 values:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
cardNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
cvc: '101'
authentication:
threeDS:
eci: '05'
version: 2.1.0
authenticationValue: MAAAAAAAAAAAAAAAAAAAAAAAAAA=
transactionId: c5b808e7-1de1-4069-a17b-f70d3b3b1645
cryptogramAlgorithm: '2'
challengePreference: challengeMandated
authenticationFlow: challenge
statusReason: '11'
cancellationIndicator: '01'
networkScore: '00'
brand: cartesBancaires
Successful card verification with optional fund transfer values:
value:
type: cardVerification
merchant:
entity: default
mcc: '6012'
paymentFacilitator:
schemeId: '12345678901'
independentSalesOrganizationId: '12345678901'
subMerchant:
name: Merchant Plc
reference: '12345'
address:
street: 123 Street
state: CA
city: San Francisco
countryCode: US
postalCode: '94101'
taxReference: '12345'
phoneNumber: 0123456789
email: test@email.com
url: developer.worldpay.com
transactionReference: Memory265-13/08/1876
instruction:
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
customerAgreement:
type: cardOnFile
paymentInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
cardNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
cvc: '101'
fundsTransfer:
type: personToPerson
purpose: gift
Successful card verification with Apple Pay decrypted:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1876
instruction:
consumerBillPayment: true
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/networkToken+applepay
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
tokenNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
customerAgreement:
type: cardOnFile
storedCardUsage: first
authentication:
networkToken:
cryptogram: MAAAAAAB=
eci: '06'
Successful card verification with Google Pay decrypted:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1877
instruction:
consumerBillPayment: true
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/networkToken+googlepay
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
tokenNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
customerAgreement:
type: cardOnFile
storedCardUsage: first
authentication:
networkToken:
cryptogram: MAAAAACB=
eci: '02'
Successful card verification with Samsung Pay decrypted:
value:
type: cardVerification
merchant:
entity: default
transactionReference: Memory265-13/08/1878
instruction:
consumerBillPayment: true
value:
amount: 250
currency: GBP
narrative:
line1: MindPalace
line2: Memory
paymentInstrument:
type: card/networkToken+samsungpay
cardHolderName: Sherlock Holmes
expiryDate:
month: 5
year: 2050
tokenNumber: '4444333322221111'
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: NW1 6XE
city: Cambridge
countryCode: GB
customerAgreement:
type: cardOnFile
storedCardUsage: first
authentication:
networkToken:
cryptogram: MAAACDAB=
eci: '04'
Successful cardholder name inquiry with card details:
value:
type: nameInquiry
merchant:
entity: default
instruction:
paymentInstrument:
type: card/plain
cardNumber: '4444333322221111'
expiryDate:
month: 5
year: 2035
cvc: '123'
cardHolder:
firstName: William
middleName: Sherlock Scott
lastName: Holmes
Successful cardholder name inquiry with a token:
value:
type: nameInquiry
merchant:
entity: default
instruction:
paymentInstrument:
type: card/token
href: https://tokens/token
cvc: '101'
cardHolder:
firstName: William
middleName: Sherlock Scott
lastName: Holmes
required: true
responses:
'200':
description: Successful cardholder name inquiry outcome.
headers:
WP-CorrelationId:
schema:
type: string
description: This will be echoed from the request header of the same name
content:
application/vnd.worldpay.cardverifications-v6+json:
schema:
oneOf:
- title: Matched name inquiry (verified result)
type: object
properties:
outcome:
$ref: '#/components/schemas/outcome'
nameInquiry:
$ref: '#/components/schemas/nameInquiry'
- $ref: '#/components/schemas/AccountNameInquiryResponseMatched'
- $ref: '#/components/schemas/AccountNameInquiryResponseWithRiskFactors'
- $ref: '#/components/schemas/AccountNameInquiryResponseWithOutcomeNotVerified'
- $ref: '#/components/schemas/AccountNameInquiryResponseWithOutcomeNotVerifiedWithRefusalCode'
'201':
description: Successful card verification outcome.
headers:
WP-CorrelationId:
schema:
type: string
description: This will be echoed from the request header of the same name
content:
application/vnd.worldpay.cardverifications-v6+json:
schema:
oneOf:
- title: Successful Verification
type: object
required:
- outcome
- checkedAt
properties:
outcome:
$ref: '#/components/schemas/outcome'
scheme:
$ref: '#/components/schemas/scheme'
checkedAt:
$ref: '#/components/schemas/checkedAt'
riskFactors:
$ref: '#/components/schemas/riskFactors'
paymentInstrument:
$ref: '#/components/schemas/paymentInstrumentCardDetails'
_links:
type: object
example:
cardVerifications:verification:
href: https://try.access.worldpay.com/cardVerifications/linkData
- title: Refused Verification
type: object
properties:
outcome:
$ref: '#/components/schemas/outcome'
scheme:
$ref: '#/components/schemas/scheme'
refusalCode:
$ref: '#/components/schemas/refusalCode'
refusalDescription:
$ref: '#/components/schemas/refusalDescription'
advice:
$ref: '#/components/schemas/advice'
checkedAt:
$ref: '#/components/schemas/checkedAt'
riskFactors:
$ref: '#/components/schemas/riskFactors'
paymentInstrument:
$ref: '#/components/schemas/paymentInstrumentCardDetails'
_links:
type: object
example:
cardVerifications:verification:
href: https://try.access.worldpay.com/cardVerifications/linkData
example:
outcome: not verified
refusalCode: '76'
refusalDescription: CARD BLOCKED
advice:
code: '04'
checkedAt: '2019-11-28T12:02:49.572137Z'
riskFactors:
- risk: notMatched
type: cvc
- risk: notMatched
detail: postcode
type: avs
- risk: notMatched
detail: address
type: avs
paymentInstrument:
type: card/plain+masked
issuerName: cardIssuer
cardBin: '444433'
lastFour: '1111'
brand: visa
fundingType: debit
category: consumer
paymentAccountReference: reference
countryCode: GB
expiryDate:
month: 12
year: 2029
_links:
cardVerifications:verification:
href: https://try.access.worldpay.com/cardVerifications/linkData
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
tags:
- CardVerifications
/cardVerifications/{linkData}:
get:
summary: Query a previous verification
description: Querying of a successful verification.
operationId: getCardVerificationByResourceId
parameters:
- name: linkData
in: path
description: Action link that's received in your request.
required: true
schema:
type: string
- $ref: '#/components/parameters/acceptHeader'
- $ref: '#/components/parameters/contentTypeHeader'
responses:
'200':
description: Successful query request
headers:
WP-CorrelationId:
$ref: '#/components/headers/wpCorrelationId'
content:
application/vnd.worldpay.cardVerifications-v6+json:
schema:
$ref: '#/components/schemas/response200'
examples:
Querying of a successful verification for oneTime:
description: Querying of a successful verification for oneTime
value:
outcome: verified
checkedAt: '2018-09-01T10:37:36.923Z'
riskFactors:
- risk: matched
type: cvc
- risk: matched
detail: postcode
type: avs
- risk: matched
detail: address
type: avs
paymentInstrument:
type: card/plain+masked
cardBin: '444433'
lastFour: '1111'
countryCode: GB
expiryDate:
month: 12
year: 2029
brand: visa
fundingType: debit
issuerName: cardIssuer
category: consumer
paymentAccountReference: reference
_links:
'cardVerifications: verification':
href: https://try.access.worldpay.com/cardVerifications/{resource}
Querying of a successful verification for cardOnFile:
description: Querying of a successful verification for cardOnFile
value:
outcome: verified
scheme:
reference: '00000000000000000'
checkedAt: '2018-09-01T10:37:36.923Z'
riskFactors:
- risk: matched
type: cvc
- risk: matched
detail: postcode
type: avs
- risk: matched
detail: address
type: avs
paymentInstrument:
type: card/plain+masked
cardBin: '444433'
lastFour: '1111'
countryCode: GB
expiryDate:
month: 12
year: 2029
brand: visa
fundingType: debit
issuerName: cardIssuer
category: consumer
paymentAccountReference: reference
_links:
cardVerifications:verification:
href: https://try.access.worldpay.com/cardVerifications/{resource}
Querying of a refused verification:
description: Querying of a refused verification
value:
outcome: not verified
refusalCode: '76'
refusalDescription: CARD BLOCKED
advice:
code: '04'
checkedAt: '2019-11-28T12:02:49.572137Z'
riskFactors:
- risk: notMatched
type: cvc
- risk: notMatched
detail: postcode
type: avs
- risk: notMatched
detail: address
type: avs
paymentInstrument:
type: card/plain+masked
cardBin: '444433'
lastFour: '1111'
countryCode: GB
expiryDate:
month: 12
year: 2029
brand: visa
fundingType: debit
issuerName: cardIssuer
category: consumer
paymentAccountReference: reference
_links:
'cardVerifications: verification':
href: 'https: //try.access.worldpay.com/cardVerifications/{resource}'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404get'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
tags:
- CardVerifications
components:
responses:
'500':
description: An error occurred processing the request on our side.
headers:
WP-CorrelationId:
schema:
type: string
description: Generated identifier for the request and response. When contacting support please include this.
example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
content:
application/json:
schema:
title: error500
type: object
required:
- errorName
- message
properties:
errorName:
type: string
enum:
- internalServerError
description: A machine and human readable error type for clarity and semantic understanding of the error.
example: internalServerError
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*
example: An internal server error occurred
'403':
description: Boarding issue - unable to process requested merchant
headers:
WP-CorrelationId:
schema:
type: string
description: Generated identifier for the request and response. When contacting support please include this.
example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
content:
application/vnd.worldpay.cardVerifications-v6+json:
schema:
title: error403
type: object
required:
- errorName
- message
properties:
errorName:
type: string
enum:
- resourceNotFound
description: A machine and human readable error type for clarity and semantic understanding of the error.
example: boardingError
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*
example: There has been a problem with your boarding and you cannot use this API yet, please contact support.
example:
errorName: boardingError
message: There has been a problem with your boarding and you cannot use this API yet, please contact support.
'400':
description: Bad Request
headers:
WP-CorrelationId:
schema:
type: string
description: Generated identifier for the request and response. When contacting support please include this.
example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
content:
application/json:
examples:
Validation Error:
$ref: '#/components/examples/validationError'
Header Error:
$ref: '#/components/examples/headerError'
schema:
title: error400
type: object
required:
- errorName
- message
properties:
errorName:
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-cardverifications-api-openapi.yml