Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Card Verification (6)

Determine the validity of the account to maximize authorization rates.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License Worldpay
Languages
Servers
Testing (Try)
https://try.access.worldpay.com/
Live
https://access.worldpay.com/

Card Verification / Name Inquiry

Request

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

Headers
Acceptstringrequired
Example:

application/vnd.worldpay.cardVerifications-v6+json

Content-Typestringrequired
Example:

application/vnd.worldpay.cardVerifications-v6+json

Bodyapplication/vnd.worldpay.verifications.accounts-v6+jsonrequired

Card verification or Cardholder Name Inquiry.

One of:
typestringrequired
Value"cardVerification"
merchantobjectrequired

Information about the merchant.

entitystringrequired

This should map to a profile from the Onboarding Domain. For more information contact your Relationship Manager or Implementation Manager.

mccstring

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

Example:

6012

paymentFacilitatorobject

An object containing your payment facilitator information.

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

schemeIdstringrequired

Your payment facilitator ID received from Mastercard, Visa and Amex.

Example:

"12345678901"

independentSalesOrganizationIdstring

Independent Sales Organization (ISO) ID provided by Mastercard.

Example:

"12345678901"

subMerchantobjectrequired

Your sub-merchant's details

transactionReferencestring^[A-Za-z0-9\-_\/!@#$%\(\)*=.:;?[\]{}~+]{1,64}...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"

instructionobjectrequired
consumerBillPaymentboolean

If you are registered with Visa as a Consumer Bill Payment Service (CBPS), you must set this to true for any payments associated with the CBPS.

Example:

true

nominalRetryboolean

Set this field to true to automatically retry a failed verification with a nominal amount. This only is in effect if no "value.amount" is submitted with the verification request.

Example:

true

valueobjectrequired

Currency and value of transaction. If value is nominal, retry is requested.

currencystring^[A-Z]{3}$required
Example:

"GBP"

amountinteger

Implied decimal. For example, 250 GBP = £2.50

Example:

250

narrativeobject

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.

line1string^[A-Za-z0-9-,.'\s]{3,24}$required
Example:

"MindPalace"

line2string^[A-Za-z0-9-,.'\s]{3,24}$
Example:

"Memory"

paymentInstrumentcard/plain (object) or card/token (object) or card/networkToken (object) or card/networkToken+applepay (object)required

An object that contains your customer's payment details.

One of:

An object that contains your customer's payment details.

typestringrequired
Example:

"card/plain"

cardHolderNamestring

The name as shown on the card.

Example:

"Sherlock Holmes"

expiryDateobjectrequired

The expiry date of the card

cardNumberstring^\d{12,19}$required

An element that contains your customer's payment card number.

Example:

"4444333322221111"

billingAddressobject

An object containing the billing address information. Applicable for paymentInstrument type as card/plain only. If included you must send at least: [address1, city, countryCode, postalCode]

cvcstring^\d{3,4}$

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"

customerAgreementcardOnFile (object) or subscription (object) or installment (object) or unscheduled (object)

Contains specific customer agreements for the transaction.

One of:

Contains specific customer agreements for the transaction.

typestringrequired

The processing arrangement agreed with your customer.

Value"cardOnFile"
storedCardUsagestring

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

typestringrequired

Specify the type of the funds transfer.

Enum"accountToAccount""cash""debitTopUp""disbursement""payrollDisbursement""personToPerson""prePaidTopUp""stagedDigitalWallet""transfer"
purposestring

Specify the purpose of the funds transfer.

Enum"crowdLending""crypto""education""emergency""familySupport""gift""medical""salary""savings""travel"
channelstring

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"
authenticationobject
  • 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
networkTokenobject
cryptogramstring[ 1 .. 60 ] charactersrequired

The base64-encoded dynamic cryptogram for the transaction

Example:

"MAAAAAAAAAAAAAAAA="

ecistring^\d{2}$

The electronic commerce indicator issued by the tokenization service.

Example:

"06"

threeDSobject
ecistring^\d{2}$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"

authenticationValuestring^[A-Za-z0-9+\/]{1,40}={0,2}$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="

transactionIdstringrequired

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"

versionstringrequired

The version of 3DS used to process the transaction.

Only 3DS2 version 2.1.0 or more recent

Example:

"2.2.0"

cryptogramAlgorithmstring

The 3DS cryptogram algorithm used.

Example:

2

challengePreferencestring
Enum"noPreference""noChallengeRequested""challengeRequested""challengeMandated"
Example:

"noPreference"

authenticationFlowstring
Enum"challenge""frictionless""frictionlessDelegated"
Example:

"challenge"

statusReasonstring^[0-9]{2}$
Example:

"00"

cancellationIndicatorstring
Example:

"00"

networkScorestring
Example:

"00"

brandstring

Currently reserved for Cartes Bancaires. Only "carteBancaires" is accepted in this optional field.

Value"cartesBancaires"
Example:

"cartesBancaires"

recipientobject

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.

accountReferencestring

Partial account number.

Example:

"azAZ0123"

lastNamestring[ 1 .. 85 ] characters

surname

Example:

"Holmes"

addressobject
postalCodestring[ 1 .. 15 ] charactersrequired

Recipient's postal code.

Example:

"NW1 6XE"

dateOfBirthobject
daynumberrequired

Recipient's day of birth

Example:

1

monthnumberrequired

Recipient's month of birth

Example:

2

yearnumberrequired

Recipient's year of birth

Example:

2000

application/vnd.worldpay.verifications.accounts-v6+json
{
  "type": "cardVerification",
  "merchant": {
    "entity": "default",
    "mcc": "6012",
    "paymentFacilitator": {
      "schemeId": "12345678901",
      "independentSalesOrganizationId": "12345678901",
      "subMerchant": {
        "merchantId": "123456789012345",
        "name": "Example Shop",
        "street": "123 Street",
        "state": "CA",
        "city": "San Francisco",
        "countryCode": "826",
        "postalCode": "94101",
        "taxReference": "987-65-4321"
      }
    }
  },
  "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"
    }
  }
}

Responses

Successful cardholder name inquiry outcome.

Headers
WP-CorrelationIdstring

This will be echoed from the request header of the same name

Bodyapplication/vnd.worldpay.verifications.accounts-v6+json
One of:
outcomestring

Result of the Card Verification

Enum"verified""not verified"
nameInquirystring

Result of the Cardholder Name Inquiry

Enum"matched""partialMatched""notMatched""notChecked""notSupported"
Response
application/vnd.worldpay.verifications.accounts-v6+json
{
  "outcome": "verified",
  "nameInquiry": "matched"
}

ACH Verification

Request

Successful account verification outcome.

Headers
Acceptstringrequired
Example:

application/vnd.worldpay.achVerifications-v6+json

Content-Typestringrequired
Example:

application/vnd.worldpay.achVerifications-v6+json

Bodyapplication/vnd.worldpay.achVerifications-v6+json
merchantobjectrequired
entitystringrequired

Used to route the verification request in Access Worldpay, created as part of on-boarding.

paymentInstrumentobject
typestringrequired

The type of payment instrument, must be "bankAccountUS" for ACH.

accountTypestringrequired

Possible values: checking, savings, corporate, corporateSavings.

Enum"checking""savings""corporate""corporateSavings"
accountNumberstringrequired

Account number of direct debit account.

routingNumberstringrequired

Routing number of direct debit account.

companyNamestring

Company name if a corporate account.

billToAddressobjectrequired
transactionReferencestring
application/vnd.worldpay.achVerifications-v6+json
{
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "1234567",
  "paymentInstrument": {
    "type": "bankAccountUS",
    "accountType": "corporateSavings",
    "accountNumber": "1234567890",
    "routingNumber": "011400495",
    "companyName": "companyName",
    "billToAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "address1": "address1",
      "address2": "address2",
      "address3": "address3",
      "city": "city",
      "region": "state",
      "postalCode": "postalCode",
      "countryCode": "US",
      "telephoneNumber": "4085551212"
    }
  }
}

