Menu

Querying Network Tokens and Provisioning Cryptograms

API v3
Last updated March 2023
Change log

Proceed tonetwork token inquiryif you do not receive a network token, else proceed toprovisioning 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 yourcreate a network token request

Note: While creating a network token via Mastercard, you may not receive the tokenNumber immediately. In that case, you must send requests to thetokens:networkTokenLookupaction link for up to 5 minutes while the network token is being created.

Network token inquiry request

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

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.

Copied!
{
  "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
    }
  },
  "_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.statusStatus of the network token. Possible values: Active, Inactive and Suspended.
tokenPaymentInstrument.typeShould always be card/networkToken to indicate that this is a network token.
tokenPaymentInstrument.tokenNumberA 16 digit network token number.
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.

Provisioning network token cryptograms

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

Note: Cryptograms provisioned through Visa are valid for 24 hours and those provisioned through Mastercard are valid for 72 hours.

To provision a network token cryptogram , POST your request to thetokens:networkTokenCryptogramaction link returned in yourquery on the tokens root resourceresponse.

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

Request

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

Response

Copied!
{
  "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 such as Worldwide payment gateway (WPG).

Next steps

Take a payment using cryptogram