Skip to content
APIs/Tokens/Create a network token

Last updated: 12 May 2025 | Change log

Create a network token

Create a network token via card schemes to replace your customer's sensitive card information. Use network tokens to improve payment authorization rates, gain built-in account updater and minimize fraud.

Supported schemes: Visa, Mastercard, American Express and Discover

Create a network token request

To create a network token:

POST your request to the tokens:networkToken request link.

Create a network token example request

POST https://try.access.worldpay.com/tokens/network

Network token creation request body:

{
  "paymentInstrument": {
    "cardHolderName": "name",
    "type": "card/front",
    "cardExpiryDate": {
      "month": 1,
      "year": 2030
    },
    "cardNumber": "4444333322221111"
  },
  "merchant": {
    "entity": "default"
  }
}

Description of your network token creation request parameters:

ParameterRequiredDescription
merchant✅An object that contains information about your merchant account.
merchant.entity✅Identifies merchant account for billing, reporting and reconciliation. Contact your Worldpay Implementation Manager for more details.
paymentInstrument✅An object that contains the card details and token href.
paymentInstrument.type✅An identifier for the paymentInstrument being used.
  • type : card/front
  • type : card/tokenized
paymentInstrument.cardHolderName❌Your customer's card name. This field can only be supplied with card/front payment instrument.
paymentInstrument.cardExpiryDate❌An object that contains your customer's card expiry date. This field can only be supplied with card/front payment instrument.
paymentInstrument.cardNumber❌Your customer's 16 digit card number. This field can only be supplied with card/front payment instrument.
paymentInstrument.href❌A link to your token. This field can only be supplied with card/tokenized payment instrument.

Responses

The majority of network token requests will include the network token in the response. These are referred to as synchronous network token creations.

For a synchronous network token creation, you receive:

For an asynchronous network token creation, you receive:

For more information about provisioning errors, please see Network token error responses.

Example response

{
  "tokenReference": "aa224320-425c-40b6-9781-2cb7df76b0c8",
  "paymentInstrument": {
    "type": "card/masked",
    "firstSix": "444433",
    "lastFour": "1111",
    "cardExpiryDate": {
      "month": 1,
      "year": 2030
    },
    "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E"
  },
  "tokenPaymentInstrument": {
    "status": "Active",
    "type": "card/networkToken",
    "tokenNumber": "4917610000000000",
    "expiryDate": {
      "month": 3,
      "year": 2030
    }
  },
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/tokens/network"
    },
    "tokens:networkTokenLookup": {
      "href": "https://try.access.worldpay.com/tokens/network/aa224320-425c-40b6-9781-2cb7df76b0c8"
    },
    "tokens:networkTokenCryptogram": {
      "href": "https://try.access.worldpay.com/tokens/network/cryptograms"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}
ParameterDescription
tokenReferenceA reference to get the tokenNumber with tokens:networkTokenLookup.
paymentInstrumentAn object that contains the payment type and details.
paymentInstrument.typeAn identifier for the paymentInstrument being used, e.g. card/masked
paymentInstrument.firstSixFirst six digits of your customer's card number.
paymentInstrument.lastFourLast four digits of your customer's card number.
paymentInstrument.cardExpiryDateAn object that contains your customer's card expiry date.
paymentInstrument.paymentAccountReferenceThe payment account reference (PAR) is a non-financial reference that uniquely identifies the underlying cardholder account. This allows you to correlate payments made from the same account with differing instruments (e.g. cards, network tokens, and wallets), where the same account funds the transaction. A PAR cannot be used to initiate a payment.
tokenPaymentInstrumentAn object that contains the details of the network token created.
tokenPaymentInstrument.status
  • Active - The token is valid and ready for use in transactions.

  • Suspended- The token is temporarily suspended, meaning you can't use it until it's reactivated (often due to fraud concerns or other security issues). If the card is reactivated, then the status would automatically change to Active.

  • Deleted - The token has been permanently deleted and you can no longer use it to take a payment. This could happen if the associated card is canceled or replaced.

  • Expired - The token has passed its expiration date and is no longer valid for use. This should not occur often as token expiries are automatically extended when cards are extended.
tokenPaymentInstrument.typeShould always be card/networkToken to indicate that this is a network token.
tokenPaymentInstrument.tokenNumberA network token with the same length as the card number it masks.
tokenPaymentInstrument.expiryDateExpiry date of the network token. This value is likely different to the expiry date of the underlying card that corresponds to the network token (found in paymentInstrument.cardExpiryDate). Include this value where you use this token in payment authorization requests.
tokenPaymentInstrument.expiryDate.monthExpiry month of the network token.
tokenPaymentInstrument.expiryDate.yearExpiry year of the network token.
provisioningErrors.errorCodeWorldpay's representation of the error code.
provisioningErrors.providerErrorCodeThe error code returned from the card schemes.
provisioningErrors.sourceWhere the error occurred.
provisioningErrors.contextContext of the error.
provisioningErrors.messageGreater description of the error.

Next steps

Query a network token or
Provision a network token cryptogram or
Delete a network token