Last Updated: 18 May 2023 | 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.

Visa, Mastercard, American Express and Discover are currently supported.

Create a network token request

To create a network token, POST your request to the tokens:networkToken action 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": 2050
    },
    "cardNumber": "4444333322221111"
  },
  "merchant": {
    "entity": "default"
  }
}

Description of your network token creation request parameters:

ParameterRequiredDescription
merchantAn object that contains information about your merchant account.
merchant.entityIdentifies merchant account for billing, reporting and reconciliation. Contact your Implementation Manager for more details.
paymentInstrumentAn object that contains the card details and token href.
paymentInstrument.typeAn identifier for the paymentInstrument being used.
  • type : card/front
  • type : card/tokenized
paymentInstrument.cardHolderNameYour customer's card name. This field can only be supplied with card/front payment instrument.
paymentInstrument.cardExpiryDateAn object that contains your customer's card expiry date. This field can only be supplied with card/front payment instrument.
paymentInstrument.cardNumberYour customer's 16 digit card number. This field can only be supplied with card/front payment instrument.
paymentInstrument.hrefA 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 as synchronous network token creations.

For a synchronous network token creation, you receive:

For an asynchronous network token creation, you receive:

Example response

{
  "tokenReference": "aa224320-425c-40b6-9781-2cb7df76b0c8",
  "paymentInstrument": {
    "type": "card/masked",
    "firstSix": "444433",
    "lastFour": "1111",
    "cardExpiryDate": {
      "month": 1,
      "year": 2050
    }
  },
  "tokenPaymentInstrument": {
    "status": "Active",
    "type": "card/networkToken",
    "tokenNumber": "4111111111111111",
    "expiryDate": {
      "month": 1,
      "year": 2050
    }
  },
  "_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.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.
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.
tokenPaymentInstrument.expiryDate.monthExpiry month of the network token.
tokenPaymentInstrument.expiryDate.yearExpiry year of the network token.
tokenPaymentInstrument.paymentAccountReferenceAlso known as PAR, an alphanumeric value up to 29 characters used to link a Payment Account (PAN) to a token associated with it.

Next steps


Query a network token or
Provision a network token cryptogram