Skip to main content
optimization protection

Request a token

This page describes how to request a Network or Safetech token for a payment instrument, and retrieve the token status and state information, token and card metadata details, and token asset details. 

Before you begin

Familiarize yourself with Network tokenization and Safetech tokenization.

Required information

Before you proceed with requesting a network token, ensure that the following fields are present in your request body for card tokenization: 

Required and conditionally-required fields for card tokenization by card brand
Payment brand Required field Conditional fields
Visa
  • AccountholderEmail 
  • accountholderReference 
  • cardNumber 
  • cardExpiry 
  • deviceLocale 
  
Mastercard
  • cardNumber
  • cardExpiry
  
American Express
  • cardNumber
  • cardExpiry

One of the following fields must be provided:

  • accountholderEmail or accountholderTelephone
  • deviceIPAddress - required when cardSource field is not ONFILE.

Request a network token

Request a network token by performing a POST call to the /tokens endpoint. 

HTTP method: POST
Endpoint: /tokens

Json
{
    "device": {
        "deviceType": "PHONE",
        "deviceIPAddress": "127.0.0.1",
        "deviceLocale": "en-US",
        "deviceLatLong": "40, -73",
        "deviceMake": "Samsung",
        "deviceOS": "ANDROID",
        "deviceOsVersion": "12",
        "digitalDeviceIdentifier": "ahd896384d",
        "deviceGeoLocationCaptureTimestamp": "2021-09-08T21:01:20.945Z",
        "deviceName": "Samsung_Android",
        "walletId": "123"
    },
    "accountInformation": {
        "accountholderName": "John Doe",
        "accountholderEmail": "test@test.com",
        "accountType": "GUEST",
        "accountHolderReference": "e5ad0fd0-4f92-4df",
        "cardNumber": "5204740000001002",
        "billingAddress": {
            "addressLine1": "7825 N MacArthur Blvd",
            "addressLine2": "Lewisville Mall",
            "city": "Irving",
            "stateProvince": "TX",
            "postalCode": "72638",
            "countryCode": "US"
        },
        "cardExpiry": {
            "month": 11,
            "year": 2022
        },
        "cardSource": "KEY_ENTERED",
        "cardVerificationNumber": "325"
    },
    "riskInformation": {
        "walletRisk": {
            "walletScore": 15,
            "walletUsageLength": 94,
            "walletTransactions": 35,
            "walletNameMatch": true
        },
        "cardRisk": {
            "cardScore": 23,
            "cardUsageLength": 249
        },
        "deviceRisk": {
            "deviceScore": 19,
            "deviceUsageLength": 193,
            "deviceTokenCount": 2,
            "deviceCountry": "US"
        },
        "userRisk": {
            "userScore": 38,
            "userUsageLength": 49,
            "userTokenCount": 2,
            "userWalletCount": 1,
            "userCountry": "US",
            "newUserAccount": false,
            "onFileTime": 37
        }
    },
    "presentationModes": [
        "ECOM"
    ],
    "recommendationPath": "APPROVED"
}

Response:

Json
{
    "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08",
    "timestamp": "2021-09-15T19:08:19.097",
    "tokenInformation": {
        "tokenNumber": "5000010000000019",
        "expiry": {
            "month": 11,
            "year": 2022
        },
        "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
        "tokenizationApprovalStatus": "APPROVED",
        "cardReferenceNumber": "73ebcc62-56c0-41d2-b70a-4ede8cd700ff",
        "cardTokenStatus": "ACTIVE",
        "cardLast4Digits": "1002",
        "cardBrand": "MASTERCARD"
    },
    "cardMetaData": {
        "cardArtUrl": "http://cardArtUrl.com",
        "backgroundCardGraphicsColor": "#000000",
        "foregroundCardGraphicsColor": "#FFFFFF",
        "labelCardGraphicsColor": "#C0C0C0",
        "cardDescription": "The Bank Chase Card",
        "issuerInformation": {
            "cardIssuer": "Bank Example",
            "cardIssuerEmailAddress": "bank@example.com",
            "issuerWebsiteURL": "bank.com",
            "cardIssuerCustomerServiceTelephone": "400800393",
            "issuerOnlineBankingURL": "onlinebanking.com",
            "issuerIconURL": "http://logo.png",
            "issuerPrivacyURLText": "privacypolicybank.com",
            "issuerLogoURLText": "banklogo.com",
            "issuerApplicationOS": "IOS",
            "issuerAppName": "bankmobileapp",
            "issuerAppAddress": "com.bank.appname"
        },
        "cardShortDescription": "The Bank Card",
        "cardTermsAndConditionsIdentifier": "37629726-58cf-4fbb-a2bd-457614704be4",
        "cardTermsAndConditionsURL": "http://termsAndConditionsUrl.com",
        "cardAssetData": [
            {
                "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
                "assetType": "ICON_ISSUER",
                "mimeType": "IMAGE/PNG",
                "pixelHeight": 100,
                "pixelWidth": 100
            }
        ]
    },
    "requestIdentifier": "276ac797-8754-4ab8-a0b7-87da568e4d6d",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "The request is well received"
}

