# Card Verification / Name Inquiry

Verify your customer's card. Perform a name inquiry to verify the name of the cardholder.

Endpoint: POST /cardVerifications
Version: 6
Security: BasicAuth

## Security:

  - `BasicAuth` (unknown)
    http basic

## Header parameters:

  - `Accept` (string, required)

  - `Content-Type` (string, required)

## Request body:

  - `application/vnd.worldpay.cardverifications-v6+json` (unknown)
    Card verification or Cardholder Name Inquiry.

## Request fields (application/vnd.worldpay.cardverifications-v6+json):

  - `type` (string, required)
    Enum: "cardVerification"

  - `merchant` (object, required)
    Information about the merchant.

  - `merchant.entity` (string, required)
    This should map to a profile from the Onboarding Domain. For more information contact your Relationship Manager or Worldpay Implementation Manager.

  - `merchant.mcc` (string)
    A Merchant Category Code (MCC) can be applied to an individual request. You can only supply `mcc`, if we have enabled the dynamic MCC feature during boarding. If enabled but not provided, `merchant.mcc` defaults to a configured value. For more information contact your Relationship Manager or Worldpay Implementation Manager.
    Example: 6012

  - `merchant.paymentFacilitator` (object)
    An object containing your payment facilitator information.

This parameter is only required for verification if you are a payment facilitator.

  - `merchant.paymentFacilitator.schemeId` (string, required)
    Your payment facilitator ID received from Mastercard, Visa and Amex.
    Example: 12345678901

  - `merchant.paymentFacilitator.independentSalesOrganizationId` (string)
    Independent Sales Organization (ISO) ID provided by Mastercard.
    Example: 12345678901

  - `merchant.paymentFacilitator.subMerchant` (object, required)
    Your sub-merchant's details

  - `merchant.paymentFacilitator.subMerchant.reference` (string)
    Unique merchant reference
    Example: 123456789012345

  - `merchant.paymentFacilitator.subMerchant.name` (string, required)
    The name of your subMerchant's company
    Example: Stonewall Inn

  - `merchant.paymentFacilitator.subMerchant.address` (object, required)

  - `merchant.paymentFacilitator.subMerchant.address.street` (string, required)
    Street name of your subMerchant's company
    Example: 53 Christopher Street

  - `merchant.paymentFacilitator.subMerchant.address.state` (string)
    State of your subMerchant's company
    Example: NY

  - `merchant.paymentFacilitator.subMerchant.address.city` (string, required)
    City of your subMerchant's company
    Example: New York City

  - `merchant.paymentFacilitator.subMerchant.address.countryCode` (string, required)
    The alpha-2 ISO-3166 country code of the billing address
    Example: GB

  - `merchant.paymentFacilitator.subMerchant.address.postalCode` (string, required)
    Post code/Zip code of your subMerchant's company
    Example: 10014

  - `merchant.paymentFacilitator.subMerchant.taxReference` (string)
    Tax Reference of your subMerchant's company
    Example: 987-65-4321

  - `merchant.paymentFacilitator.subMerchant.phoneNumber` (string)
    Phonenumber of your subMerchant's company
    Example: 987-65-4321

  - `merchant.paymentFacilitator.subMerchant.email` (string)
    Email address of your subMerchant's company
    Example: email@example.com

  - `merchant.paymentFacilitator.subMerchant.url` (string)
    URL of submerchant's company

  - `transactionReference` (string, required)
    A unique reference generated by you. It is used to identify a payment throughout its lifecycle.
