**Last updated**: 28 February 2024 | [**Change log**](/products/verified-tokens/changelog/) # Create a verified token Use our Verified Tokens API to verify your customer's 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 Session with a namespace tabs below to see an example. Note See [create a token](/products/tokens/create-a-token) for more information about namespaces. `POST` `https://try.access.worldpay-bsh.securedataplatform.com/verifiedTokens/oneTime` or `POST` `https://try.access.worldpay-bsh.securedataplatform.com/verifiedTokens/cardOnFile` Verified token creation request body: Card { "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" } }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP" } Card 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" } }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP", "namespace": "SHOPPER_ID_1234567890" } sessionState { "description": "Token-Description", "paymentInstrument": { "type": "card/checkout", "cardHolderName": "Sherlock Holmes", "sessionHref": "https://try.access.worldpay-bsh.securedataplatform.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9", "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" } }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP" } sessionState with a namespace { "description": "Token-Description", "paymentInstrument": { "type": "card/checkout", "cardHolderName": "Sherlock Holmes", "sessionHref": "https://try.access.worldpay-bsh.securedataplatform.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoiZmJIT1pOOXNRc2xFeWQ1NXc5WEVLWHppUlJUWkpiMGozZkZIdWhFdmp4QTd4UmpNcWVmL0xJQzhHUTE0MCt6NyJ9", "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" } }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP", "namespace": "SHOPPER_ID_1234567890" } 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](/products/reference/supported-countries-currencies#iso-currency-codes). | | `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 a session If you are using the [Access Checkout SDK](/products/checkout), 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-bsh.securedataplatform.com/verifiedTokens/sessions/eyJrIjoxLCJkIjoicGtubGtlWDJzeTVTdG1Qa3F5WlZ0emdJY1JEbjIyZVJ6KzlOR245YWlOMFVsVytCYitTa1NWa3l0RU1DQjZXYiJ9 ``` The session has a lifespan of one minute and can be used only once. ## Responses Once you've sent your request, one of the following responses is returned: details summary 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](/products/tokens/create-a-token#create-a-token-responses). The response contains links to the: - [verification](/products/card-verifications/v5/verifications) result - [token](/products/tokens/querying-and-updating-tokens) { "outcome": "verified", "_links": { "verifications:verification": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/accounts/{resource}" }, "tokens:token": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/accounts/{rel}.json", "name": "verifications", "templated": true }, { "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true } ] } } You can [query your verification](/products/card-verifications/v5/verifications#query-verifications-request) to get your next available payment actions links. `GET` `https://try.access.worldpay-bsh.securedataplatform.com/verifications/accounts/{resource}` details summary 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](/products/card-verifications/v5/verifications) result as an unverified token is created. { "outcome": "not verified", "code": "106", "description": "INVALID ACCOUNT", "_links": { "verifications:verification": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/accounts/{resource}" }, "tokens:token": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/verifications/accounts/{rel}.json", "name": "verifications", "templated": true }, { "href": "https://try.access.worldpay-bsh.securedataplatform.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 `"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](/products/3ds). - If you then want to take a one-time payment straight away, proceed directly to our [Payments API](/products/card-payments/v6). - If you want to use the unverified token in a recurring capacity (e.g. instalment or subscription), proceed to our [Verifications API](/products/card-verifications/v5/verifications) to verify the token separately. You can then store your verified token for future use or use it immediately. br **Next steps** [Take a payment](/products/card-payments/v6/authorize-a-payment) [Take your first and subsequent recurring payment](/products/card-payments/v6/authorise-a-recurring-payment#recurring-authorization-without-verification) [Take your first and subsequent card on file payment](/products/card-payments/v6/authorise-a-cardonfile-payment#card-on-file-without-verification-authorization-request) - (use this as your next step if you have created a `sessionState`)