Skip to content

Last updated: 28 August 2026 | Change log

Query and update tokens

Find and change the details of your customer's tokens.

To retrieve the data stored in a token, send a GET request to the tokens:token request 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 request 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 retrieve the token details using query parameters.

By default, all sensitive PCI details are masked in the response. If you wish the raw card details to be returned in the response, see detokenize.

Note

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.

Request

GET https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ

Note

No request body is needed for this request.

Response

Response
application/vnd.worldpay.tokens-v3.hal+json
{
  "tokenPaymentInstrument": {
    "type": "card/tokenized",
    "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
  },
  "tokenId": "9902480679618049603",
  "description": "Test Token Description",
  "tokenExpiryDateTime": "2030-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"
  },
  "_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
      }
    ]
  }
}

View the full API Response schema

Retrieve token details using query parameters

Query the tokens:tokens request link from the tokens root resource.

At least one of tokenId or namespace must be provided.

Avoid using personally identifiable information (PII) as references. This prevents the logging of sensitive identifiers.

Request

To look up an individual token created without a namespace, query by tokenId. GET https://try.access.worldpay-bsh.securedataplatform.com/tokens?tokenId=9902480679618049603

If the token was created with a namespace, both tokenId and namespace must be supplied in order to target a specific token. GET https://try.access.worldpay-bsh.securedataplatform.com/tokens?tokenId=9902480679618049603&namespace=my-namespace

To look up all tokens created under a namespace, query by namespace alone. GET https://try.access.worldpay-bsh.securedataplatform.com/tokens?namespace=my-namespace

Note

Replace 9902480679618049603 in the URL with the tokenId you're trying to query, and my-namespace by the namespace where applicable.

Note

No request body is needed for this request.

Response

Response
application/vnd.worldpay.tokens-v3.hal+json
{
  "_embedded": {
    "tokens": [
      {
        "tokenPaymentInstrument": {
          "type": "card/tokenized",
          "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQUjRyeUt6Z21BN3NxdDN6VEYxeWNieSJ9"
        },
        "tokenId": "9925760692793807595",
        "description": "Test Token Description",
        "tokenExpiryDateTime": "2026-09-02T14:37:06Z",
        "paymentInstrument": {
          "type": "card/masked",
          "cardNumber": "4444********1111",
          "cardHolderName": "Sherlock Holmes",
          "cardExpiryDate": {
            "month": 5,
            "year": 2037
          },
          "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"
        },
        "_links": {
          "tokens:token": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQUjRyeUt6Z21BN3NxdDN6VEYxeWNieSJ9"
          },
          "tokens:description": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQU0dMUkhEVmZ5bjg0VTVBVkVqTFFvcyJ9"
          },
          "tokens:cardHolderName": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeU5hRVBwbGlGeVJ1SmozZ2hta2ZFbEo3RnpSN2xPQ210elBIQkZBSzdiNHc9In0"
          },
          "tokens:cardExpiryDate": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeXMxVW4ySlIzUTZHclA1aVRDV3FRS3A3RnpSN2xPQ210elBIQkZBSzdiNHc9In0"
          },
          "tokens:billingAddress": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeU5aT3d3L1ZGcE1vVjBQL2t2eDBXYlhiQW8rR2RhcUxRdkhGZXJSMDBGRkU9In0"
          },
          "tokens:schemeTransactionReference": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQU3Q1MlVockRlc2R5K1NKU1FBcUJhMzZjdHFSUklYNS9FWkYvbCtkay90WUE9PSJ9"
          }
        }
      }
    ]
  },
  "_links": {
    "tokens:tokens": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/tokens{?tokenId,namespace}",
      "templated": true
    },
    "resourceTree": {
      "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/tokens/resourceTree.json"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay-bsh.securedataplatform.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}

View the full API Response schema


Update 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, token href lookup or token inquiry request.

You can update:

  • the token description
  • the cardholder name
  • the card expiry date
  • the billing address
  • the scheme transaction reference
Note

You can only update one attribute at a time with a maximum of 50 updates in a rolling 30 day period.

Warning
  • You cannot update the card number. Instead, you must send a new create a token request.
  • You cannot update card network type tokens.

Request

PUT
https://try.access.worldpay-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0MWJVbkh1WTFGZExUNXJxc04va1ZoTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9

Update billing address.

application/vnd.worldpay.tokens-v3.hal+json
{
  "address1": "1 Test Street",
  "address2": "Address line 2",
  "address3": "Address line 3",
  "postalCode": "TE12 34ST",
  "city": "Testville",
  "state": "Testshire",
  "countryCode": "TS"
}

View the full API Request schema

Response

The response status is 204 No Content for a successful update, or 429 indicating too many updates within the period.

Delete 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-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ

Note

No request body is needed for this request. You can delete tokens of all types.

Response

The response status is 204 No Content.

Warning
This action cannot be undone. Once we've received the request, the token is deleted.


Update a token with conflicts

To resolve a token with a conflict, send a PUT request with no request body to the tokens:conflicts request 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.

Warning
  • The tokens:conflicts request 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:conflicts 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-bsh.securedataplatform.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0ODUrN2hvZ0cyK1JvQ3JKdUtFZnU5UTFsdTdwODVHTUcwYy92VW02MDlJd2pHQllvcW0zanhWQ3p3Zk9OUW9CYUZtQ1hNbFhwM3lhSXlkYVlNYWJnQUdQUHFpRVAxVXVpZHM2Y2tvTjEvOGNJdFQ0WkVlVEJIVWF6T1dlWTlQMkpnPT0ifQ

Reminder

No request body is needed for this request.

Response

The response status is 204 No Content.