Access Worldpay
/
Verify a customer's account

Last Updated: 25 March 2024 | Change Log

Verify a customer's account

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

Query the root resource

Our APIs guide you by providing you with links to the next available actions. To discover and start using our APIs you must first query the root resource.

Query the root resource request

Discover our API resources by querying the root resource. Querying the root resource returns the available resources within Access Worldpay. Use the resources to send your requests depending on which of our APIs you're integrating into.

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

Note

No request body is needed for this request.

Query the root resource response

{
  "_links": {
    "payments:authorize": {
      "href": "https://try.access.worldpay.com/payments/authorizations"
    },
    "service:payments": {
      "href": "https://try.access.worldpay.com/payments"
    },
    "service:sessions": {
      "href": "https://try.access.worldpay.com/sessions"
    },
    "service:tokens": {
      "href": "https://try.access.worldpay.com/tokens"
    },
    "service:verifications/accounts": {
      "href": "https://try.access.worldpay.com/verifications/accounts"
    },
    "service:verifications/customers/3ds": {
      "href": "https://try.access.worldpay.com/verifications/customers/3ds"
    },
    "service:verifiedTokens": {
      "href": "https://try.access.worldpay.com/verifiedTokens"
    },
    "service:fraudsight": {
      "href": "https://try.access.worldpay.com/fraudsight"
    },
    "service:exemptions": {
      "href": "https://try.access.worldpay.com/exemptions"
    },
    "service:payouts": {
      "href": "https://try.access.worldpay.com/payouts"
    },
    "service:payments/alternative/direct": {
      "href": "https://try.access.worldpay.com/payments/alternative/direct"
    },
    "service:payments/alternative/action/paypal": {
      "href": "https://try.access.worldpay.com/payments/alternative/action/paypal"
    },
    "service:payments/alternative/action/ideal": {
      "href": "https://try.access.worldpay.com/payments/alternative/action/ideal"
    },
    "service:payouts/accounts": {
      "href": "https://try.access.worldpay.com/payouts/accounts"
    },
    "service:payouts/events": {
      "href": "https://try.access.worldpay.com/payouts/events"
    },
    "service:moneyTransfers": {
      "href": "https://try.access.worldpay.com/moneyTransfers"
    },
    "service:foreignExchange": {
      "href": "https://try.access.worldpay.com/foreignExchange"
    },
    "service:accounts/statements": {
      "href": "https://try.access.worldpay.com/accounts/statements"
    },
    "service:accounts/balance": {
      "href": "https://try.access.worldpay.com/accounts/balance"
    },
    "service:accounts/transfer": {
      "href": "https://try.access.worldpay.com/accounts/transfer"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/payments/{rel}",
        "name": "payments",
        "templated": true
      }
    ]
  }
}

In the response are our available API resources. You must then query the resources to discover the specific API resources. The response contains links to your next available actions and the resources to send your request to.

Set your headers

Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.

Authorization: {your_credentials},
Content-Type : application/vnd.worldpay.verifications.accounts-v3+json,
Accept : application/vnd.worldpay.verifications.accounts-v3+json
HeaderDescription
AuthorizationThe Authorization header is used for authentication and identification of our merchants within Access Worldpay. You must use the Authorization header for any request you send to our Verifications API.
Content-TypeThe Content-Type header is required for all request sent to our Verifications API.
AcceptThe Accept header is used to identify which version of our Verifications API you are using. You must use the Accept header for any request you send to our Verifications API.

The Content-Type and Accept headers, must match.

Note

Replace {your_credentials} with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.

Query verifications root resource

Query the verifications root resource to get the resources to our verifications API.

GET https://try.access.worldpay.com/verifications/accounts

The response

Intelligent verification

With an Intelligent verification, Worldpay chooses the amount to use in the verification.

Intelligent verification request

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

oneTime intelligent 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 intelligent 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

Intelligent verification request body:

  1. Intelligent verification request
  2. Intelligent verification request with paymentFacilitator
{
    "transactionReference": "{uniqueTransactionReference}",
    "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 Intelligent verification request with paymentFacilitator if you are a payment facilitator.

Descriptions of your intelligent verification request parameters:

ParameterRequiredDescription
currency✅The 3 digit currency code.
See list of supported currencies.
transactionReference✅A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
paymentInstrument✅An object that contains your customer's payment details.
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, 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.

Dynamic verification

Our Dynamic verifications service gives you granular control over the amount that is used for verification.

Dynamic verification request

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

dynamicOneTime verification

For a dynamicOneTime verification, POST your request to the verifications:dynamicOneTime action link received in your query the verifications root resource request.

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

dynamicCardOnFile verification

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

For a dynamicCardOnFile verification, POST your request to the verifications:dynamicCardOnFile 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/dynamic/cardOnFile

Dynamic verification request body:

  1. Dynamic verification request
  2. Dynamic verification request with paymentFacilitator
{
    "transactionReference": "unique-transactionReference",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "value": {
            "currency": "GBP",
            "amount": 20
        },
        "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 Dynamic verification request with paymentFacilitator if you are a payment facilitator.

Descriptions of your Dynamic verification request parameters:

ParameterRequiredDescription
instruction✅An object that contains all the information related to the payment.
value.currency✅The 3 digit currency code.
See list of supported currencies.
value.amount✅The payment amount. This is a whole number with an exponent e.g.if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.
transactionReference✅A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
paymentInstrument✅An object that contains your customer's payment details.
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, 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

The response is the same for both an Intelligent or Dynamic verification.

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

Possible outcomes:

  • verified
  • not verified
  1. Verified
  2. Not verified
  3. Verified (cardOnFile)
  4. Not verified (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.

Action Link (resources)Description
verifications:verificationThe link to the outcome of your verification request.
payments:recurringAuthorizeA subsequent payment in a recurring agreement. This resource is only returned as a result of a successful verifications:cardOnFile, verifications:dynamicCardOnFile or payments:migrateRecurringAuthorize request.
payments:cardOnFileAuthorizeA subsequent payment in a card on file agreement. This resource is only returned as a result of a successful verifications:cardOnFile, verifications:dynamicCardOnFile or payments:migrateCardOnFileAuthorize request.
payments:recurringSaleA subsequent payment in a recurring agreement. This resource is only returned as a result of a successful verifications:cardOnFile or verifications:dynamicCardOnFile request.

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/verifications/accounts/{resource}

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
  1. Verified
  2. Not verified
  3. Verified (cardOnFile)
  4. Not verified (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
        }]
    }
}
Note

Verifications are accurate at the time of the initial verifications request,and sending another Intelligent or Dynamic verification requests may return different results.