Access Worldpay
/
Card Verification

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.

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

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.

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.

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.verifications.accounts-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": "826",
          "postalCode": "94101"
        },
        "taxReference": "12345",
        "phoneNumber": "0123456789",
        "email": "test@email.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.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
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
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}"
    }
  }
}