Last Updated: 18 May 2023 | Change Log
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.
If you have tokens from a previous provider you can import the existing tokens 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 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:
{ "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" } } }
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:
|
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. |
You are not normally expected to provide a value for schemeTransactionReference. If you are using the Verified Tokens API 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:
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.
{ "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 }] } }
The link to a token is returned in the tokenPaymentInstrument.href parameter. When you receive this response, you must save the link.
The tokenId is for clients interested in linking their eCom and POS solutions. Contact your Implementation Manager for more details.
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.
{ "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 }] } }
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 using the tokens:conflicts action link returned in the response.
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, if a schemenTransactionReference 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.
Optional fields: If the existing token has a value for the field and your create a 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.
{ "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 }] } }
In case of an error, you can get further information in our error reference.
Next steps