**Last updated**: 28 February 2024 | [**Change log**](/products/verified-tokens/changelog/) # 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 use the token for: - CIT (Customer Initiated Transactions) - proceed to the 3DS flow to remain SCA compliant, before taking a payment. - Future MIT (Merchant Initiated Transactions) payments, proceed to the 3DS flow with the `challenge.preference` to `challengeMandated`, 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](/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" } }, "narrative": { "line1": "The Mind Palace Ltd", "line2": "Memory265-13-08-1876" }, "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" } }, "narrative": { "line1": "The Mind Palace Ltd", "line2": "Memory265-13-08-1876" }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP", "namespace": "SHOPPER_ID_1234567890" } Session { "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" } }, "narrative": { "line1": "The Mind Palace Ltd", "line2": "Memory265-13-08-1876" }, "merchant": { "entity": "default" }, "verificationCurrency": "GBP" } Session 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" } }, "narrative": { "line1": "The Mind Palace Ltd", "line2": "Memory265-13-08-1876" }, "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 is unavailable, expressed in ISO 8601 format. If not supplied, the default expiry date/time is 90 days in Try and 4 years in the Live environment. We extend the expiry by 4 years after the token is used to process a transaction in Live once a token has reached its half-life. For Try, expiry date extensions are not applicable. | | `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](https://www.worldpay-bsh.securedataplatform.com/en-GB/merchant-support#still-need-help) 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. | | `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](/products/reference/formatting#narrative-format) section for more information. | ### 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 ``` 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: 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` 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](/products/tokens/create-a-token#create-a-card-token-request). For more information about these response codes, see [Create a token responses](/products/tokens/create-a-token#create-a-token-responses). The response contains the embedded results of the: - [verification](/products/card-verifications/v5/verifications) result - [token](/products/tokens/querying-and-updating-tokens) Note Most but not all issuers are sending a `schemeTransactionReference`. cardOnFile 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-bsh.securedataplatform.com/verifications/accounts/{resource}" }, "payments:cardOnFileAuthorize": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/payments/authorizations/cardOnFile/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k=" }, "payments:recurringAuthorize": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/payments/authorizations/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k=" }, "payments:recurringSale": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/payments/sales/recurring/eyJrIjoia2FhYzM1ZiIsImxpbmtWZXJzaW9uIjoiMS4wLjAifQ==.rTSaWnvtqTfgLUF9d+yia:Xr:bMt7SfZl7sgZ0yFtqVrp79hk:hZjQ1rHNZUtukWvMHHnIhvkyp4QhRO0aAcDdOsiNkkSoq+It1ADfLty7k=" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.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-bsh.securedataplatform.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-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokens:description": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9" }, "tokens:billingAddress": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true } ] } } } } oneTime response { "_embedded": { "verification": { "outcome": "verified", "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": { "expiryDate": { "month": 5, "year": 2035 }, "brand": "visa", "fundingType": "debit", "paymentAccountReference": "reference" } }, "_links": { "verifications:verification": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/verifications/accounts/{resource}" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.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-bsh.securedataplatform.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-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokens:description": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9" }, "tokens:billingAddress": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.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](/products/tokens) and [Verifications API](/products/card-verifications/v5/verifications) for more information on the respective embedded response data. You can [query your verification](/products/card-verifications/v5/verifications#query-verifications-request) to get your next available 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. { "_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-bsh.securedataplatform.com/verifications/accounts/{resource}" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.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-bsh.securedataplatform.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-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokens:description": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9" }, "tokens:billingAddress": { "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9" }, "curies": [ { "href": "https://try.access.worldpay-bsh.securedataplatform.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](/products/3ds). Warning Please ensure you set the `challenge.preference` to `challengeMandated` in your 3DS authentication request if you are setting up an MIT (Merchant Initiated Transaction) agreement (e.g. a subscription). - 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. Note In case of any errors, you can get further information in our [error reference](/products/reference/worldpay-error-responses). br **Next steps** [Query the verification and token](/products/verified-tokens/querying-verification-and-token) [Take a payment](/products/card-payments)