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 and Mastercard are currently supported. American Express and Discover will be supported in 2023.

Create a network token request

To create a network token, POST your request to the tokens:networkToken action link returned in your query the tokens root resource response.

Create a network token example request

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

Network token creation request body:

Card
Token

{
  "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

With network token
Without network token

{
  "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`	The status of the network token. Possible values are Active, Inactive and Suspended.
`tokenPaymentInstrument.type`	Should always be `card/networkToken` to indicate that this is a network token.
`tokenPaymentInstrument.tokenNumber`	A 16 digit network token number. This is the actual network token.
`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

Create a Network Token

Create a network token request

Create a network token example request

Responses

Example response

Was this helpful?