64 characters max. We recommend your `transactionReference` contains between 9-20 characters for ease of onward
processing.
    Example: Memory265-13/08/1876

  - `instruction` (object, required)

  - `instruction.consumerBillPayment` (boolean)
    If you are registered with Visa as a Consumer Bill Payment Service provider, you must set this to `true` for any verifications made for the purpose of paying consumer bills in the future.
    Example: true

  - `instruction.nominalRetry` (boolean)
    Set this field to `true` to automatically retry a failed zero value verification with a nominal value authorisation amount. This is only possible if **0** or **missing** "value.amount" is submitted with the verification request. We automatically cancel the applied nominal authorization amount before your customer is charged.
    Example: true

  - `instruction.value` (object, required)
    Currency and value of transaction. If value is nominal, retry is requested.

  - `instruction.value.currency` (string, required)
    3-letter [ISO-4217 currency code](/products/reference/supported-countries-currencies#iso-currency-codes).
    Example: GBP

  - `instruction.value.amount` (integer)
    "Implied decimal. For example, 250 GBP = £2.50.
We cancel the applied nominal authorization amount before your customer is charged."
    Example: 250

  - `instruction.narrative` (object)
    Text to appear on the customer's billing statement. Sometimes referred to as a billing descriptor.  If this isn't set, the value from your merchant profile is used.

  - `instruction.narrative.line1` (string, required)
    Example: MindPalace

  - `instruction.narrative.line2` (string)
    Example: Memory

  - `instruction.paymentInstrument` (any, required)
    An object that contains your customer's payment details.

  - `instruction.paymentInstrument.type` (string, required)
    Example: card/plain

  - `instruction.paymentInstrument.cardHolderName` (string)
    The name as shown on the card.
    Example: Sherlock Holmes

  - `instruction.paymentInstrument.expiryDate` (object, required)
    The expiry date of the card

  - `instruction.paymentInstrument.expiryDate.year` (integer, required)
    Four digit expiry year
    Example: 2025

  - `instruction.paymentInstrument.expiryDate.month` (integer, required)
    Expiry month
    Example: 8

  - `instruction.paymentInstrument.cardNumber` (string, required)
    An element that contains your customer's payment card number.
    Example: 4444333322221111

  - `instruction.paymentInstrument.billingAddress` (object)
    An object containing the billing address information. If included you must send at least: [address1, city, countryCode, postalCode]

  - `instruction.paymentInstrument.billingAddress.address1` (string, required)
    Address line1 of billing address.
    Example: 221B Baker Street

  - `instruction.paymentInstrument.billingAddress.address2` (string)
    Address line2 of billing address.
    Example: Marylebone

  - `instruction.paymentInstrument.billingAddress.address3` (string)
    Address line3 of billing address.
    Example: Westminster

  - `instruction.paymentInstrument.billingAddress.postalCode` (string, required)
    Recipient's postal code.
    Example: NW1 6XE

  - `instruction.paymentInstrument.billingAddress.city` (string, required)
    City of billing address
    Example: London

  - `instruction.paymentInstrument.billingAddress.state` (string)
    Region, state, or province of billing address
    Example: GB

  - `instruction.paymentInstrument.billingAddress.countryCode` (string, required)
    The alpha-2 ISO-3166 country code of the billing address.
    Example: GB

  - `instruction.paymentInstrument.cvc` (string)
    CVC is a unique set of 3 or 4 numbers on the back of your customer's card. Including the CVC in your request increases the chances of the verification request outcome being verified. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.
    Example: 101

  - `instruction.paymentInstrument.billingAddress` (object)
    An object containing the billing address information. If provided, it will override the billing address information from the actual token.
If included, you must send at least: [address1, city, countryCode, postalCode]

  - `instruction.paymentInstrument.billingAddress.address1` (string, required)
    Address line 1 of billing address.
    Example: 221B Baker Street

  - `instruction.paymentInstrument.billingAddress.address2` (string)
    Address line 2 of billing address.
    Example: Marylebone

  - `instruction.paymentInstrument.billingAddress.address3` (string)
    Address line 3 of billing address.
    Example: Westminster

  - `instruction.paymentInstrument.billingAddress.city` (string, required)
    City of billing address.
    Example: London

  - `instruction.paymentInstrument.billingAddress.state` (string)
    Region, state, or province of billing address.
    Example: Greater London

  - `instruction.paymentInstrument.href` (string, required)
    An element that contains your token.
    Example: https://tokens/token

  - `instruction.paymentInstrument.tokenId` (string, required)
    An identifier that contains your token. Consists of numbers and capital letters excluding I and O. Cannot be a card number.
    Example: ABCDEFGH01234567

  - `instruction.paymentInstrument.namespace` (string)
    Namespace associated with the token. Must not start with '_' and must conform to ISO-8859-1 (Latin-1) without spaces, & or <.
    Example: SHOPPER_ID_1234567890

  - `instruction.paymentInstrument.tokenNumber` (string, required)
    The token number issued by the network

  - `instruction.paymentInstrument.cardHolderName` (string)

  - `instruction.paymentInstrument.tokenNumber` (string, required)
    The token number issued by Apple Pay

  - `instruction.paymentInstrument.tokenNumber` (string, required)
    The token number issued by Google Pay.

  - `instruction.paymentInstrument.billingAddress` (object)
    An object containing the billing address information. If included you must send at least: [address1, city, countryCode, postalCode].

  - `instruction.paymentInstrument.tokenNumber` (string, required)
    The token number issued by Samsung Pay.

  - `instruction.customerAgreement` (object)
    Contains specific customer agreements for the transaction.

  - `instruction.customerAgreement.type` (string, required)
    The processing arrangement agreed with your customer.
    Enum: "cardOnFile"

  - `instruction.customerAgreement.storedCardUsage` (string)
    If this optional field is not provided, `first` will be used. Set to `first` for original verification or `subsequent` to use a previously stored card.
    Enum: "first", "subsequent"

  - `instruction.customerAgreement.installmentType` (string)
    Defines the type of installments service. Only merchant is available for card verification.
    Enum: "merchant"

  - `instruction.fundsTransfer` (object)
    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).

  - `instruction.fundsTransfer.type` (string, required)
    Specify the type of the funds transfer.
    Enum: "accountToAccount", "cash", "disbursement", "personToPerson", "purchase", "topUp", "transfer", "walletLoad"

  - `instruction.fundsTransfer.purpose` (string)
    Specify the purpose of the funds transfer.
    Enum: "businessToBusiness", "creditCardRepayment", "crowdLending", "crypto", "debitCard", "education", "emergency", "familySupport", "gaming", "gift", "giftcard", "highRiskSecurities", "liquidAssets", "medical", "payroll", "prepaidCard", "salary", "savings", "travel", "other"

  - `channel` (string)
    The payment channel indicates the interaction of the cardholder with the merchant.
