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

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.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 (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.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": "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.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.

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

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

Card Verification (6)

Card Verification / Name Inquiry

Request

Responses

Do you like our page?

ACH Verification

Request

Responses

Do you like our page?

Query a previous Verification

Request

Responses

Do you like our page?

Card Verification (6)

Card Verification / Name Inquiry

Request

Responses

Do you like our page?

ACH Verification

RequestExpand all

Responses

Do you like our page?

Query a previous Verification

Request

Responses

Do you like our page?

Request