Last Updated: 25 March 2024 | Change Log

Verify a customer's account

Warning

Verifications v1 will be deprecated on June 15, 2020 as it is no longer compliant with Visa/Mastercard mandates. You must integrate our latest version. Contact your Implementation Manager for further information.

Verifying an account

To verify your customer's account, you must send a verifications request to one of our supported resources.

Verifications request

You can POST your verification request to one of these resources :

`oneTime` verification

For a oneTime verification, POST your request to the verifications:oneTime action link.

POST https://try.access.worldpay.com/verifications/accounts/intelligent/oneTime

`cardOnFile` verification

cardOnFile payment are payments made by the cardholder using the payment instrument details that have already been stored.

For a cardOnFile verification, POST your request to the verifications:cardOnFile action link to become Cardholder Initiated Transaction (CIT) compliant.

POST https://try.access.worldpay.com/verifications/accounts/intelligent/cardOnFile

`recurring` verification

recurring payments are payments that follow a schedule, such as subscription or installment payments.

For a recurring verification, POST your request to the verifications:recurring action link to become Merchant Initiated Transaction (MIT) compliant.

POST https://try.access.worldpay.com/verifications/accounts/intelligent/recurring

Verification request body:

Verification request
Intelligent verification request with paymentFacilitator

{
    "currency": "GBP",
    "merchant": {
        "reference": "default"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cvc": "321",
        "cardHolderName": "John Appleseed",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "billingAddress": {
            "address1": "Worldpay",
            "address2": "1 Milton Road",
            "address3": "The Science Park",
            "postalCode": "CB4 0WE",
            "city": "Cambridge",
            "state": "Cambridgeshire",
            "countryCode": "GB"
        }
    }
}

Note

Only use the Verification request with paymentFacilitator if you are a payment facilitator.

Descriptions of your verifications request parameters:

Parameter	Required	Description
`paymentInstrument`	✅	An object that contains your customer's payment details.
`billingAddress`	❌	An object that contains the billing address information. If included you must send at least: `address1` `city` `countryCode` `postalCode`
`cvc`	❌	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.
`merchant`	✅	An object that contains information about the merchant.
`merchant.reference`	❌	Direct your verification to assist with billing, reporting and reconciliation. For more information contact your Relationship Manager or Implementation Manager.
`merchant.mcc`	❌	A Merchant Category Code(`mcc`) can be applied to an individual request. An `mcc` can only be provided, if the dynamic `mcc` feature has been enabled during boarding. If enabled but not provided, `merchant.mcc` defaults to a configured value. For more information contact your Relationship Manager or Implementation Manager.
`merchant.paymentFacilitator`	❌	An object containing payment facilitator information. If required you must send: pfId isoId subMerchant.merchantId subMerchant.postalcode subMerchant.street subMerchant.city subMerchant.countryCode This information is only required for verification if you are a payment facilitator.
`recipient`	❌	An object that contains the details of the recipient of the payment. `accountReference`: Partial account number `lastName` `dateOfBirth.day` `dateOfBirth.month` `dateOfBirth.year` `address.postalCode` 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.

Verifications response

You receive a 201 HTTP response code and the outcome of the verification in your response.

Possible outcomes:

verified
not verified

Verified (oneTime)
Not verified (oneTime)
Verified (recurring/cardOnFile)
Not verified (recurring/cardOnFile)

{
    "outcome": "verified",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

The parameter checkedAt contains a timestamp showing when the verification was performed, and the location of the verification for future access.

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.

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.

Query a historic verification

To query a historic verification, submit a query to the location returned in your initial response.

Query verifications request

GET https://try.access.worldpay.com/rels/verifications/accounts/{rel}

You can query the location that was returned in the initial response to retrieve the outcome of the initial verification. You can only get the location from the initial response.

Query verifications response

In your response is a 200 HTTP response code and the historic outcome of the verification.

outcome:

verified
not verified

Verified (oneTime)
Not verified (oneTime)
Verified (recurring/cardOnFile)
Not verified (recurring/cardOnFile)

{
    "outcome": "verified",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}