Supply a value of `moto` to process an authorization as a Mail Order or Telephone Order transaction.
When channel is not provided, the authorization will be processed as ecommerce `ecom` by default.
**NOTE:** 3DS `authentication` data cannot be supplied for MOTO payments.
    Enum: "moto", "ecom"

  - `authentication` (object)
    * **threeDS** can apply OPTIONALLY to any paymentInstrument other than Apple Pay
* **networkToken** only applies to payment instruments: **card/networkToken** and **card/networkToken+applepay**
**networkToken** should be mandatory for these instruments
* For paymentInstrument **card/networkToken** then the **threeDS** object can optionally be supplied along with the networkToken one

  - `authentication.networkToken` (object)

  - `authentication.networkToken.cryptogram` (string, required)
    The base64-encoded dynamic cryptogram for the transaction
    Example: MAAAAAAAAAAAAAAAA=

  - `authentication.networkToken.eci` (string)
    The electronic commerce indicator issued by the tokenization service.
    Example: 06

  - `authentication.threeDS` (object)

  - `authentication.threeDS.eci` (string, required)
    Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS verification.

02 or 05 - Fully Authenticated Transaction

01 or 06 - Attempted Authentication Transaction

00 or 07 - Non 3-D Secure Transaction

Mastercard - 02, 01, 00

Visa - 05, 06, 07

Amex - 05, 06, 07

JCB - 05, 06, 07

Diners - 05, 06, 07
    Example: 06

  - `authentication.threeDS.authenticationValue` (string, required)
    A cryptographic value that provides evidence of the outcome of a 3DS verification.

Visa - Cardholder Authentication Verification Value (CAVV)

Mastercard - Universal Cardholder Authentication Field (UCAF)

For version 3DS2 authenticationValue is required if authentication.eci value is 01, 02, 
05 or 06. It must be base64-encoded.
    Example: AAIBBmISWQAAAAB3JxJZkAAAAAA=

  - `authentication.threeDS.transactionId` (string, required)
    Required, if authentication.eci value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer. 

 For version 3DS2: transactionId must be a UUID and 36 characters in length.
    Example: a09b446d-5c0d-4003-9c99-21fb73d75999

  - `authentication.threeDS.version` (string, required)
    The version of 3DS used to process the transaction.

Only 3DS2 version 2.1.0 or more recent
    Example: 2.2.0

  - `authentication.threeDS.cryptogramAlgorithm` (string)
    The 3DS cryptogram algorithm used.
    Example: 2

  - `authentication.threeDS.challengePreference` (string)
    Enum: "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated"

  - `authentication.threeDS.authenticationFlow` (string)
    Enum: "challenge", "frictionless", "frictionlessDelegated"

  - `authentication.threeDS.statusReason` (string)
    Example: 00

  - `authentication.threeDS.cancellationIndicator` (string)
    Example: 00

  - `authentication.threeDS.networkScore` (string)
    Example: 00

  - `authentication.threeDS.brand` (string)
    Currently reserved for Cartes Bancaires. Only "carteBancaires" is accepted in this optional field.
    Enum: "cartesBancaires"

  - `recipient` (object)
    The details of the recipient of the payment.

