**Last updated**: 23 April 2025 | [**Change log**](/access/products/tokens/changelog/) # Create a token Create a card token to secure your customer's card and billing information, which could help lower your PCI-DSS compliance costs. Note If you have tokens from a previous provider you can [import the existing tokens](https://developerengine.fisglobal.com/apis/wpg/tokenisation/bulktokenmigration/panmigration) to Access Worldpay. ## Create a card token request To create a token, `POST` your request to the `tokens:tokens` action link returned in your [query on the tokens root resource](/access/products/tokens/v2/get-started#query-the-tokens-root-resource) response. When you create a token, you can optionally include the `namespace` parameter in your request. Click the Create a token with a namespace tab below to see an example request. ### Create a token example requests `POST` `https://try.access.worldpay.com/tokens` Token creation request body: Create a token ```json { "description": "Test Token Description", "paymentInstrument": { "type": "card/front", "cardHolderName": "Sherlock Holmes", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 }, "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" } } } ``` Create a token with a namespace ```json { "description": "Test Token Description", "namespace": "SHOPPER_ID_1234567890", "paymentInstrument": { "type": "card/front", "cardHolderName": "Sherlock Holmes", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 }, "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" } } } ``` #### Description of your create a token 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 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 `billingAddress` (see below). | | `billingAddress` | ❌ | An object containing the `billingAddress` information. **If included, the below fields are mandatory:**`address1``city``countryCode``postalCode` This is used during payment processing. If the address supplied does not match the address registered with the issuing bank, the payment carries additional risk. | | `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. | | `schemeTransactionReference` | ❌ | A value provided by Visa or Mastercard which tracks recurring transactions. | Note You are not normally expected to provide a value for `schemeTransactionReference`. If you are using the [Verified Tokens API](/access/products/verified-tokens/v2) to create tokens, it is automatically included where applicable. ### Responses Once you've sent your create a token request, one of the following responses is returned: details summary 201 - Created If this is the first time you've tokenized the card, a `201 Created` response is returned. Your response contains a `tokenPaymentInstrument` object which contains the `href` to the token resource. The response also includes next available action links, e.g. [updating and deleting the token](/access/products/tokens/v2/querying-and-updating-tokens). ```json { "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T09:19:35Z", "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 }] } } ``` Remember The link to a token is returned in the `tokenPaymentInstrument.href` parameter. When you receive this response, you must save the link. Note The `tokenId` is for clients interested in linking their eCom and POS solutions. Contact your Implementation Manager for more details. details summary 200 - OK A `200 OK` response means that you've already tokenized the card and that all data supplied in your create a token request matches the data stored with Access Worldpay. Sometimes, a token can be matched even if the data isn't quite the same. For example, if Access Worldpay has a `billingAddress` on file, the existing `billingAddress` is retained if no `billingAddress` was supplied in your request. Additionally, you receive the `200 OK` response code. The existing token resource reference is returned in the `tokenPaymentInstrument` object. ```json { "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T09:19:35Z", "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 }] } } ``` details summary 409 - Conflict A `409 Conflict` response means that you've already tokenized the card, but some of the data supplied in your create a token request is different from the data in the existing token. This conflict could be caused by a differentiation in the `cardHolderName`, card expiry `month`, card expiry `year` `billingAddress` or `schemeTransactionReference` (see note below) fields. In this case, the data that Access Worldpay has on file is retained, and the data which caused the conflict is returned in a `conflicts` object. If you would like to resolve the conflict, you can [update the existing token](/access/products/tokens/v2/querying-and-updating-tokens#updating-a-token-with-conflicts) using the `tokens:conflicts` action link returned in the response. Note The behavior for a conflicting `schemeTransactionReference` is slightly different from the other fields. If the existing token does not contain a `schemeTransactionReference` then it is automatically updated to include the one in your [create a token request](/access/products/tokens/v2/create-a-token#create-a-card-token-request), if a `schemeTransactionReference` is present. If the token is otherwise the same, you get a `200 OK` response. If the token has other conflicted fields you will still get a 409 conflict response but the `schemeTransactionReference` is not listed as a conflict. Note Optional fields: If the existing token has a value for the field and your [create a token request](/access/products/tokens/v2/create-a-token#create-a-card-token-request) does not, then this is not counted as a conflict, and no change is made. The existing token resource reference is returned in the `tokenPaymentInstrument` object. ```json { "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T09:19:35Z", "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" }, "conflicts": { "paymentInstrument": { "cardHolderName": "Sherlock Holmes" }, "conflictsExpiryDateTime": "2019-06-24T09:49:35Z" }, "_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" }, "tokens:conflicts": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0ODUrN2hvZ0cyK1JvQ3JKdUtFZnU5UTFsdTdwODVHTUcwYy92VW02MDlJd2pHQllvcW0zanhWQ3p3Zk9OUW9CYUZtQ1hNbFhwM3lhSXlkYVlNYWJnQUdQUHFpRVAxVXVpZHM2Y2tvTjEvOGNJdFQ0WkVlVEJIVWF6T1dlWTlQMkpnPT0ifQ" }, "curies": [{ "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true }] } } ``` br Note In case of an error, you can get further information in our [error reference](/access/products/reference/worldpay-error-responses). **Next steps** [Update token details](/access/products/tokens/v2/querying-and-updating-tokens#updating-token-details) [Delete the token](/access/products/tokens/v2/querying-and-updating-tokens#deleting-tokens)