Menu

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 thetokens:tokenaction link returned in theresponseof yourcreate a tokenrequest.

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 anamespace token inquiryrequest.

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.

Copied!
{
    "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": "Testy McTester",
        "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": "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
        }]
    }
}
{
  "tokenPaymentInstrument": {
    "type": "card/tokenized",
    "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoicFNYbzNBdHN5NFFLbm9GZ2JuWTNLNm1WRllGT2p5R2hnSzlqdE9oVFlQdERaR1ZqMzFMcW05ZzJFNi9hTFRxaCJ9"
  },
  "tokenId": "9925163845344159004",
  "description": "Test Token Description",
  "tokenExpiryDateTime": "2021-06-24T14:12:30Z",
  "paymentInstrument": {
    "type": "card/network+masked",
    "cardNumber": "5454********5454",
    "last4Digits": "5454",
    "networkType": "APPLEPAY",
    "brand": "ECMC",
    "cardExpiryDate": {
      "month": 12,
      "year": 2021
    }
  },
  "_links": {
    "tokens:token": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoicFNYbzNBdHN5NFFLbm9GZ2JuWTNLNm1WRllGT2p5R2hnSzlqdE9oVFlQdERaR1ZqMzFMcW05ZzJFNi9hTFRxaCJ9"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}

Token namespace inquiry request

Query thetokens:tokensaction link from the tokens root resource with the namespace as a query parameter.

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.

Copied!
{
    "_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": "John Appleseed",
                    "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": "444433",
                    "brand": "VISA"
                },
                "_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
        }]
    }
}
{
  "tokenPaymentInstrument": {
    "type": "card/tokenized",
    "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoicFNYbzNBdHN5NFFLbm9GZ2JuWTNLNm1WRllGT2p5R2hnSzlqdE9oVFlQdERaR1ZqMzFMcW05ZzJFNi9hTFRxaCJ9"
  },
  "tokenId": "9925163845344159004",
  "description": "Test Token Description",
  "tokenExpiryDateTime": "2021-06-24T14:12:30Z",
  "namespace": "my-namespace",
  "paymentInstrument": {
    "type": "card/network+masked",
    "cardNumber": "5454********5454",
    "last4Digits": "5454",
    "networkType": "APPLEPAY",
    "brand": "ECMC",
    "cardExpiryDate": {
      "month": 12,
      "year": 2021
    }
  },
  "_links": {
    "tokens:token": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoicFNYbzNBdHN5NFFLbm9GZ2JuWTNLNm1WRllGT2p5R2hnSzlqdE9oVFlQdERaR1ZqMzFMcW05ZzJFNi9hTFRxaCJ9"
    },
    "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 theresponseof yourcreate a tokenrequest.

You can update:

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

Warning:

  • You cannot update the card number. Instead, you must send a newcreate a tokenrequest.
  • You cannot update card network type tokens.

Updating descriptions


Updating cardHolderName


Updating cardExpiryDate


Updating billingAddress


Updating schemeTransactionReference



Deleting tokens

To delete a token, send a DELETE request to the token resource reference received in the tokenPaymentInstrument object in your create a tokenresponse.

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.



Updating a token with conflicts

To resolve a token with a conflict, send a PUT request with no request body to thetokens:conflictsaction link returned in theconflict responsewhen youcreated the token.

This request replaces all conflicting fields in the existing token with data from your initial token request.

Warning:

  • 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

Reminder: 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 thetokens:tokensaction link from thetokens root resource, with the tokenId as a query parameter.

Token ID look up 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.

Copied!
{
    "_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": "John Appleseed",
                "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": "444433",
                "brand": "VISA"
            },
            "_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

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.