# Create a new token

Create a new token for the payment instrument.

Endpoint: POST /tokens
Version: 3
Security: BasicAuth

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

  - `paymentInstrument` (object, required) — one of (discriminator: type):
    - card/front:
      - `type` (any)
        Enum: "card/front"
      - `cardHolderName` (string)
        The name on your customer's card.
      - `cardExpiryDate` (object)
        Contains your customer's card expiry date.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardNumber` (string)
        Contains your customer's card number.
      - `billingAddress` (object)
        Contains the billing address information.
      - `billingAddress.address1` (string, required)
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.city` (string, required)
      - `billingAddress.countryCode` (string, required)
      - `billingAddress.address2` (string)
      - `billingAddress.address3` (string)
      - `billingAddress.state` (string)
    - card/networkToken:
      - `type` (any)
        Enum: "card/networkToken"
      - `expiryDate` (object)
        The expiry date of the network token.
      - `expiryDate.month` (integer, required)
      - `expiryDate.year` (integer, required)
      - `tokenNumber` (string)
        The network token number.
    - card/networkToken+applepay:
      - `type` (any)
        Enum: "card/networkToken+applepay"
      - `expiryDate` (object)
        The expiry date of the network token.
      - `expiryDate.month` (integer, required)
      - `expiryDate.year` (integer, required)
      - `tokenNumber` (string)
        The network token number.
    - card/networkToken+googlepay:
      - `type` (any)
        Enum: "card/networkToken+googlepay"
      - `expiryDate` (object)
        The expiry date of the network token.
      - `expiryDate.month` (integer, required)
      - `expiryDate.year` (integer, required)
      - `tokenNumber` (string)
        The network token number.
    - card/networkToken+samsungpay:
      - `type` (any)
        Enum: "card/networkToken+samsungpay"
      - `expiryDate` (object)
        The expiry date of the network token.
      - `expiryDate.month` (integer, required)
      - `expiryDate.year` (integer, required)
      - `tokenNumber` (string)
        The network token number.

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

  - `merchant.entity` (string, required)
    Identifies merchant account for billing, reporting and reconciliation. Contact your Worldpay Implementation Manager for more details.

  - `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 90 days in Try and 4 years in the Live environment.We extend the expiry in Live by 4 years, if under half of the time remains on the token.

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

  - `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 200 fields (application/vnd.worldpay.tokens-v3.hal+json):

  - `tokenPaymentInstrument` (object)

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

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

  - `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'.

  - `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 90 days in Try and 4 years in the Live environment.We extend the expiry in Live by 4 years, if under half of the time remains on the token.

  - `namespace` (string)
    A reference to group up to 16 cards, e.g. for one customer.

  - `paymentInstrument` (object) — one of (discriminator: type):
    - card/front:
      - `type` (any)
        Enum: same as `type` in "card/front" (1 values)
      - `cardHolderName` (string)
        The name on your customer's card.
      - `cardExpiryDate` (object)
        Contains your customer's card expiry date.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardNumber` (string)
        Contains your customer's card number.
      - `billingAddress` (object)
        Contains the billing address information.
      - `billingAddress.address1` (string, required)
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.city` (string, required)
      - `billingAddress.countryCode` (string, required)
      - `billingAddress.address2` (string)
      - `billingAddress.address3` (string)
      - `billingAddress.state` (string)
    - card/masked:
      - `type` (string)
      - `cardNumber` (string, required)
      - `cardExpiryDate` (object, required)
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardHolderName` (string)
        The name on your customer's card.
      - `bin` (string)
      - `brand` (string)
      - `fundingType` (string)
      - `countryCode` (string)
      - `billingAddress` (object)
        Contains the billing address information.
      - `billingAddress.address1` (string, required)
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.city` (string, required)
      - `billingAddress.countryCode` (string, required)
      - `billingAddress.address2` (string)
      - `billingAddress.address3` (string)
      - `billingAddress.state` (string)
      - `networkType` (string)
      - `last4Digits` (string)
    - card/network+masked:
      - `type` (string)
      - `cardNumber` (string, required)
        This is the token number provided in the tokenNumber field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate` (object, required)
        This is the token expiry date provided in the expiryDate field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `brand` (string)
      - `networkType` (string)
        The network behind the token, such as GOOGLEPAY or APPLEPAY.
      - `last4Digits` (string)
        Last 4 digits of the tokenNumber.

  - `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.

  - `_links` (object, required)

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

  - `tokenPaymentInstrument` (object, required)

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

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

  - `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'.

  - `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 90 days in Try and 4 years in the Live environment.We extend the expiry in Live by 4 years, if under half of the time remains on the token.

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

  - `paymentInstrument` (object, required) — one of (discriminator: type):
    - card/masked:
      - `type` (string)
      - `cardNumber` (string, required)
      - `cardExpiryDate` (object, required)
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardHolderName` (string)
        The name on your customer's card.
      - `bin` (string)
      - `brand` (string)
      - `fundingType` (string)
      - `countryCode` (string)
      - `billingAddress` (object)
        Contains the billing address information.
      - `billingAddress.address1` (string, required)
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.city` (string, required)
      - `billingAddress.countryCode` (string, required)
      - `billingAddress.address2` (string)
      - `billingAddress.address3` (string)
      - `billingAddress.state` (string)
      - `networkType` (string)
      - `last4Digits` (string)
    - card/network+masked:
      - `type` (string)
      - `cardNumber` (string, required)
        This is the token number provided in the tokenNumber field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate` (object, required)
        This is the token expiry date provided in the expiryDate field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `brand` (string)
      - `networkType` (string)
        The network behind the token, such as GOOGLEPAY or APPLEPAY.
      - `last4Digits` (string)
        Last 4 digits of the tokenNumber.

  - `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.

  - `_links` (object, required)

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

  - `errorName` (string)
    Example: "bodyDoesNotMatchSchema"

  - `message` (string)
    Example: "The json body provided does not match the expected schema"

  - `validationErrors` (array)
    Further error details

  - `validationErrors.errorName` (string)
    Example: "fieldHasInvalidValue"

  - `validationErrors.message` (string)
    Example: "Card expiry month too small - must be between 1 & 12"

  - `validationErrors.jsonPath` (string)
    Example: "$.paymentInstrument.cardExpiryDate.month"

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

  - `errorName` (string)
    Example: "tooManyTokensForNamespace"

  - `message` (string)
    Example: "Too many tokens created for this namespace"

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

  - `tokenPaymentInstrument` (object, required)

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

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

  - `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'.

  - `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 90 days in Try and 4 years in the Live environment.We extend the expiry in Live by 4 years, if under half of the time remains on the token.

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

  - `paymentInstrument` (object, required) — one of (discriminator: type):
    - card/masked:
      - `type` (string)
      - `cardNumber` (string, required)
      - `cardExpiryDate` (object, required)
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardHolderName` (string)
        The name on your customer's card.
      - `bin` (string)
      - `brand` (string)
      - `fundingType` (string)
      - `countryCode` (string)
      - `billingAddress` (object)
        Contains the billing address information.
      - `billingAddress.address1` (string, required)
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.city` (string, required)
      - `billingAddress.countryCode` (string, required)
      - `billingAddress.address2` (string)
      - `billingAddress.address3` (string)
      - `billingAddress.state` (string)
      - `networkType` (string)
      - `last4Digits` (string)
    - card/network+masked:
      - `type` (string)
      - `cardNumber` (string, required)
        This is the token number provided in the tokenNumber field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate` (object, required)
        This is the token expiry date provided in the expiryDate field in the request. This response field will be renamed in future versions.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `brand` (string)
      - `networkType` (string)
        The network behind the token, such as GOOGLEPAY or APPLEPAY.
      - `last4Digits` (string)
        Last 4 digits of the tokenNumber.

  - `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.

  - `conflicts` (object)

  - `conflicts.conflictsExpiryDateTime` (string)

  - `conflicts.paymentInstrument` (object)

  - `conflicts.paymentInstrument.cardHolderName` (string)

  - `conflicts.paymentInstrument.cardExpiryDate` (object)

  - `conflicts.paymentInstrument.cardExpiryDate.month` (integer)

  - `conflicts.paymentInstrument.cardExpiryDate.year` (integer)

  - `conflicts.paymentInstrument.billingAddress` (object)

  - `conflicts.paymentInstrument.billingAddress.address1` (string)

  - `conflicts.paymentInstrument.billingAddress.postalCode` (string)

  - `conflicts.paymentInstrument.billingAddress.city` (string)

  - `conflicts.paymentInstrument.billingAddress.countryCode` (string)

  - `conflicts.paymentInstrument.billingAddress.address2` (string)

  - `conflicts.paymentInstrument.billingAddress.address3` (string)

  - `conflicts.paymentInstrument.billingAddress.state` (string)

  - `conflicts.schemeTransactionReference` (string)

  - `_links` (object, required)

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

  - `errorName` (string)
    Example: "unrecognizedCardBrand"

  - `message` (string)
    Example: "The card brand is not recognized"

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

  - `errorName` (string)
    Example: "tokenizationNotEnabled"

  - `message` (string)
    Example: "Tokenization not enabled"