Last Updated: 18 May 2023 | Change Log
Querying and updating tokens
Find and change the details of your customers tokens.
Token inquiry
To retrieve the data stored in a token, send a GET
request to the tokens:token
action link returned in the response of your create a token request.
Do this if you want to display the tokenized card details to your customer on a payment page, or if you need the next available action links in order to update your customer's details.
If the token is in a namespace
, the namespace
attribute is also returned. To retrieve all tokens in the same namespace
, you must send a namespace token inquiry request.
The default expiry of a token is 7 days in Try and 4 years in the Live environment. Upon token inquiry, update or use in a payment, we extend the tokenExpiryDateTime
by an additional 7 days or 4 years, if under half of the time remains on the token.
Token inquiry request
GET
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
No request body is needed for this request.
Response
The response status is 200 OK
. You receive links to your next available actions in your response.
{ "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", "fundingType": "credit", "countryCode": "GB" }, "_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 }] } }
Token namespace inquiry request
Query the tokens:tokens
action link from the tokens root resource with the namespace
as a query parameter.
GET
https://try.access.worldpay.com/tokens?namespace=my-namespace
Replace my-namespace
in the URL with the token namespace.
No request body is needed for this request.
Response
The response status is 200 OK
and you receive an embedded list of tokens in the given namespace. Each token has its own links to its next available actions.
{ "_embedded": { "tokens": [{ "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T14:12:30Z", "namespace": "my-namespace", "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", "fundingType": "credit", "countryCode": "GB" }, "_links": { "tokens:token": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokens:description": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMXBDOGVSd3MydUJMSjVwRzVNanBqbGNxSGsrdytmcWwwRExsS0o3YjNsbkU9In0" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGRRYWhKQXYrcTlLdmdCTW1STGFLZzV3dW82bXo3WENkdTJKRzhmK3AyMjkifQ" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaFJTdkM0dVZ5SWVwSGhVclE2R1VSNVQ3Z0R1VHFBRmVGbDJqOVl6UEh2aEYifQ" }, "tokens:billingAddress": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGR6YjhXVHZjclVJZnF4WllKZ0hpQm5RZy9aeVNxMHZKR0N6RXJPclpORGoifQ" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiT2ZiMC94bFNRb1ZrY0hEbWtmaDFFQXNTTERJYnlXbXpqMU85VTUzK1RnclRVYkZoYjJxaVdqL1N5KzBtTUtTQ0toUHZMSWY5ZWZ1c0xIVE94R0FERkRwcnFYMFZSY2tnbklEdGh5Vm5CNlk9In0" } } }, { "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokenId": "9908329580648327627", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T14:12:26Z", "namespace": "my-namespace", "paymentInstrument": { "type": "card/masked", "cardHolderName": "John Appleseed", "cardNumber": "1111********4444", "cardExpiryDate": { "month": 5, "year": 2035 }, "billingAddress": { "address1": "Worldpay", "address2": "1 Milton Road", "address3": "The Science Park", "postalCode": "CB4 0WE", "city": "Cambridge", "state": "Cambridgeshire", "countryCode": "GB" }, "bin": "111122", "brand": "VISA" }, "_links": { "tokens:token": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokens:description": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMXBDOGVSd3MydUJMSjVwRzVNanBqbGNxSGsrdytmcWwwRExsS0o3YjNsbkU9In0" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGRRYWhKQXYrcTlLdmdCTW1STGFLZzV3dW82bXo3WENkdTJKRzhmK3AyMjkifQ" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaFJTdkM0dVZ5SWVwSGhVclE2R1VSNVQ3Z0R1VHFBRmVGbDJqOVl6UEh2aEYifQ" }, "tokens:billingAddress": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiWmhkSnBTdzdDajlQSDZKVVI1SHhLVDZsM1FPRGxTamRNbjJxQUZ0YjRrM1AwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGR6YjhXVHZjclVJZnF4WllKZ0hpQm5RZy9aeVNxMHZKR0N6RXJPclpORGoifQ" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiT2ZiMC94bFNRb1ZrY0hEbWtmaDFFQXNTTERJYnlXbXpqMU85VTUzK1RnclRVYkZoYjJxaVdqL1N5KzBtTUtTQ0toUHZMSWY5ZWZ1c0xIVE94R0FERkRwcnFYMFZSY2tnbklEdGh5Vm5CNlk9In0" } } } ] }, "_links": { "tokens:tokens": { "href": "https://try.access.worldpay.com/tokens{?tokenId,namespace}", "templated": true }, "resourceTree": { "href": "https://try.access.worldpay.com/rels/tokens/resourceTree.json" }, "curies": [{ "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true }] } }
Updating token details
To update the details in a token, send a PUT
request to one of the links returned in the response of your create a token request.
You can update:
- The token description
- The cardholder name
- The card expiry date
- The billing address
- The scheme transaction reference
You can only update one attribute at a time with a maximum of 50 updates in a rolling 30 day period.
- You cannot update the card number. Instead, you must send a new create a token request.
- You cannot update card network type tokens.
Updating descriptions
Update description example
Send a PUT
request to the tokens:description
action link received in your create a token response.
Request
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9
Request body:
"New token description"
Include the description
as a string in the body as shown above. The description
must be within quotation marks (" "
).
Response
The response status is 204 No Content
.
Updating cardHolderName
Update cardHolderName example
Send a PUT
request to the tokens:cardHolderName
action link received in your create a token response.
Request
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9
Request body:
"New name"
Include the cardHolderName
as a string in the body as shown above. The cardHolderName
must be within quotation marks (" "
).
Response
The response status is 204 No Content
.
Updating cardExpiryDate
Update cardExpiryDate example
Request
Send a PUT
request to the tokens:cardExpiryDate
action link received in your create a token response.
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdUpLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9
Request body:
{ "month": 5, "year": 2023 }
Include both the month
and date
in the JSON body.
Response
The response status is 204 No Content
.
Updating billingAddress
Update billingAddress example
Send a PUT
request to the tokens:billingAddress
action link received in your create a token response.
Request
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0d3ltd21ieGo3TlZLYzRYSkExOUhSdFpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9
Request body:
{ "address1": "ADDRESS 1", "address2": "ADDRESS 2", "address3": "ADDRESS 3", "postalCode": "TE12 34ST", "city": "TEST CITY", "state": "TEST STATE", "countryCode": "XX" }
You must include all the mandatory parameters in your update billingAddress
request. See the description of the create a token request parameters for more information.
Using this request, you can also add a billing address to a token which didn't previously include a billing address.
billingAddress
. You must send the complete billingAddress
when updating it.Response
The response status is 204 No Content
.
Updating schemeTransactionReference
Update schemeTransactionReference example
Send a PUT
request to the tokens:schemeTransactionReference
action link received in your create a token response.
Request
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9
Request body:
"000000000000020005060720116005060"
Include the schemeTransactionReference
as a string in the body as shown above. The schemeTransactionReference
must be within quotation marks (" "
).
For compliance with the Merchant Initiated Transaction (MIT) framework you should store the schemeTransactionReference
created for the first payment. Alternatively, you can store the reference included in the most recent payment. You must consider that you can only make 50 updates in a rolling 30 days.
Response
The response status is 204 No Content
.
Deleting tokens
To delete a token, send a DELETE
request to the token resource reference received in the tokenPaymentInstrument
object in your create a token response.
You might want to delete tokens if a customer has closed their account with you, or if the customer no longer wants their card details kept on file.
Request
DELETE
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
No request body is needed for this request. You can delete tokens of all types.
Response
The response status is 204 No Content
.
Updating a token with conflicts
To resolve a token with a conflict, send a PUT
request with no request body to the tokens:conflicts
action link returned in the conflict response when you created the token.
This request replaces all conflicting fields in the existing token with data from your initial token request.
- The
tokens:conflict
action link is time-limited. Once it expires, it is no longer possible to use this link to update the original token. - You cannot update card network type tokens. The
tokens:conflict
action will not be provided for tokens of this type.
Request
Send a PUT
request to the tokens:conflicts
link:
PUT
https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0ODUrN2hvZ0cyK1JvQ3JKdUtFZnU5UTFsdTdwODVHTUcwYy92VW02MDlJd2pHQllvcW0zanhWQ3p3Zk9OUW9CYUZtQ1hNbFhwM3lhSXlkYVlNYWJnQUdQUHFpRVAxVXVpZHM2Y2tvTjEvOGNJdFQ0WkVlVEJIVWF6T1dlWTlQMkpnPT0ifQ
No request body is needed for this request.
Response
The response status is 204 No Content
.
Token ID look up
If you create tokens outside of Access Worldpay, you must use a tokenId
to look them up. Query the tokens:tokens
action link from the tokens root resource, with the tokenId
as a query parameter.
Token ID look up request
GET
https://try.access.worldpay.com/tokens?tokenId=9902480679618049603
Replace 9902480679618049603
in the URL with the tokenId
you're trying to query.
No request body is needed for this request.
Response
The response status is 200 OK
and you receive an embedded list containing exactly one token, if the token was found. Otherwise, an empty list is returned.
{ "_embedded": { "tokens": [{ "tokenPaymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokenId": "9902480679618049603", "description": "Test Token Description", "tokenExpiryDateTime": "2021-06-24T14:12:30Z", "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", "fundingType": "credit", "countryCode": "GB" }, "_links": { "tokens:token": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMVdWVGh3SEFXOUhJaUYwWHhmYW5lY3c9PSJ9" }, "tokens:description": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMXBDOGVSd3MydUJMSjVwRzVNanBqbGNxSGsrdytmcWwwRExsS0o3YjNsbkU9In0" }, "tokens:cardHolderName": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGRRYWhKQXYrcTlLdmdCTW1STGFLZzV3dW82bXo3WENkdTJKRzhmK3AyMjkifQ" }, "tokens:cardExpiryDate": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaFJTdkM0dVZ5SWVwSGhVclE2R1VSNVQ3Z0R1VHFBRmVGbDJqOVl6UEh2aEYifQ" }, "tokens:billingAddress": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiVzFTTDVldnlHZHpaZDQ4Z0hhczRGWEhtU1hZcmdRVVpvLyt2L0lFdkxqRFAwR1pkS2hFUHFMSmFiVmp4ZitXMUlMK0ljWkcxS3ZuQW02RFh4ZjduaGR6YjhXVHZjclVJZnF4WllKZ0hpQm5RZy9aeVNxMHZKR0N6RXJPclpORGoifQ" }, "tokens:schemeTransactionReference": { "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiSENXWFZQZjNIZ1V3dnpDMElJZS9Zdmc4M0pYM3dDWEJTVnQrWVlacXdDUXFFKzhzaC8xNSs2d3NkTTdFWUFNVU9tdXBmUlZGeVNDY2dPMkhKV2NIcGc9PSJ9" } } }] }, "_links": { "tokens:tokens": { "href": "https://try.access.worldpay.com/tokens{?tokenId,namespace}", "templated": true }, "resourceTree": { "href": "https://try.access.worldpay.com/rels/tokens/resourceTree.json" }, "curies": [{ "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true }] } }
If your token is in a namespace, then namespace
must be included as a request parameter.
Token ID and namespace look up request
GET
https://try.access.worldpay.com/tokens?tokenId=9902480679618049603&namespace=my-namespace
Replace 9902480679618049603
in the URL with the tokenId
you're trying to query and replace my-namespace
with the token namespace.
No request body is needed for this request.