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

Response schema

Copied!
{
 "type": "object",
 "properties": {
  "_embedded": {
   "type": "object",
   "properties": {
    "tokens": {
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "tokenPaymentInstrument": {
        "type": "object",
        "properties": {
         "type": {
          "type": "string"
         },
         "href": {
          "type": "string"
         }
        }
       },
       "tokenId": {
        "type": "string",
        "minLength": 15,
        "maxLength": 21,
        "pattern": "^[0-9A-HJ-NP-Z]+$"
       },
       "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "pattern": "^[^&<]*$"
       },
       "tokenExpiryDateTime": {
        "type": "string",
        "format": "date-time"
       },
       "namespace": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
       },
       "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"
          ]
         },
         "bin": {
          "type": "string",
          "minLength": 6,
          "maxLength": 6,
          "pattern": "\\d{6}"
         },
         "brand": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
         },
         "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",
         "bin",
         "brand"
        ]
       },
       "_links": {
        "type": "object",
        "format": "hal+json"
       }
      },
      "required": [
       "tokenPaymentInstrument",
       "description",
       "tokenExpiryDateTime",
       "paymentInstrument",
       "_links"
      ]
     }
    }
   }
  },
  "_links": {
   "type": "object",
   "format": "hal+json"
  }
 },
 "required": [
  "_links"
 ]
}

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"
   ]
  }
 },
 "required": [
  "paymentInstrument"
 ]
}

Responses

Headers

NameDescription
LocationAn URI identifying the matched Token resource.

Response schema

Copied!
{
 "type": "object",
 "properties": {
  "tokenPaymentInstrument": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string"
    },
    "href": {
     "type": "string"
    }
   }
  },
  "tokenId": {
   "type": "string",
   "minLength": 15,
   "maxLength": 21,
   "pattern": "^[0-9A-HJ-NP-Z]+$"
  },
  "description": {
   "type": "string",
   "minLength": 1,
   "maxLength": 255,
   "pattern": "^[^&<]*$"
  },
  "tokenExpiryDateTime": {
   "type": "string",
   "format": "date-time"
  },
  "namespace": {
   "type": "string",
   "minLength": 1,
   "maxLength": 64
  },
  "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"
     ]
    },
    "bin": {
     "type": "string",
     "minLength": 6,
     "maxLength": 6,
     "pattern": "\\d{6}"
    },
    "brand": {
     "type": "string",
     "minLength": 1,
     "maxLength": 255
    },
    "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",
    "bin",
    "brand"
   ]
  },
  "_links": {
   "type": "object",
   "format": "hal+json"
  }
 },
 "required": [
  "tokenPaymentInstrument",
  "description",
  "tokenExpiryDateTime",
  "paymentInstrument",
  "_links"
 ]
}

Headers

NameDescription
LocationAn URI identifying the created Token resource.

Response schema

Copied!
{
 "type": "object",
 "properties": {
  "tokenPaymentInstrument": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string"
    },
    "href": {
     "type": "string"
    }
   }
  },
  "tokenId": {
   "type": "string",
   "minLength": 15,
   "maxLength": 21,
   "pattern": "^[0-9A-HJ-NP-Z]+$"
  },
  "description": {
   "type": "string",
   "minLength": 1,
   "maxLength": 255,
   "pattern": "^[^&<]*$"
  },
  "tokenExpiryDateTime": {
   "type": "string",
   "format": "date-time"
  },
  "namespace": {
   "type": "string",
   "minLength": 1,
   "maxLength": 64
  },
  "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"
     ]
    },
    "bin": {
     "type": "string",
     "minLength": 6,
     "maxLength": 6,
     "pattern": "\\d{6}"
    },
    "brand": {
     "type": "string",
     "minLength": 1,
     "maxLength": 255
    },
    "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",
    "bin",
    "brand"
   ]
  },
  "_links": {
   "type": "object",
   "format": "hal+json"
  }
 },
 "required": [
  "tokenPaymentInstrument",
  "description",
  "tokenExpiryDateTime",
  "paymentInstrument",
  "_links"
 ]
}

Headers

NameDescription
LocationAn URI identifying the conflicting Token resource.

Response schema

Copied!
{
 "type": "object",
 "properties": {
  "tokenPaymentInstrument": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string"
    },
    "href": {
     "type": "string"
    }
   }
  },
  "tokenId": {
   "type": "string",
   "minLength": 15,
   "maxLength": 21,
   "pattern": "^[0-9A-HJ-NP-Z]+$"
  },
  "description": {
   "type": "string",
   "minLength": 1,
   "maxLength": 255,
   "pattern": "^[^&<]*$"
  },
  "tokenExpiryDateTime": {
   "type": "string",
   "format": "date-time"
  },
  "namespace": {
   "type": "string",
   "minLength": 1,
   "maxLength": 64
  },
  "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"
     ]
    },
    "bin": {
     "type": "string",
     "minLength": 6,
     "maxLength": 6,
     "pattern": "\\d{6}"
    },
    "brand": {
     "type": "string",
     "minLength": 1,
     "maxLength": 255
    },
    "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",
    "bin",
    "brand"
   ]
  },
  "conflicts": {
   "type": "object",
   "properties": {
    "paymentInstrument": {
     "type": "object",
     "properties": {
      "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"
       ]
      }
     }
    },
    "schemeTransactionReference": {
     "type": "string"
    }
   }
  },
  "_links": {
   "type": "object",
   "format": "hal+json"
  }
 },
 "required": [
  "tokenPaymentInstrument",
  "tokenId",
  "description",
  "tokenExpiryDateTime",
  "paymentInstrument",
  "conflicts",
  "_links"
 ]
}

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. 
GET https://try.access.worldpay.com/tokens
Copied!
{
  "Accept": "application/vnd.worldpay.tokens-v2.hal+json"
}