Last updated: 23 April 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.

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:

Parameter	Required	Description
`merchant`	✅	An object that contains information about your merchant account.
`merchant.entity`	✅	Identifies merchant account for billing, reporting and reconciliation. Contact your 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 as synchronous network token creations.

For a synchronous network token creation, you receive:

an HTTP code 200
tokenReference
tokenPaymentInstrument object which contains network tokenNumber
links to query a network token and provision a network token cryptogram

For an asynchronous network token creation, you receive:

an HTTP code 200
tokenReference
link to query a network token

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
      }
    ]
  }
}

Parameter	Description
`tokenReference`	A reference to get the `tokenNumber` with `tokens:networkTokenLookup`.
`paymentInstrument`	An object that contains the payment `type` and details.
`paymentInstrument.firstSix`	First six digits of your customer's card number.
`paymentInstrument.lastFour`	Last four digits of your customer's card number.
`paymentInstrument.cardExpiryDate`	An object that contains your customer's card expiry date.
`tokenPaymentInstrument`	An 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.type`	Should always be `card/networkToken` to indicate that this is a network token.
`tokenPaymentInstrument.tokenNumber`	A network token with the same length as the card number it masks.
`tokenPaymentInstrument.expiryDate`	Expiry date of the network token.
`tokenPaymentInstrument.expiryDate.month`	Expiry month of the network token.
`tokenPaymentInstrument.expiryDate.year`	Expiry year of the network token.
`tokenPaymentInstrument.paymentAccountReference`	Also 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 or
Delete a network token

Create a network token

Create a network token request

Create a network token example request

Responses

Example response

Do you like our page?