Skip to content
APIs/Card Verifications/
Verify a customer's card...

Last updated: 11 September 2025 | Change log

Verify a customer's card

Verify your customer's card or make a name inquiry.

Card Verification

Verify and validate your customer's card details to protect you against fraud.

Example request

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

application/vnd.worldpay.cardverifications-v6+json
{
  "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"
      }
    }
  }
}

Parameter descriptions

ParameterRequired?Description
type✅Defines the type of request. Use cardVerification to verify a card or nameInquiry if you want to make a name inquiry.
merchant✅An object that contains information about the merchant. See full object descriptions in our API Reference
transactionReference✅A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
instruction✅The object that contains all the payment information related to the verification request. See full object descriptions in our API Reference.
channel❌The payment channel indicates the interaction of the cardholder with you. Supply a value of moto to process an authorization as a Mail Order or Telephone Order transaction. When channel is not provided, the default is ecom One of: ecom or moto.
customerAgreement❌An object that contains specific customer agreements for the transaction. One of: cardOnFile, subscription, installment or unscheduled. See full object descriptions in our API Reference
authentication❌An object containing information about the authentication of your customer. See full object descriptions in our API Reference.
recipient❌The details of the recipient of the payment. See full object descriptions in our API Reference.
Recommendation
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.
Note

You can also find the full schema and more example requests in our API Reference.

Name inquiry

You can now make a nameInquiry for Visa cards. This allows you to check the validity of the cardholder name provided.

This is important if you make payouts so you can check that the person receiving the payout is who they say they are.

Prerequisite

In order to make a name inquiry, your account must be enabled. Please contact your Implementation Manager.

Example request

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

application/vnd.worldpay.cardverifications-v6+json
{
  "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"
    }
  }
}

Parameter descriptions

ParameterRequired?Description
type✅Defines the type of request. Use cardVerification to verify a card or nameInquiry if you want to make a name inquiry.
merchant✅An object that contains information about the merchant. See full object descriptions in our API Reference
instruction✅The object that contains all the payment information related to the verification request. See full object descriptions in our API Reference.
cardHolder✅The object that contains cardholder name information. See full object descriptions in our API Reference
lastname✅The Last name of the cardholder. Must not contain 'All spaces', 'All zeros' , ' All numeric , 'Question marks - ?'. See full object descriptions in our API Reference
firstname❌The First name of the cardholder. Must not contain 'All spaces', 'All zeros' , ' All numeric , 'Question marks - ?'. See full object descriptions in our API Reference
middlename❌The Middle name of the cardholder. Must not contain 'All spaces', 'All zeros' , ' All numeric , 'Question marks - ?'. See full object descriptions in our API Reference
Note

You can also find the full schema and more example requests in our API reference.

Test values

Test cardholder name inquiry outcomes using the values below:

Test card numbernameInquiryriskFactors
4462030000000000matchedNo riskFactors returned
4484070000000000partialMatchedA riskFactors.risk value of partialMatched is returned where riskFactors.type = nameInquiry, for the following riskFactors.detail values:
  • firstName
  • middleName
  • lastName
4917300800000000notMatchedA riskFactors.risk value of notMatched is returned where riskFactors.type = nameInquiry, for the following riskFactors.detail values:
  • firstName
  • middleName
  • lastName
4444333322221111notCheckedA riskFactors.risk value of notChecked is returned where riskFactors.type = nameInquiry, for the following riskFactors.detail values:
  • firstName
  • middleName
  • lastName

3DS

You can optionally submit 3DS parameters for card verification requests.

To get the customer authentication object you must complete an authentication request using our 3DS API.

Example request

application/vnd.worldpay.cardverifications-v6+json
{
  "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"
    }
  }
}

3DS Parameters

You can view the full details for our authentication object in our API Reference.

Apple Pay decrypted

You can optionally submit Apple Pay decrypted parameters for card verification requests.

Example request

application/vnd.worldpay.cardverifications-v6+json
{
  "type": "cardVerification",
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "Memory265-13/08/1876",
  "instruction": {
    "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"
    }
  },
  "authentication": {
    "networkToken": {
      "eci": "05",
      "cryptogram": "2.1.0"
    },
    "threeDS": {
      "eci": "05",
      "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
      "version": "2.1.0",
      "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
  }
}

