Last updated: 12 May 2025 | Change log

Query and update tokens

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

Retrieve token details using the token href link data

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

Note

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": "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.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
        }]
    }
}

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. If the token was created with a namespace, both tokenId and namespace must be supplied in order to target a specific token.

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

Token inquiry using tokenId

If you create tokens outside of Access Worldpay, you must use a tokenId to look them up. Query the tokens:tokens request link with the tokenId as a query parameter.

Request

GET https://try.access.worldpay.com/tokens?tokenId=9902480679618049603

Note

Replace 9902480679618049603 in the URL with the tokenId you're trying to query.

Note

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": "2030-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"
            },
            "_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
        }]
    }
}

Token inquiry using tokenId and namespace

If your token is in a namespace, then namespace must be included as a request parameter alongside the tokenId.

Request

GET https://try.access.worldpay.com/tokens?tokenId=9902480679618049603&namespace=my-namespace

Note

Replace 9902480679618049603 in the URL with the tokenId you're trying to query and replace my-namespace with the token namespace.

Note

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/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQUjRyeUt6Z21BN3NxdDN6VEYxeWNieSJ9"
        },
        "tokenId": "9925760692793807595",
        "description": "Test Token Description",
        "tokenExpiryDateTime": "2026-09-02T14:37:06Z",
        "namespace": "customer-1",
        "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.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQUjRyeUt6Z21BN3NxdDN6VEYxeWNieSJ9"
          },
          "tokens:description": {
            "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQU0dMUkhEVmZ5bjg0VTVBVkVqTFFvcyJ9"
          },
          "tokens:cardHolderName": {
            "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeU5hRVBwbGlGeVJ1SmozZ2hta2ZFbEo3RnpSN2xPQ210elBIQkZBSzdiNHc9In0"
          },
          "tokens:cardExpiryDate": {
            "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeXMxVW4ySlIzUTZHclA1aVRDV3FRS3A3RnpSN2xPQ210elBIQkZBSzdiNHc9In0"
          },
          "tokens:billingAddress": {
            "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQVGp6RWVHOVkxUXpoMEdlMkR0ak9MeU5aT3d3L1ZGcE1vVjBQL2t2eDBXYlhiQW8rR2RhcUxRdkhGZXJSMDBGRkU9In0"
          },
          "tokens:schemeTransactionReference": {
            "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMmEySFRyUGdFQk9DQVBJWE9vZFQ2NEpJa08rK3hwYktyRnlBenpoWEpQU3Q1MlVockRlc2R5K1NKU1FBcUJhMzZjdHFSUklYNS9FWkYvbCtkay90WUE9PSJ9"
          }
        }
      }
    ]
  },
  "_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
      }
    ]
  }
}

Token inquiry using namespace only

To look up all tokens created under a namespace, query by namespace alone.

Request

GET https://try.access.worldpay.com/tokens?namespace=my-namespace

Note

Replace my-namespace in the URL with the token namespace.

Note

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": "2030-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"
                },
                "_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": "2030-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
        }]
    }
}

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 request.

You can update:

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.

Update descriptions

Update description example

Send a PUT request to the tokens:description request 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.

Update cardHolderName

Update cardHolderName example

Send a PUT request to the tokens:cardHolderName request 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.

Update cardExpiryDate

Update cardExpiryDate example

Request

Send a PUT request to the tokens:cardExpiryDate request 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.

Update billingAddress

Update billingAddress example

Send a PUT request to the tokens:billingAddress request 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.

Warning

You cannot partially update a billingAddress. You must send the complete billingAddress when updating it.

Response

The response status is 204 No Content.

Update schemeTransactionReference

Update schemeTransactionReference example

Send a PUT request to the tokens:schemeTransactionReference request 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 (" ").

Warning

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.

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.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.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0ODUrN2hvZ0cyK1JvQ3JKdUtFZnU5UTFsdTdwODVHTUcwYy92VW02MDlJd2pHQllvcW0zanhWQ3p3Zk9OUW9CYUZtQ1hNbFhwM3lhSXlkYVlNYWJnQUdQUHFpRVAxVXVpZHM2Y2tvTjEvOGNJdFQ0WkVlVEJIVWF6T1dlWTlQMkpnPT0ifQ

Reminder

No request body is needed for this request.

Response

The response status is 204 No Content.

Query and update tokens

Retrieve token details using the token href link data

Request

Response

Retrieve token details using query parameters

Token inquiry using tokenId

Request

Response

Token inquiry using tokenId and namespace

Request

Response

Token inquiry using namespace only

Request

Response

Update token details

Update descriptions

Request

Response

Update cardHolderName

Request

Response

Update cardExpiryDate

Request

Response

Update billingAddress

Request

Response

Update schemeTransactionReference

Request

Response

Delete tokens

Request

Response

Update a token with conflicts

Request

Response

Do you like our page?