Tokens

A collection of tokens representing payment instruments.

Methods

GET

Retrieve token(s) based on their tokenId, namespace, or both.

Parameters

NameDescription
tokenIdWorldpay's internal identifier for a token. If supplied, must be between 15 and 21 characters, must consist of digits and upper-case characters excluding 'I' and 'O'.
namespaceThe reference by which a client can identify a shopper. If supplied, must be between 1 and 64 characters, must not start with an underscore, must not contain spaces, '&' or '<'.

Responses

Examples

GET
 Retrieve the Tokens top-level collection resource.
View
GET
 Find a token by tokenId.
View
GET
 Find a token by tokenId and namespace.
View
GET
 Find all tokens related to a namespace.
View
GET
 Token not found.
View
POST

Create a new Token.

Request

Copied!
{
 "type": "object",
 "properties": {
  "description": {
   "type": "string",
   "minLength": 1,
   "maxLength": 255,
   "pattern": "^[^&<]*$"
  },
  "tokenExpiryDateTime": {
   "type": "string",
   "format": "date-time"
  },
  "namespace": {
   "type": "string",
   "minLength": 1,
   "maxLength": 64
  },
  "originalToken": {
   "type": "string"
  },
  "schemeTransactionReference": {
   "type": "string",
   "minLength": 1,
   "maxLength": 56,
   "pattern": "^[a-zA-Z0-9 ]*$"
  },
  "paymentInstrument": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string"
    },
    "cardNumber": {
     "type": "string",
     "minLength": 10,
     "maxLength": 19,
     "pattern": "^[0-9]*$"
    },
    "cardHolderName": {
     "type": "string",
     "minLength": 1,
     "maxLength": 255
    },
    "cardExpiryDate": {
     "type": "object",
     "properties": {
      "month": {
       "type": "integer",
       "minimum": 1,
       "maximum": 12
      },
      "year": {
       "type": "integer",
       "maximum": 9999
      }
     },
     "required": [
      "month",
      "year"
     ]
    },
    "billingAddress": {
     "type": "object",
     "properties": {
      "address1": {
       "type": "string"
      },
      "address2": {
       "type": "string"
      },
      "address3": {
       "type": "string"
      },
      "postalCode": {
       "type": "string"
      },
      "city": {
       "type": "string"
      },
      "state": {
       "type": "string"
      },
      "countryCode": {
       "type": "string",
       "pattern": "^[A-Z]*$",
       "minLength": 2,
       "maxLength": 2
      }
     },
     "required": [
      "address1",
      "postalCode",
      "city",
      "countryCode"
     ]
    }
   },
   "required": [
    "cardNumber",
    "cardHolderName",
    "cardExpiryDate"
   ]
  },
  "merchant": {
   "type": "object",
   "properties": {
    "entity": {
     "type": "string"
    }
   },
   "required": [
    "entity"
   ]
  }
 },
 "required": [
  "merchant",
  "paymentInstrument"
 ]
}

Responses

Examples

POST
 Creating a new token.
View
POST
 Matching an existing token.
View
POST
 Conflicting with an existing token.
View
POST
 Creating a new shopper token.
View
POST
 Creating a new token using an existing token for default values.
View

Link relationship

get
 Retrieve the Tokens top-level collection resource. 
GEThttps://try.access.worldpay.com/tokens
Copied!
{
  "Accept": "application/vnd.worldpay.tokens-v3.hal+json"
}

200

Copied!
{
  "Content-Type": "application/vnd.worldpay.tokens-v3.hal+json;charset=UTF-8"
}
Copied!
{
  "_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"
    },
    "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
      }
    ]
  }
}