Responses

The account verification has been successful.

Bodyapplication/vnd.worldpay.achVerifications-v6+json
outcomestringrequired

This field indicates the status of the transaction.

Enum"verified""not verified"
descriptionstring
checkedAtstring^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{...required
Example:

"2024-03-26T19:38:29.543195Z"

Response
application/vnd.worldpay.achVerifications-v6+json
{
  "outcome": "verified",
  "checkedAt": "2021-09-27T18:02:16.475Z"
}

Query a previous Verification

Request

Querying of a successful verification.

Headers
Acceptstringrequired
Example:

application/vnd.worldpay.cardVerifications-v6+json

Content-Typestringrequired
Example:

application/vnd.worldpay.cardVerifications-v6+json

No request payload

Responses

Successful query request

Headers
WP-CorrelationIdstring

Generated identifier for the request and response. When contacting support please include this.

Example:

"4c195ce9-3dbd-4bc8-9c94-3d3393842323"

Bodyapplication/vnd.worldpay.cardVerifications-v6+json
outcomestringrequired

Result of the Card Verification

Enum"verified""not verified"
schemeobject

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

referencestringrequired
Example:

"abc123"

checkedAtstring^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{...required
Example:

"2024-03-26T19:38:29.543195Z"

refusalCodestring
Example:

"6"

refusalDescriptionstring
Example:

"Try another card"

adviceobject
codestringrequired
Example:

"02"

riskFactorsArray of objects

List of risks involved in this verification.

Example:

[{"type":"cvc","risk":"notSupplied"},{"type":"avs","detail":"postcode","risk":"notSupplied"},{"type":"avs","detail":"address","risk":"notSupplied"}]

typestring
Enum"cvc""avs""nameInquiry"
Example:

"avs"

riskstring
Enum"notChecked""notMatched""notSupplied""partialMatched""notSupported"
Example:

"notMatched"

detailstring
Enum"postcode""address""firstName""middleName""lastName"
Example:

"postcode"

paymentInstrumentobject
typestringrequired
Enum"card/plain+masked""card/network+masked"
lastFourstring^[0-9]{4}$

The last 4 digits from the card number

Example:

"0001"

cardBinstring^[0-9]{4}$|^[0-9]{6}$

A bank identification number is the first four to six numbers that appear on payment cards.

Example:

654321

brandstring

The card scheme, e.g. visa or mastercard.

Example:

"visa"

fundingTypestring
Enum"debit""credit""chargeCard""prepaid""deferredDebit"
Example:

"prepaid"

categorystring
Enum"consumer""commercial"
Example:

"commercial"

paymentAccountReferencestring

The unique reference associated with the card PAN.

Example:

"321ABC"

countryCodestring^[A-Z]{2}$

The alpha-2 ISO-3166 country code of the card.

Example:

"GB"

issuerNamestring
expiryDateobject

The expiry date of the card

yearinteger(int32)required

Four digit expiry year

Example:

2025

monthinteger(int32)required

Expiry month

Example:

8

_linksobjectrequired
Example:

{"cardVerifications:verification":{"href":"https://try.access.worldpay.com/cardVerifications/linkData"}}

Response
application/vnd.worldpay.cardVerifications-v6+json

Querying of a successful verification for oneTime

{
  "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}"
    }
  }
}