Skip to content
APIs/Tokens/
/
Retrieve the detail for t...

Tokens (1)

A collection of tokens representing payment instruments.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Test (Try)
https://try.access.worldpay.com
Live
https://access.worldpay.com

Token

A token representing a payment instrument.

Operations

Create a new token

Request

Creating a new token for the payment instrument.

Security
BasicAuth
Bodyapplication/vnd.worldpay.tokens-v1.hal+json
descriptionstring[ 1 .. 255 ] characters^[^&<]*$

A description of your token. If not supplied, a default description is created for you.

tokenExpiryDateTimestring(date-time)

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 7 days or 4 years after any use of the token, if under half of the time remains on the token.

namespacestring[ 1 .. 64 ] characters

A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.

schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$

A value provided by Visa or Mastercard which tracks recurring transactions.

Note: 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.

paymentInstrumentobjectrequired

An object that contains the payment type and details. All sub-fields are mandatory with the exception of billingAddress (see below).

typestring

card/front

cardHolderNamestring[ 1 .. 255 ] characters

The name on the customer's card.

cardExpiryDateobject
cardNumberstring[ 10 .. 19 ] characters^[0-9]*$

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

merchantobjectrequired

An object that contains information about your merchant account.

application/vnd.worldpay.tokens-v1.hal+json
{
  "paymentInstrument": {
    "type": "card/front",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 1,
      "year": 2025
    },
    "cardHolderName": "Testy McTester"
  },
  "merchant": {
    "entity": "default"
  }
}

Responses

A token already exists matching the details in the request.

Headers
Acceptstring

application/vnd.worldpay.tokens-v1.hal+json

Content-Typestring

application/vnd.worldpay.tokens-v1.hal+json

Locationstring(uri)

A URI identifying the created token resource.

Bodyapplication/vnd.worldpay.tokens-v1.hal+json
tokenPaymentInstrumentobjectrequired
typestring
hrefstring
descriptionstring[ 1 .. 255 ] characters^[^&<]*$required

A description of your token. If not supplied, a default description is created for you.

tokenExpiryDateTimestring(date-time)required

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 7 days or 4 years after any use of the token, if under half of the time remains on the token.

paymentInstrumentobjectrequired
cardNumberstring[ 10 .. 19 ] characters^[0-9\*]*$required

Contains your customer's card number.

cardExpiryDateobjectrequired
cardHolderNamestring[ 1 .. 255 ] characters

The name on the customer's card.

billingAddressobject

Contains the billing address information.

networkTypestring[ 1 .. 255 ] characters
last4Digitsstring= 4 characters
tokenIdstring[ 15 .. 21 ] characters^[0-9A-HJ-NP-Z]+$
namespacestring[ 1 .. 64 ] characters
schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$

A value provided by Visa or Mastercard which tracks recurring transactions.

Note: 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.

Response
application/vnd.worldpay.tokens-v1.hal+json
{
  "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"
    }
  },
  "_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 the detail for this token

Request

A token representing a payment instrument.

Security
BasicAuth
Path
tokenIdstringrequired

Access Worldpay encrypted token.

No request payload

Responses

The detail for this token.

Bodyapplication/vnd.worldpay.tokens-v1.hal+json
tokenPaymentInstrumentobjectrequired
typestring
hrefstring
descriptionstring[ 1 .. 255 ] characters^[^&<]*$required

A description of your token. If not supplied, a default description is created for you.

tokenExpiryDateTimestring(date-time)required

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 7 days or 4 years after any use of the token, if under half of the time remains on the token.

paymentInstrumentobjectrequired
cardNumberstring[ 10 .. 19 ] characters^[0-9\*]*$required

Contains your customer's card number.

cardExpiryDateobjectrequired
cardHolderNamestring[ 1 .. 255 ] characters

The name on the customer's card.

billingAddressobject

Contains the billing address information.

networkTypestring[ 1 .. 255 ] characters
last4Digitsstring= 4 characters
tokenIdstring[ 15 .. 21 ] characters^[0-9A-HJ-NP-Z]+$
namespacestring[ 1 .. 64 ] characters
schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$

A value provided by Visa or Mastercard which tracks recurring transactions.

Note: 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.

Response
application/vnd.worldpay.tokens-v1.hal+json
{
  "tokenPaymentInstrument": {
    "type": "card/tokenized",
    "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ"
  },
  "tokenId": "9925760692793807595",
  "description": "Token Description",
  "tokenExpiryDateTime": "2025-01-23T10:57:01Z",
  "paymentInstrument": {
    "type": "card/masked",
    "cardNumber": "4444********1111",
    "cardHolderName": "Card Holder Name",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    },
    "billingAddress": {
      "address1": "Address 1",
      "address2": "Address 2",
      "address3": "Address 3",
      "postalCode": "Postal Code",
      "city": "City",
      "state": "State",
      "countryCode": "XX"
    }
  },
  "_links": {
    "tokens:token": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ"
    },
    "tokens:description": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXdW9oYzR3RUFEM2FCQnlaejhsZ1poTFVzYW1OU1lxSFE2NHI1c2JkY1pWaSJ9"
    },
    "tokens:cardHolderName": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXT0pLN2N3VVc5WUk3czRUTW1RQ2JLdjFnVXlzakdPSXdWWkRhZkZyUmlMd3c9PSJ9"
    },
    "tokens:cardExpiryDate": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXT0pLN2N3VVc5WUk3czRUTW1RQ2JLdkVpVW5GNnBsZThNTXNQWTRGbzFzTXc9PSJ9"
    },
    "tokens:billingAddress": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXTlpSdXFxbWZlNVl1TkpHZEVvZXN3MTlCU0lmdCtxSTUyVDJSdXlmSTIwM3c9PSJ9"
    },
    "tokens:schemeTransactionReference": {
      "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXc2w4WnRHSGdzblFZd2Y4ZU1hLzhXTThZcVl5OWJFUHNnbzNpTHd1NlpJSTJxUUNRVXZybWJpRkdyQ0NNQ0g0ZlpsNlBnc1NkL0h5VkRCKyt0Ym9wMGs9In0"
    },
    "tokens:networkToken": {
      "href": "https://try.access.worldpay.com/tokens/network"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}

Update this token

Request

Updating different fields represented by the token

Security
BasicAuth
Path
tokenIdstringrequired

Access Worldpay encrypted token.

Bodyapplication/vnd.worldpay.tokens-v1.hal+json
schemeTransactionReferencestring[ 1 .. 56 ] characters^[a-zA-Z0-9 ]*$

A value provided by Visa or Mastercard which tracks recurring transactions.

Note: 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.

cardHolderNamestring[ 1 .. 255 ] characters

The name on the customer's card.

descriptionstring[ 1 .. 255 ] characters^[^&<]*$

A description of your token. If not supplied, a default description is created for you.

monthinteger[ 1 .. 12 ]
yearinteger<= 9999
address1string
address2string
address3string
postalCodestring
citystring
statestring
countryCodestring= 2 characters^[A-Z]*$
application/vnd.worldpay.tokens-v1.hal+json
{
  "address1": "1 Test Street",
  "address2": "Address line 2",
  "address3": "Address line 3",
  "postalCode": "TE12 34ST",
  "city": "Testville",
  "state": "Testshire",
  "countryCode": "TS"
}

Responses

The token was successfully updated.

Delete this token

Request

Deleting a token based on an encrypted tokenId

Security
BasicAuth
Path
tokenIdstringrequired

Access Worldpay encrypted token.

No request payload

Responses

The token was successfully deleted.