Last Updated: 28 February 2024 | Change Log

Create a verified token

Use our Verified Tokens API to verify your customer's card payment details and create a verified token.

Create a verified token request

To create a verified token, POST your request to the:

verifiedTokens:oneTime action link - Use this action link:
- in all circumstances if PSD2 regulations apply to you (primarily if you are located in the UK, EEA, and Gibraltar). If you intend to keep the token for future payments, proceed to a challengeMandated 3DS flow to remain SCA compliant, before taking a payment.
- if you want to take a one-off payment. You must delete the token afterwards.
verifiedTokens:cardOnFile action link - Use this action link only if PSD2 regulations do not apply to you, and you intend to store cards for card on file or subscription payments.

When you create a verified token, you can optionally include the namespace parameter in your request. Choose either of the Card with a namespace or sessionState with a namespace tabs below to see an example.

Note

See Create a token for more information about namespaces.

POST https://try.access.worldpay.com/verifiedTokens/oneTime

POST https://try.access.worldpay.com/verifiedTokens/cardOnFile

Verified token creation request body:

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

Description of your request parameters:

Parameter	Required	Description
`description`	❌	A description of your token. If not supplied, a default `description` is created for you.
`tokenExpiryDateTime`	❌	The date/time after which the token will be unavailable, expressed in ISO 8601 format. If not supplied, a default expiry date/time is used.
`paymentInstrument`	✅	An object that contains the payment type and details. All sub-fields are mandatory with the exception of `cvc` and `billingAddress` (see below).
`cvc`	❌	The CVC number from the card. This is used during the verification process and if not supplied, the verification acceptance rate is likely to be lower.
`billingAddress`	❌	An object containing the billing address information. If included, the below fields are mandatory: `address1` `city` `countryCode` `postalCode` This is used during the verification and payment processes. If the address supplied does not match the address registered with the issuing bank, the payment carries additional risk.
`merchant`	✅	An object that contains information about the merchant. Contact your Implementation Manager for more information.
`verificationCurrency`	✅	The 3 character currency code. See our list of supported currencies.
`namespace`	❌	A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.

Using the sessionState

If you are using the Access Checkout SDK the paymentInstrument.type changes from card/plain to card/checkout, and sessionHref is used instead of cardNumber, cardExpiryDate and cvc.

The sessionHref looks like this :

https://try.access.worldpay.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoicGtubGtlWDJzeTVTdG1Qa3F5WlZ0emdJY1JEbjIyZVJ6KzlOR245YWlOMFVsVytCYitTa1NWa3l0RU1DQjZXYiJ9

Note

The sessionState is very short-lived and can be used only once.

Responses

Once you've sent your request, one of the following responses is returned:

Verified

If your Verified Token request was successful, the outcome of verification and one of the following response codes is returned:

201 Created
200 OK
409 Conflict

For more information about these response codes, see Create a token responses.

The response contains links to the:

verification result
token

{
  "outcome": "verified",
  "_links": {
    "verifications:verification": {
      "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
    },
    "tokens:token": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}.json",
        "name": "verifications",
        "templated": true
      },
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}

You can query your verification to get your next available payment actions links.

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

Not verified

If the verification failed, a 206 Partial Content HTTP response status code is returned. The response body contains a link to the verification result as an unverified token is created.

{
  "outcome": "not verified",
  "_links": {
    "verifications:verification": {
      "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
    },
    "tokens:token": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}.json",
        "name": "verifications",
        "templated": true
      },
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}

If you are getting an "outcome": "not verified", the next logical step is to ask your customer to re-enter, try a different or supply a new card. You can then try and verify the token again.

You might receive "outcome": "not verified" when the card issuer wants to authenticate the customer before verifying the token. In this case, we create an unverified token and suggest that you proceed to authenticate with our 3DS API.

If you then want to take a one-time payment straight away, proceed directly to our Payments API.
If you want to use the unverified token in a recurring capacity (e.g. instalment or subscription), proceed to our Verifications API to verify the token separately. You can then store your verified token for future use or use it immediately.

Next steps

Take a payment
Take your first and subsequent recurring payment
Take your first and subsequent card on file payment - (use this as your next step if you have created a sessionState)

Create a verified token