Last Updated: 18 May 2023 | Change Log

Querying Network Tokens and Provisioning Cryptograms

Proceed to network token inquiry if you do not receive a network token, else proceed to provisioning a cryptogram.

Network token inquiry

If you do not receive a tokenNumber , send a GET request to the tokens:networkTokenLookup action link returned in the response of your create a network token request

Network token inquiry request

GET https://try.access.worldpay.com/tokens/network/E9026BB9-0FD3-47C9-A088-17A68BF07659

Note

No request body is needed for this request.

Response

The response status is 200 OK. You receive links to your next available actions in your response.

{
  "tokenPaymentInstrument": {
    "status": "Active",
    "type": "card/networkToken",
    "tokenNumber": "4111111111111111",
    "expiryDate": {
      "month": 12,
      "year": 2025
    }
  },
  "paymentInstrument": {
    "type": "card/masked",
    "firstSix": "411111",
    "lastFour": "1111",
    "cardExpiryDate": {
      "month": 12,
      "year": 2025
    },
    "paymentAccountReference": "41111111111111111111111111111"
  },
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/tokens/network/0b56de37-22b3-4422-a791-ae9550df1db0"
    },
    "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
tokenPaymentInstrumentAn object that contains the network token details.
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.
paymentInstrumentAn object that contains the payment card 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.
paymentInstrument.cardExpiryDate.monthCard expiry month.
paymentInstrument.cardExpiryDate.yearCard expiry year.
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.

Provisioning network token cryptograms

Once you receive the tokenNumber, provision a cryptogram to take a card on file payment. A cryptogram contains transaction specific information.

Note

Cryptograms are single use and valid for 24 hours.

To provision a network token cryptogram , POST your request to the tokens:networkTokenCryptogram action link. POST https://try.access.worldpay.com/tokens/network/cryptograms

Request

{
  "tokenNumber": "4111111111111111"
}
ParameterRequiredDescription
tokenNumber16 digits network token number provisioned via card schemes.

Response

{
  "cryptogramDetails": {
    "cryptogram": "AgAAAAAASFh+gDRt/rq8QOkAAAA=",
    "eci": "07"
  },
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/tokens/network/cryptograms"
    },
    "tokens:networkTokenLookup": {
      "href": "https://try.access.worldpay.com/tokens/network/{tokenReference}",
      "templated": true
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/tokens/{rel}.json",
        "name": "tokens",
        "templated": true
      }
    ]
  }
}
ParameterDescription
cryptogramDetailsContains the details of the new cryptogram.
cryptogramDetails.cryptogramThe value for the cryptogram. Depending on the type of network token used, you can expect to receive a cryptogram in one of the following formats:
  • UCAF cryptogram: Base64 encoded and up to 32 characters in length
  • ICC cryptogram: Hex encoded and up to 512 characters in length
  • TAVV cryptogram: Base64 encoded and up to 28 characters in length
cryptogramDetails.eciElectronic Commerce Indicator (ECI). Indicates the outcome of the cryptogram provisioning. Possible values:
  • Mastercard - 02, 01
  • Visa - 05, 06, 07
Note

You can use the network tokens created with Access Worldpay across other providers or gateways.

Next steps


Take a payment using cryptogram