Apple Pay decrypted parameter descriptions

You can view the full details for the "card/networkToken+apple" paymentInstrumentin our API Reference.

Risk factors

We recommend you supply cvc and billingAddress to increase probability of a successful verification.

Funds transfers

A funds transfer is a money movement for a reason other than for the purchase of goods or services. These are also referred to as Account Funding Transactions (AFTs).

Examples:

  • loading a wallet with funds using a card (including stored value digital wallets and crypto or trading wallets)
  • adding funds to a pre-paid card using another card
  • sending money to another person (for example as a gift)
Parameters

You must include the instruction.fundsTransfer object to correctly flag a transaction as a funds transfer.

ParameterRequired?Description
instruction.fundsTransfer❌An object containing details about the transfer and the sender and recipient of funds.
fundsTransfer.type✅Possible values:
  • accountToAccount - Move funds to another financial institution account owned by the same person
  • cash - A card is used to fund a transfer where funds are given to the recipient in cash
  • disbursement - A card is used as the source of funds for a disbursement
  • transfer - Move funds to another account owned by the same person. Eg crypto/trading
  • personToPerson - Move money to an account owned by another person
  • payrollDisbursement - Use a card to fund payroll disbursements
  • prePaidTopUp - Top up a pre-paid card
  • debitTopUp - Transfer funds from a card to a debit card account owned by the same person
fundsTransfer.purpose❌Possible values:
  • familySupport
  • travel
  • education
  • medical
  • emergency
  • savings
  • gift
  • other
  • salary
  • crowdLending
  • crypto

Code example

    "instruction": {        
        "fundsTransfer": {
            "type": "transfer",
            "purpose": "crypto",
           }
      }

Response

You receive:

  • a 200 (name inquiry) or 201 (card verification) HTTP response code
  • a verification outcome (either verified or not verified)
  • an issuer response code and description (not verified result only), and a refusalAdvice code (not verified result only and MasterCard is the only card that may return this)
  • a scheme reference for card on file only (not all issuers return this)
  • riskFactors
  • a paymentInstrument
Best practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

Note

The paymentInstrument contains the paymentInstrument.type sent in the request at minimum. If you wish to receive more card metadata this must be enabled. For more information contact your Implementation Manager.

{
    "outcome": "verified",    
    "scheme": {
        "reference": "MCCYQ2PBT0626"
    },
    "checkedAt": "2024-06-26T14:33:22.780572Z",
    "riskFactors": [
        {
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "notSupplied",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "notSupplied",
            "detail": "address",
            "type": "avs"
        }
    ],
    "paymentInstrument": {
        "type": "card/plain+masked",
        "countryCode": "GB",
        "cardBrand": "mastercard",
        "fundingType": "credit",
        "issuerName": "BANK OF SCOTLAND PLC",
        "category": "consumer"
    },
    "_links": {
        "cardVerifications:verification": {
            "href": "https://access.worldpay.com/cardVerifications/MjpHbzRkTGNDVnh1alJzN3NFdG1LSGZnPT06QUVTL0NCQy9QS0NTNVBhZGRpbmc6SktwM2Q0MkFsM2RORlV2NnhkendYTlFZcHlPMmxUeUs0TVlpY0srUmtBcVY4Sk1tRGJaaGVMQ3ZDWjZ0M2dJdDE3Vi94VHhFZHdZR0NXbFlXL1gxSmFUaEZXaHhzbWtzT0xHdlpBc2pPUGZ3eVE3bVRpZVNncVN2NTJRQ3c5QVo="
        }
    }
}

Payment instrument

We only return the paymentInstrument card metadata if you are enabled for this feature.

Best practice

If you receive an outcome of not verified it means that your customer has failed the verification. We strongly recommend that you refuse the payment made with that payment instrument.

Note

In case of any errors, you can get further information in our error reference.

Location storing

You must store the returned location information. Failing to store the location information means the outcome of the verification is lost. You are not able to query a historic verification.

The location is stored in the href of the verifications:verification action link received on your verifications response.

Best practice

We recommend you store all responses.