We highly recommend you supply this, if your MCC is 6012 or 6051. Sending this field ensures you remain PSD2 compliant
and avoid potential acquirer refusals.

  - `recipient.accountReference` (string)
    Partial account number.
    Example: azAZ0123

  - `recipient.lastName` (string)
    surname
    Example: Holmes

  - `recipient.address` (object)

  - `recipient.dateOfBirth` (object)

  - `recipient.dateOfBirth.day` (number, required)
    Recipient's day of birth
    Example: 1

  - `recipient.dateOfBirth.month` (number, required)
    Recipient's month of birth
    Example: 2

  - `recipient.dateOfBirth.year` (number, required)
    Recipient's year of birth
    Example: 2000

## Request examples:

  - `Successful card verification for payfac and card on file` (unknown)

  - `Successful card verification with a token` (unknown)

  - `Successful card verification with a token, 3DS data and customer agreement` (unknown)

  - `Successful card verification with a network token` (unknown)

  - `Successful card verification for one-time and nominal retry` (unknown)

  - `Successful card verification for one-time with no nominal retry` (unknown)

  - `Successful card verification with 3DS2 values` (unknown)

  - `Successful card verification with optional fund transfer values` (unknown)

  - `Successful card verification with Apple Pay decrypted` (unknown)

  - `Successful card verification with Google Pay decrypted` (unknown)

  - `Successful card verification with Samsung Pay decrypted` (unknown)

  - `Successful cardholder name inquiry with card details` (unknown)

  - `Successful cardholder name inquiry with a token` (unknown)

## Response 200:

  - `200` (unknown)
    Successful cardholder name inquiry outcome.

## Response 200 fields (application/vnd.worldpay.cardverifications-v6+json):

  - `outcome` (string)
    Result of the Card Verification
    Enum: "verified", "not verified"

  - `nameInquiry` (string)
    Result of the Cardholder Name Inquiry
    Enum: "matched", "partialMatched", "notMatched", "notChecked", "notSupported"

  - `riskFactors` (array)
    List of risks involved in this verification.
    Example: [{"type":"cvc","risk":"notSupplied"},{"type":"avs","detail":"postcode","risk":"notSupplied"},{"type":"avs","detail":"address","risk":"notSupplied"}]

  - `riskFactors.type` (string)
    Enum: "cvc", "avs", "nameInquiry"

  - `riskFactors.risk` (string)
    Enum: "notChecked", "notMatched", "notSupplied", "partialMatched", "notSupported"

  - `riskFactors.detail` (string)
    Enum: "postcode", "address", "firstName", "middleName", "lastName"

  - `refusalCode` (string)
    The [refusal response code](/products/reference/refusal-response) from the acquirer
    Example: 6

  - `refusalDescription` (string)
    The [description of the 'refusalCode'](/products/reference/refusal-response)
    Example: Try another card

## Response 200 headers (application/vnd.worldpay.cardverifications-v6+json):

  - `WP-CorrelationId` (string)
    This will be echoed from the request header of the same name

## Response 201:

  - `201` (unknown)
    Successful card verification outcome.

