**Last updated**: 12 May 2025 | [**Change log**](/products/tokens/changelog/) # 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: Card ```json { "paymentInstrument": { "cardHolderName": "name", "type": "card/front", "cardExpiryDate": { "month": 1, "year": 2030 }, "cardNumber": "4444333322221111" }, "merchant": { "entity": "default" } } ``` Token ```json { "merchant" : { "entity": "default" }, "paymentInstrument": { "type": "card/tokenized", "href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoia0gvT2xpdDV3WnpOZG1GTWpwemtXckVkRHdJSjFNQzR5VkE5NHhYUldzYz0ifQ" } } ``` 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 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: * an HTTP code `200` * `tokenReference` * `tokenPaymentInstrument` object which contains network `tokenNumber` * links to [query a network token](/products/tokens/query-network-tokens-and-provision-cryptograms#network-token-inquiry) and [provision a network token cryptogram](/products/tokens/query-network-tokens-and-provision-cryptograms#provision-network-token-cryptograms) For an asynchronous network token creation, you receive: * an HTTP code `200` * `tokenReference` * link to [query a network token](/products/tokens/query-network-tokens-and-provision-cryptograms#network-token-inquiry) For more information about provisioning errors, please see [Network token error responses](/products/tokens/network-token-errors). #### Example response With network token ```json { "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 } ] } } ``` Without network token ```json { "tokenReference": "aa224320-425c-40b6-9781-2cb7df76b0c8", "paymentInstrument": { "type": "card/masked", "firstSix": "444433", "lastFour": "1111", "cardExpiryDate": { "month": 1, "year": 2030 }, "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_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" }, "curies": [ { "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json", "name": "tokens", "templated": true } ] } } ``` Provisioning error ```json { "paymentInstrument":{ "type":"card/masked", "firstSix":"555544", "lastFour":"4444", "cardExpiryDate":{ "month":5, "year":2035 }, "paymentAccountReference":"900999AB1N1T9G3ABC0XYZ3HVY4AW" }, "provisioningErrors":[ { "errorCode":"301", "providerErrorCode":"DECLINED", "source":"A2T Mastercard NPT Token Provider Service", "context":"Provision Token.Processor Error", "message":"Provider error occurred : DECLINED" } ], "_links":{} } ``` | Parameter | Description | | --- | --- | | `tokenReference` | A reference to get the `tokenNumber` with `tokens:networkTokenLookup`. | | `paymentInstrument` | An object that contains the payment `type` and details. | | `paymentInstrument.type` | An identifier for the `paymentInstrument` being used, e.g. `card/masked` | | `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. | | `paymentInstrument.paymentAccountReference` | The 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. | | `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. 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.month` | Expiry month of the network token. | | `tokenPaymentInstrument.expiryDate.year` | Expiry year of the network token. | | `provisioningErrors.errorCode` | Worldpay's representation of the error code. | | `provisioningErrors.providerErrorCode` | The error code returned from the card schemes. | | `provisioningErrors.source` | Where the error occurred. | | `provisioningErrors.context` | Context of the error. | | `provisioningErrors.message` | Greater description of the error. | **Next steps** [Query a network token](/products/tokens/query-network-tokens-and-provision-cryptograms#network-token-inquiry) or [Provision a network token cryptogram](/products/tokens/query-network-tokens-and-provision-cryptograms#provision-network-token-cryptograms) or [Delete a network token](/products/tokens/query-network-tokens-and-provision-cryptograms#delete-network-tokens)