# Create a new token

Creating a new token for the payment instrument.

Endpoint: POST /tokens
Version: 1
Security: BasicAuth

## Request fields (application/vnd.worldpay.tokens-v1.hal+json):

  - `description` (string)
    A description of your token. If not supplied, a default description is created for you.

  - `tokenExpiryDateTime` (string)
    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.

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

  - `schemeTransactionReference` (string)
    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](/products/verified-tokens/@v3/index.md) to create tokens, it is automatically included where applicable.

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

  - `paymentInstrument.type` (string)
    card/front

  - `paymentInstrument.cardHolderName` (string)
    The name on the customer's card.

  - `paymentInstrument.cardExpiryDate` (object)

  - `paymentInstrument.cardExpiryDate.month` (integer, required)

  - `paymentInstrument.cardExpiryDate.year` (integer, required)

  - `paymentInstrument.cardNumber` (string)
    Contains your customer's card number.

  - `paymentInstrument.billingAddress` (object)
    Contains the billing address information.

  - `paymentInstrument.billingAddress.address1` (string, required)

  - `paymentInstrument.billingAddress.postalCode` (string, required)

  - `paymentInstrument.billingAddress.city` (string, required)

  - `paymentInstrument.billingAddress.countryCode` (string, required)

  - `paymentInstrument.billingAddress.address2` (string)

  - `paymentInstrument.billingAddress.address3` (string)

  - `paymentInstrument.billingAddress.state` (string)

  - `merchant` (object, required)
    An object that contains information about your merchant account.

## Response 200 fields (application/vnd.worldpay.tokens-v1.hal+json):

  - `tokenPaymentInstrument` (object, required)

  - `tokenPaymentInstrument.type` (string)

  - `tokenPaymentInstrument.href` (string)

  - `description` (string, required)
    A description of your token. If not supplied, a default description is created for you.

  - `tokenExpiryDateTime` (string, 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.

  - `paymentInstrument` (object, required)

  - `paymentInstrument.cardNumber` (string, required)
    Contains your customer's card number.

  - `paymentInstrument.cardExpiryDate` (object, required)

  - `paymentInstrument.cardExpiryDate.month` (integer, required)

  - `paymentInstrument.cardExpiryDate.year` (integer, required)

  - `paymentInstrument.cardHolderName` (string)
    The name on the customer's card.

  - `paymentInstrument.billingAddress` (object)
    Contains the billing address information.

  - `paymentInstrument.billingAddress.address1` (string, required)

  - `paymentInstrument.billingAddress.postalCode` (string, required)

  - `paymentInstrument.billingAddress.city` (string, required)

  - `paymentInstrument.billingAddress.countryCode` (string, required)

  - `paymentInstrument.billingAddress.address2` (string)

  - `paymentInstrument.billingAddress.address3` (string)

  - `paymentInstrument.billingAddress.state` (string)

  - `paymentInstrument.networkType` (string)

  - `paymentInstrument.last4Digits` (string)

  - `tokenId` (string)

  - `namespace` (string)

  - `schemeTransactionReference` (string)
    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](/products/verified-tokens/@v3/index.md) to create tokens, it is automatically included where applicable.

## Response 201 fields (application/vnd.worldpay.tokens-v1.hal+json):

  - `tokenPaymentInstrument` (object, required)

  - `tokenPaymentInstrument.type` (string)
    Indicating the type of this token.

  - `tokenPaymentInstrument.href` (string)
    Link to the corresponding token.

  - `description` (string, required)
    A description of your token. If not supplied, a default description is created for you.

  - `tokenExpiryDateTime` (string, 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.

  - `paymentInstrument` (object, required)

  - `paymentInstrument.cardNumber` (string, required)

  - `paymentInstrument.cardExpiryDate` (object, required)

  - `paymentInstrument.cardExpiryDate.month` (integer, required)

  - `paymentInstrument.cardExpiryDate.year` (integer, required)

  - `paymentInstrument.type` (string)

  - `paymentInstrument.cardHolderName` (string)
    The name on the customer's card.

  - `paymentInstrument.billingAddress` (object)

  - `paymentInstrument.billingAddress.address1` (string, required)

  - `paymentInstrument.billingAddress.postalCode` (string, required)

  - `paymentInstrument.billingAddress.city` (string, required)

  - `paymentInstrument.billingAddress.countryCode` (string, required)

  - `paymentInstrument.billingAddress.address2` (string)

  - `paymentInstrument.billingAddress.address3` (string)

  - `paymentInstrument.billingAddress.state` (string)

  - `paymentInstrument.networkType` (string)

  - `paymentInstrument.last4Digits` (string)

  - `tokenId` (string)
    Worldpay'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'.

  - `namespace` (string)
    The 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 '<'.

  - `schemeTransactionReference` (string)
    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](/products/verified-tokens/@v3/index.md) to create tokens, it is automatically included where applicable.

## Response 409 fields (application/vnd.worldpay.tokens-v1.hal+json):

  - `tokenPaymentInstrument` (object, required)

  - `tokenPaymentInstrument.type` (string)
    Indicating the type of this token.

  - `tokenPaymentInstrument.href` (string)
    Link to the corresponding token.

  - `description` (string, required)
    A description of your token. If not supplied, a default description is created for you.

  - `tokenExpiryDateTime` (string, 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.

  - `paymentInstrument` (object, required)

  - `paymentInstrument.cardNumber` (string, required)

  - `paymentInstrument.cardExpiryDate` (object, required)

  - `paymentInstrument.cardExpiryDate.month` (integer, required)

  - `paymentInstrument.cardExpiryDate.year` (integer, required)

  - `paymentInstrument.type` (string)

  - `paymentInstrument.cardHolderName` (string)
    The name on the customer's card.

  - `paymentInstrument.billingAddress` (object)

  - `paymentInstrument.billingAddress.address1` (string, required)

  - `paymentInstrument.billingAddress.postalCode` (string, required)

  - `paymentInstrument.billingAddress.city` (string, required)

  - `paymentInstrument.billingAddress.countryCode` (string, required)

  - `paymentInstrument.billingAddress.address2` (string)

  - `paymentInstrument.billingAddress.address3` (string)

  - `paymentInstrument.billingAddress.state` (string)

  - `paymentInstrument.networkType` (string)

  - `paymentInstrument.last4Digits` (string)

  - `paymentInstrument.tokenId` (string)
    Worldpay'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'.

  - `paymentInstrument.namespace` (string)
    The 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 '<'.

  - `paymentInstrument.schemeTransactionReference` (string)
    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](/products/verified-tokens/@v3/index.md) to create tokens, it is automatically included where applicable.