## Response 201 fields (application/vnd.worldpay.cardverifications-v6+json):

  - `outcome` (string, required)
    Result of the Card Verification
    Enum: "verified", "not verified"

  - `scheme` (object)
    Card issuer's scheme (not all issuers return this)

  - `scheme.reference` (string, required)
    Example: abc123

  - `checkedAt` (string, required)
    Example: 2024-03-26T19:38:29.543195Z

  - `riskFactors` (array)
    List of risks involved in this verification.
    Example: [{"type":"cvc","risk":"notSupplied"},{"type":"avs","detail":"postcode","risk":"notSupplied"},{"type":"avs","detail":"address","risk":"notSupplied"}]

  - `riskFactors.type` (string)
    Enum: "cvc", "avs", "nameInquiry"

  - `riskFactors.risk` (string)
    Enum: "notChecked", "notMatched", "notSupplied", "partialMatched", "notSupported"

  - `riskFactors.detail` (string)
    Enum: "postcode", "address", "firstName", "middleName", "lastName"

  - `paymentInstrument` (object)

  - `paymentInstrument.type` (string, required)
    Enum: "card/plain+masked", "card/network+masked"

  - `paymentInstrument.lastFour` (string)
    The last 4 digits from the card number
    Example: 0001

  - `paymentInstrument.cardBin` (string)
    A bank identification number is the first four to six numbers that appear on payment cards.
    Example: 654321

  - `paymentInstrument.cardBrand` (string)
    The card scheme, e.g. visa or mastercard.
    Example: visa

  - `paymentInstrument.fundingType` (string)
    Enum: "debit", "credit", "chargeCard", "prepaid", "deferredDebit"

  - `paymentInstrument.category` (string)
    Enum: "consumer", "commercial"

  - `paymentInstrument.paymentAccountReference` (string)
    The unique reference associated with the card PAN.
    Example: 321ABC

  - `paymentInstrument.countryCode` (string)
    The alpha-2 ISO-3166 country code of the card.
    Example: GB

  - `paymentInstrument.issuerName` (string)

  - `paymentInstrument.expiryDate` (object)
    The expiry date of the card

  - `paymentInstrument.expiryDate.year` (integer, required)
    Four digit expiry year
    Example: 2025

  - `paymentInstrument.expiryDate.month` (integer, required)
    Expiry month
    Example: 8

  - `_links` (object)
    Example: {"cardVerifications:verification":{"href":"https://try.access.worldpay-bsh.securedataplatform.co.uk/cardVerifications/linkData"}}

  - `refusalCode` (string)
    The [refusal response code](/products/reference/refusal-response) from the acquirer
    Example: 6

  - `refusalDescription` (string)
    The [description of the 'refusalCode'](/products/reference/refusal-response)
    Example: Try another card

  - `advice` (object)
    The [MAC (Merchant Advice Code)](/products/reference/refusal-response#refusal-advice-codes) returned by Mastercard

  - `advice.code` (string, required)
    Example: 02

## Response 201 headers (application/vnd.worldpay.cardverifications-v6+json):

  - `WP-CorrelationId` (string)
    This will be echoed from the request header of the same name

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "internalErrorOccurred", "headerIsMissing", "headerHasInvalidValue", "bodyIsEmpty", "bodyIsNotJson", "bodyDoesNotMatchSchema"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: A JSON body matching the expected schema must be provided.

  - `validationErrors` (array)
    If there were field validation errors, they will be collected in this array

  - `validationErrors.errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "fieldIsMissing", "fieldMustBeString", "fieldMustBeNumber", "fieldMustBeInteger", "fieldMustBeBoolean", "fieldMustBeObject", "fieldMustBeArray", "fieldIsNull", "fieldIsEmpty", "fieldHasInvalidValue", "fieldIsNotAllowed", "numberIsTooSmall", "integerIsTooLarge", "stringIsTooShort", "stringIsTooLong", "stringFailedRegexCheck", "panFailedLuhnCheck", "dateHasInvalidFormat"

  - `validationErrors.message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: Field at path is not allowed.

  - `validationErrors.jsonPath` (string)
    This field represents the JSON path of the element within the request body associated with the error.
    Example: $.transactionRef

  - `headerName` (string)
    If the header is missing or does not contain an expected value, this field will be populated with the incorrect header name.
    Example: Content-Type

## Response 400 headers (application/json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 401:

  - `401` (unknown)
    Client is not authorized due to missing or invalid Authorization header.

## Response 401 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Example: accessDenied

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: Access to the requested resource has been denied

## Response 401 headers (application/json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 403:

  - `403` (unknown)
    Boarding issue - unable to process requested merchant

## Response 403 fields (application/vnd.worldpay.cardVerifications-v6+json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "resourceNotFound"

  - `message` (string, required)
    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.

## Response 403 headers (application/vnd.worldpay.cardVerifications-v6+json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 404:

  - `404` (unknown)
    Not Found - unable to locate requested record

## Response 404 fields (application/vnd.worldpay.cardVerifications-v6+json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "resourceNotFound"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: Unable to verify the historic outcome from the data provided

## Response 404 headers (application/vnd.worldpay.cardVerifications-v6+json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 415:

  - `415` (unknown)
    Invalid content-type HTTP header

## Response 415 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Example: headerHasInvalidValue

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: A valid header must be provided.

  - `headerName` (string)
    If the header is missing or does not contain an expected value, this field will be populated with the incorrect header name.
    Example: Content-Type

## Response 415 headers (application/json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 500:

  - `500` (unknown)
    An error occurred processing the request on our side.

## Response 500 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "internalServerError"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*
    Example: An internal server error occurred

## Response 500 headers (application/json):

  - `WP-CorrelationId` (string)
    Generated identifier for the request and response. When contacting support please include this.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 400 examples:

  - `Validation Error` (unknown)

  - `Header Error` (unknown)