Skip to content
APIs/Tokens/Token

Token

A token representing a payment instrument.

Operations

Create a new token

Request

Create a new token for the payment instrument.

Security
BasicAuth
Bodyapplication/vnd.worldpay.tokens-v3.hal+json
paymentInstrumentobjectrequired
merchantobjectrequired

An object that contains information about your merchant account.

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 90 days in Try and 4 years in the Live environment.

In Live, if the token is used in the second half of its life, the token expiry becomes 4 years from that point, with no limit to the number of extensions. In Try, expiry date extensions are not applicable. After the expiry passes, the token is deleted.

namespacestring, [ 1 .. 64 ] characters

A reference to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace. If supplied, must not start with an underscore, must not contain spaces, '&' or '<'.

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.

{
  "paymentInstrument": {
    "type": "card/front",
    "cardHolderName": "Sherlock Holmes",
    "cardNumber": "4444333322221111",
    "cardExpiryDate": {
      "month": 5,
      "year": 2035
    }
  },
  "merchant": {
    "entity": "default"
  }
}

Responses

You've already tokenized the card and all data supplied in your create a token request matches the data stored with us.

The existing token resource reference is returned in the tokenPaymentInstrument object.

Note: Sometimes we match a token even if the data doesn't seem quite the same. For example, if we have a billing address on file, we retain this address if you do not supply a billingAddress object in your request.

Headers
Acceptstring

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

Content-Typestring

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

Locationstring, (uri)

A URI identifying the created token resource.

Bodyapplication/vnd.worldpay.tokens-v3.hal+json
tokenPaymentInstrumentobject
tokenIdstring, [ 15 .. 21 ] characters^[0-9A-HJ-NP-Z]+$

Worldpay's internal identifier for a token.

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 90 days in Try and 4 years in the Live environment.

In Live, if the token is used in the second half of its life, the token expiry becomes 4 years from that point, with no limit to the number of extensions. In Try, expiry date extensions are not applicable. After the expiry passes, the token is deleted.

namespacestring, [ 1 .. 64 ] characters

A reference to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace. If supplied, must not start with an underscore, must not contain spaces, '&' or '<'.

paymentInstrumentobject
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
{
  "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
      }
    ]
  }
}