Skip to content
APIs/Card Verifications/
Query a previous verifica...

Card Verifications (6)

Determine the validity of your customer's card to maximize authorization rates.

Authentication header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to your by your Implementation Manager.

You must use the Authorization header for any request you send to our Card Verifications API.

Accept/Content-Type header for card verifications

Content-Type : application/vnd.worldpay.cardVerifications-v6+json,
Accept : application/vnd.worldpay.cardVerifications-v6+json

Accept/Content-Type header for ACH verifications (US accounts)

Content-Type : application/vnd.worldpay.achVerifications-v6+json,
Accept : application/vnd.worldpay.achVerifications-v6+json


We 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 Card Verifications API.

We 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.

DNS whitelisting

Whitelist the following URLs:

* https://try.access.worldpay.com/
* https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Test (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.

Security
BasicAuth
Headers
Acceptstringrequired
Example: application/vnd.worldpay.cardVerifications-v6+json
Content-Typestringrequired
Example: application/vnd.worldpay.cardVerifications-v6+json
Bodyapplication/vnd.worldpay.cardverifications-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.

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 provider, you must set this to true for any verifications made for the purpose of paying consumer bills in the future.

Example: true
nominalRetryboolean

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
valueobjectrequired

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

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.

paymentInstrumentobjectrequired
One of:

An object that contains your customer's payment details.

customerAgreementobject
One of:

Contains specific customer agreements for the transaction.

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

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

Responses

Successful cardholder name inquiry outcome.

Headers
WP-CorrelationIdstring

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

Bodyapplication/vnd.worldpay.cardverifications-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.cardverifications-v6+json
{
  "outcome": "verified",
  "nameInquiry": "matched"
}

ACH verification

Request

Successful account verification outcome.

Security
BasicAuth
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.

paymentInstrumentobjectrequired
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
transactionReferencestringrequired
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.

Security
BasicAuth
Path
linkDatastringrequired

Action link that's received in your request.

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

The refusal response code from the acquirer

Example: "6"
refusalDescriptionstring

The description of the 'refusalCode'

Example: "Try another card"
adviceobject

The MAC (Merchant Advice Code) returned by Mastercard

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"
cardBrandstring

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

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