New API Version | Last Updated: 21 November 2024 | Change Log

Verify a customer's account

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 received in your query the verifications root resource request.

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 received in your query the verifications root resource request to become Cardholder Initiated Transaction (CIT) compliant.

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

Verification request body:

{
    "currency": "GBP",
    "merchant": {
        "entity": "default"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cvc": "321",
        "cardHolderName": "John Appleseed",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "verificationAddress": {
            "address1": "Worldpay",
            "countryCode": "GB",
            "postalCode": "CB4 0WE",
            "city": "Cambridge"
        }
    }
}

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.
`currency`	✅	The 3 digit currency code. See list of supported currencies.
`paymentInstrument.cardHolderName`	✅	An object that contains your customer's name.
`paymentInstrument.cardNumber`	✅	An object that contains your customer's payment card number.
`paymentInstrument.type`	✅	An object that contains your customer's payment type, it must be one of the payment types that is accepted such as card/plain.
`paymentInstrument.verificationAddress`	❌	An object containing the verification address information. If included you must send at least: `city` `countryCode` `postalCode`
`paymentInstrument.cardExpiryDate`	✅	An object that contains your customer's payment card expiry date.
`paymentInstrument.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.entity`	✅	Direct your verification to assist with billing, reporting and reconciliation. This is mandatory for verifications. 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 your 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

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

Action Link (resources)	Description
`verifications:verification`	The link to the outcome of your verification request.
`payments:recurringAuthorize`	A subsequent payment in a recurring agreement. This resource is only returned as a result of a successful `verifications:cardOnFile` or `payments:migrateRecurringAuthorize` request.
`payments:cardOnFileAuthorize`	A subsequent payment in a card on file agreement. This resource is only returned as a result of a successful `verifications:cardOnFile` or `payments:migrateCardOnFileAuthorize` request.

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 historic verification.

outcome:

verified
not verified

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