New API Version | Last Updated: 21 November 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 can query the root resource first.

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

Header	Description
`Authorization`	The `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-Type`	The `Content-Type` header is required for all request sent to our Verifications API.
`Accept`	The `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:

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

Parameter	Required	Description
`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:

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

Parameter	Required	Description
`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

{
    "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: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`, `verifications:dynamicCardOnFile` 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`, `verifications:dynamicCardOnFile` or `payments:migrateCardOnFileAuthorize` request.
`payments:recurringSale`	A 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

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

Verify a customer's account

Query the root resource

Query the root resource response

Set your headers

Query verifications root resource

The response

Intelligent verification

Intelligent verification request

oneTime intelligent verification

cardOnFile intelligent verification

Dynamic verification

Dynamic verification request

dynamicOneTime verification

dynamicCardOnFile verification

Dynamic verification request body:

Verifications response

Location storing

Query a historic verification

Query verifications request

Query verifications response

Do you like our page?

`oneTime` intelligent verification

`cardOnFile` intelligent verification

`dynamicOneTime` verification

`dynamicCardOnFile` verification