Last Updated: 28 February 2024 | Change Log

Create a verified token

Use our Verified Tokens API to orchestrate verifying your customer's payment details and creating a token, in a single request.

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 request, you can optionally include the namespace parameter. Choose either of the Card with a namespace or Session 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:

Card
Card with a namespace
Session
Session with a namespace

{
  "description": "Token-Description",
  "paymentInstrument": {
    "type": "card/plain",
    "cardHolderName": "Sherlock Holmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "cvc": "123",
    "billingAddress": {
      "address1": "221B Baker Street",
      "address2": "Marylebone",
      "address3": "Westminster",
      "postalCode": "NW1 6XE",
      "city": "London",
      "state": "Greater London",
      "countryCode": "GB"
    }
  },
  "narrative": {
    "line1": "The Mind Palace Ltd",
    "line2": "Memory265-13-08-1876"
  },
  "merchant": {
    "entity": "MindPalaceLtd"
  },
  "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 is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 7 days in Try and 4 years in the Live environment. We extend the expiry by 7 days or 4 years after any use of the token, if under half of the time remains on the token.
`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.
`narrative`	❌	The `narrative` object helps your customers to better identify you on their statement. If included, you must provide subfield `line1`, which is used to provide basic details about the merchant. Optionally, you can also include subfield `line2`, which can be used for additional context about the payment or merchant. See Formatting section for more information.

Using a session

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/session/eyJrIjoxLCJkIjoicGtubGtlWDJzeTVTdG1Qa3F5WlZ0emdJY1JEbjIyZVJ6KzlOR245YWlOMFVsVytCYitTa1NWa3l0RU1DQjZXYiJ9

Note

The session has a lifespan of one minute and you can only use this once.

Responses

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

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

Note

If you are attempting to create a new verified token with the same card details as an existing token, you would receive a 409 Conflict response in the live environment but a 200 OK response in the test environment. This is because a different schemeTransactionReference is received as part of each create a token request.

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

The response contains the embedded results of the:

verification result
token

Note

Most but not all issuers are sending a schemeTansactionReference.

cardOnFile response
oneTime response

{
  "_embedded": {
    "verification": {
      "outcome": "verified",
      "schemeTransactionReference": "000000000000020005060720116005060",
      "checkedAt": "2020-08-18T14:29:10.641180Z",
      "riskFactors": [
        {
          "risk": "matched",
          "type": "cvc"
        },
        {
          "risk": "matched",
          "detail": "postcode",
          "type": "avs"
        },
        {
          "risk": "matched",
          "detail": "address",
          "type": "avs"
        }
      ],
      "paymentInstrument": {
        "type": "card/plain",
        "card": {
          "number": {
            "bin": "4444",
            "last4Digits": "1236"
          },
          "expiryDate": {
            "month": 5,
            "year": 2035
          },
          "brand": "visa",
          "fundingType": "debit",
          "issuer": {
            "name": "UNKNOWN"
          },
          "paymentAccountReference": "reference"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "payments:cardOnFileAuthorize": {
          "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "payments:recurringAuthorize": {
          "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "payments:recurringSale": {
          "href": "https://try.access.worldpay.com/payments/sales/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k="
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "name": "verifications",
            "templated": true
          }
        ]
      }
    },
    "token": {
      "tokenId": "9902480679618049603",
      "description": "Test Token Description",
      "tokenExpiryDateTime": "2021-08-18T14:30:40Z",
      "schemeTransactionReference": "000000000000020005060720116005060",
      "tokenPaymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
      },
      "paymentInstrument": {
        "type": "card/masked",
        "cardNumber": "4444********1111",
        "cardHolderName": "Sherlock Holmes",
        "cardExpiryDate": {
          "month": 5,
          "year": 2035
        },
        "billingAddress": {
          "address1": "221B Baker Street",
          "address2": "Marylebone",
          "address3": "Westminster",
          "postalCode": "NW1 6XE",
          "city": "London",
          "state": "Greater London",
          "countryCode": "GB"
        },
        "bin": "444433",
        "brand": "VISA"
      },
      "_links": {
        "tokens:token": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
        },
        "tokens:description": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9"
        },
        "tokens:cardHolderName": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9"
        },
        "tokens:cardExpiryDate": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9"
        },
        "tokens:billingAddress": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9"
        },
        "tokens:schemeTransactionReference": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9"
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
            "name": "tokens",
            "templated": true
          }
        ]
      }
    }
  }
}

Note

The above is a response for a successful verified token creation. Please see the Tokens API and Verifications API for more information on the respective embedded response data.

You can query your verification to get your next available 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.

{
  "_embedded": {
    "verification": {
      "outcome": "not verified",
      "code": "106",
      "description": "INVALID ACCOUNT",
      "checkedAt": "2020-08-18T14:29:10.641180Z",
      "riskFactors": [
        {
          "risk": "not_matched",
          "type": "cvc"
        },
        {
          "risk": "matched",
          "type": "avs",
          "detail": "postcode"
        },
        {
          "risk": "not_matched",
          "type": "avs",
          "detail": "address"
        }
      ],
      "paymentInstrument": {
        "type": "card/plain",
        "card": {
          "brand": "visa",
          "fundingType": "debit"
        }
      },
      "_links": {
        "verifications:verification": {
          "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "name": "verifications",
            "templated": true
          }
        ]
      }
    },
    "token": {
      "tokenId": "9902480679618049603",
      "description": "Test Token Description",
      "tokenExpiryDateTime": "2021-08-18T14:30:40Z",
      "tokenPaymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
      },
      "paymentInstrument": {
        "type": "card/masked",
        "cardNumber": "4444********1111",
        "cardHolderName": "Sherlock Holmes",
        "cardExpiryDate": {
          "month": 5,
          "year": 2035
        },
        "billingAddress": {
          "address1": "221B Baker Street",
          "address2": "Marylebone",
          "address3": "Westminster",
          "postalCode": "NW1 6XE",
          "city": "London",
          "state": "Greater London",
          "countryCode": "GB"
        },
        "bin": "444433",
        "brand": "VISA"
      },
      "_links": {
        "tokens:token": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
        },
        "tokens:description": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9"
        },
        "tokens:cardHolderName": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9"
        },
        "tokens:cardExpiryDate": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9"
        },
        "tokens:billingAddress": {
          "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9"
        },
        "curies": [
          {
            "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
            "name": "tokens",
            "templated": true
          }
        ]
      }
    }
  }
}

Not verified

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.

Not verified - code 65

You might receive "code": "65" for an "outcome": "not verified". The most likely reason is that 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.

Warning

Please ensure you set the challenge.preference to "challengeMandated" in your 3DS authentication request.

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.

Note

In case of any errors, you can get further information in our error reference.

Next steps

Query the verification and token
Take a payment

Create a verified token