Request a Safetech token

Request a network token by performing a POST call to the /acquirertokens endpoint.

HTTP method: POST
Endpoint: /acquirertokens

Json
{
    "accountInformation": {
        "cardNumber": "379296848452209002",
        "cardSource": "KEY_ENTERED"
    }
}

Response:

Json
{
"identifier": "5bc5f837-b772-48f3-ad29-32fcdfe368ff",
"tokenInformation": {
     "acquirerTokenNumber": "379296576034739002"
  },
"responseStatus": "SUCCESS",
"responseCode": "ACCEPTED",
"responseMessage": "Request Accepted"
}

Retrieve token information

Retrieve a token’s status and state information by performing a GET call to the /tokens/{token-reference-id} endpoint.

HTTP method: GET
Endpoint: /tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98

Json
{
  "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98",
  "timestamp": "2021-09-15T19:52:48.801",
  "paymentInstrument": {
    "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
    "cardTokenStatus": "ACTIVE",
    "stateChangeReason": "RESUME",
    "statusChangeTimestamp": "2021-09-15T19:52:48.801"
  },
  "requestIdentifier": "10cc0270-7bed-11e9-a188-1763956dd7f6",
  "responseStatus": "SUCCESS",
  "responseCode": "ACCEPTED",
  "responseMessage": "The request is well received."
}

Retrieve token details

Retrieve the token and card metadata information in detail by performing a GET call to the /tokens/{token-reference-id}/details endpoint.

HTTP method: GET
Endpoint: /tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88/details

Json
{
    "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08",
    "timestamp": "2022-09-09T19:08:19.097",
    "tokenInformation": {
        "tokenNumber": "340000000001000",
        "expiry": {
            "month": 11,
            "year": 2022
        },
        "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
        "tokenizationApprovalStatus": "APPROVED",
        "cardReferenceNumber": "73ebcc62-56c0-41d2-b70a-4ede8cd700ff",
        "cardTokenStatus": "ACTIVE",
        "cardLast4Digits": "0001",
        "cardBrand": "VISA"
    },
    "cardMetaData": {
        "cardArtUrl": "http://cardArtUrl.com",
        "backgroundCardGraphicsColor": "#000000",
        "foregroundCardGraphicsColor": "#FFFFFF",
        "labelCardGraphicsColor": "#C0C0C0",
        "cardDescription": "The Bank Chase Card",
        "issuerInformation": {
            "cardIssuer": "Bank Example",
            "cardIssuerEmailAddress": "bank@example.com",
            "issuerWebsiteURL": "bank.com",
            "cardIssuerCustomerServiceTelephone": "400800393",
            "issuerOnlineBankingURL": "onlinebanking.com",
            "issuerIconURL": "http://logo.png",
            "issuerPrivacyURLText": "privacypolicybank.com",
            "issuerLogoURLText": "banklogo.com",
            "issuerApplicationOS": "IOS",
            "issuerAppName": "bankmobileapp",
            "issuerAppAddress": "com.bank.appname"
        },
        "cardShortDescription": "The Bank Card",
        "cardTermsAndConditionsIdentifier": "37629726-58cf-4fbb-a2bd-457614704be4",
        "cardTermsAndConditionsURL": "http://termsAndConditionsUrl.com",
        "cardAssetData": [
            {
                "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
                "assetType": "ICON_ISSUER",
                "mimeType": "IMAGE/PNG",
                "pixelHeight": 100,
                "pixelWidth": 100
            }
        ]
    },
    "requestIdentifier": "276ac797-8754-4ab8-a0b7-87da568e4d6d",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "The request is well received"
}

Retrieve token asset details

Retrieve token asset details containing information about the card art by performing a GET call to the /tokens/{token-reference-id}/assets/{asset-reference-id} endpoint.

HTTP method: GET
Endpoint: /tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88/assets/3801a454c0b84de883f5432815ded5f5

Json
{
    "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2022-09-11T15:25:35.950Z",
    "cardAssetData": [
        {
            "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
            "assetType": "ICON_ISSUER",
            "mineType": "IMAGE/PNG",
            "pixelHeight": 100,
            "pixelWidth": 100
        }
    ],
    "requestIdentifier": "10cc0270-7bed-11e9-a188-1763956dd7f6",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted"
}