ShieldConex® Network Tokens

📘

Large Enterprise Merchants and Payment Facilitators

ShieldConex® Orchestration and Network Token Service are common for large ISVs.

For merchants with smaller businesses, we recommend using the PayConex™ Set of APIs.

Overview

Network tokens are:

• Digital substitutes for sensitive card information used in payment processing. They enhance security by replacing card details with unique identifiers, reducing the risk of data breaches. Benefits include increased transaction security, reduced fraud, and streamlined online payment experiences.
• Used in mobile wallets, e-commerce transactions, and recurring payments, ensuring that sensitive card data is never exposed during transactions, thereby maintaining privacy and compliance with security standards.
• Able to receive updates from the card issuer, such as card reissues or expiration date changes, without requiring the cardholder to update their details. Payment Service Provider does not need account updater service for a network token. In other words, network tokens basically do not expire this way even if the cardholder changes the card information.

Network Token Support

To date, network tokens are used in roughly 30% of Visa and Mastercard transactions. ShieldConex combines Network Tokens with its own tokenization solution, allowing merchants to generate the most cost-effective token for each transaction—whether for security, routing flexibility, or downstream savings.

📘

Bluefin's ShieldConex®

ShieldConex® uses a system called vaultless tokenization.

For more information, see ShieldConex | Tokenization Explained and ShieldConex® Orchestration.

API Authentication

To authenticate with the ShieldConex API, please refer to the API Authentication.

Bluefin Network Token Service

Bluefin ShieldConex® incorporates its Network Token Service by providing a set of REST API endpoints that manage network tokens.

Merchants can use these endpoints either through individual Network Token API calls or ShieldConex Tokenization. Generating Network Tokens via ShieldConex Tokenization allows merchants to use ShieldConex payment tokens at the same time, which is especially useful if they switch to a different payment processor.

This approach streamlines the process, as Bluefin's Integration team handles the technical details, integration, and provides a ready-to-use integration.

In essence, ShieldConex Network Token Service handles the tokens on the merchant's behalf.

This can be illustrated in the following diagram:

1. The customer makes a purchase at the Point Of Sale systems maintained by the merchant. This can be a website, payment application, or similar.
2. The sensitive card data is sent to the ShieldConex Network Token Service to create a token.
   • During this step, the SCX tokenize call can be made so that the merchant also has ShieldConex tokens at their disposal and use ShieldConex ORCA during the step 5 in the diagram given that a certain payment processor does not support network tokens. For more details, see Overview | Network Token Support.
3. Then, the Network Token Service provisions the token with Network Token Providers based on the card issuer. ShieldConex stores the tokens for subsequent transactions.
4. The network token is returned to the POS for payment processing where the merchant gets the payment credentials with the network token identifier.
5. Payment Request with the network token payment credentials is made to the designated payment processor.
6. The network token and cryptogram are transmitted across the payment ecosystem.

🚧

Provision a Token

In order to use a token in a payment, provisioning the token is required with the networkTokenState of ACTIVE.

After provisioning a network token through the Network Token Provider, the merchant can use the network token for future transactions. Depending on the card issuer, the Network Token Provider can be Visa, Mastercard, or Amex.

Provisioning a network token involves requesting from a card network, like Visa or Mastercard, to generate a unique token representing a card's Primary Account Number (PAN). This token is then used in subsequent transactions instead of the actual PAN, enhancing security.

Integration Options

There are two ways the merchant can integrate with the Network Tokens.

• Template Configuration (as a field of the ShieldConex iFrame)

  • Card Information or Custom Field option

• ShieldConex REST API

  • Standalone NT API calls for managing Network Tokens
  • Recommended Approach
    • ShieldConex Tokenization & Network Tokens with Template Configuration in the case of switching to a different payment processor with ShieldConex tokens. ShieldConex tokens work with any processor, so there is no exporting and importing tokens when changing processors.
    • For more information, also see ShieldConex | Tokenization Explained and ShieldConex® Orchestration.
  • Widely adopted, Network Tokens enable secure processing of card-not-present (CNP) payments with the majority of payment processors.

Environment URLs

There are two ShieldConex environments each with their own URL.

All requests must be made over HTTPS for security. Append the endpoints described below to the appropriate base URL depending on whether you are testing or running in production.

For example, this is the full URL for creating a network token in the certification environment:

https://secure-cert.shieldconex.com/api/network-token

All preliminary development must be conducted and tested within the certification environment.

API Endpoint Overview

To use network tokens as a standalone solution, ShieldConex API offers the following endpoints.

If you want to use network tokens as part of ShieldConex solution, use the following endpoints.

📘

Recommended Approach

ShieldConex Tokenization & Network Tokens is the recommended approach.

Test Card Numbers

While you are certifying our ShieldConex Network Token Integration, use one of the following test cards based on the Network Token Provider (Card Brand).

Successful Network Token Provisioning

Use these test card numbers to provision network tokens. For Mastercard and Visa cards, replace the X in the card number with 0. For Mastercard cards, you can use any future date for the expiration date.

Unsuccessful Network Token Provisioning

Use these test card numbers to test unsuccessful provisioning of network tokens.

For American Express cards, replace the X in the PAN with a 0. For Visa cards, replace the X in the PAN with any number. You can use any future date for the expiration date.

Template Configuration

In order to use Network Tokens as part of ShieldConex solution via REST API or iFrame SDK, a template configuration must be referenced with FPT(Format Preserving Tokenization)+Network Token Data Protection Method as either Card Information or Custom Field.

Field Templates

Data Protection Method

Network Token Timeout

When a network token field is used in a ShieldConex template, there is a special setting that determines how long ShieldConex will wait for a Network Token response before returning only ShieldConex Tokens. This is due to the fact that the API call both creates and provisions a token and this timeout essentially sets a limit for those two actions.

It is also important to note that If Creating a Network Token fails, the ShieldConex tokens are included regardless of where the networkToken is dropped, as mentioned below.

Network Token API Logs

This section of the Portal is designed to help users monitor and troubleshoot network token (NT) operations. It provides detailed logs and insights into each tokenization request, making it easier to identify and analyze failures, timeouts, or irregular behavior. This is especially useful during integration, testing, or when investigating issues with production traffic involving network tokens. These can also be used for generating reports.

These operations are referred to Transactions including:

• Create Network Token
• Get Network Token
• Get Payment Credentials

Here is the sample API Logs table:

If we click on one of these items, we get the details of NT transaction like this:

Network Tokens API

🚧

scx-client-reference

This header is required for all the following API calls in this section. This is the Client ID tied to the Partner used for API Authentication.

This set of endpoints is used if the merchant exclusively uses network tokens and opts not to receive ShieldConex tokens in the response.

Create a Network Token

Creating a network token through ShieldConex involves both creating a token and provisioning it via Network Token Provider. However, this does not retrieve the payment credentials and keeps the response data both encrypted and masked.

📘

Existing Network Token

When creating a network token with the same card credentials, the same Token ID is returned with the corresponding data, becuase the network token already exists and is persistent.

Network tokens can be used for these in-app payment methods:

• Android Pay
• Apple Pay
• Chase Pay
• Google Pay
• Samsung Pay
• Visa Click to Pay

These tokenized payment methods are also referred to as digital payments, digital wallets, and tokenized cards.

Request

The request body takes in the cardholder's PAN data with the expiration dates and CVV.

POST /api/network-token-bundle

{
  "headers": {
    "Authorization": "Basic {Base64_Encoded_API_KEY}",
    "Content-Type": "application/json",
    "scx-client-reference": "cl000744"
  },
  "body": {
    "cardNumber": "4622943123155639",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "securityCode": "242"
  }
}

For comprehensive descriptions of request/response parameters, see API Reference | Create Network Token.

Response

🚧

Note

In response, we get the network token entry with the data both encrypted and masked.

{
  "messageId": "1202506261452471241450814",
  "networkTokenBundleId": "7030070000047325639",
  "networkTokenBundleState": "ACTIVE",
  "networkToken": {
    "networkTokenState": "ACTIVE",
    "tokenizedNumber": "489537XXXXXX5690",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "type": "visa",
    "card": {
      "suffix": "5639",
      "expirationMonth": "12",
      "expirationYear": "2026"
    }
  },
  "issuer": {
    "paymentAccountReference": "V0010013025078536357001803531"
  },
  "metadata": {
    "creator": "testbluefin_sandbox001"
  }
}

Get a Network Token

This endpoint returns the corresponding network token entry with its metadata.

🚧

Note

The response data is both encrypted and masked.

Request

GET /api/network-token-bundle/{networkTokenId}

{
  "headers": {
    "Authorization": "Basic {Base64_Encoded_API_KEY}",
    "Content-Type": "application/json",
    "scx-client-reference": "cl000744"
  }
}

Response

{
  "messageId": "1202506261454571251836563",
  "networkTokenBundleId": "7030070000047325639",
  "networkTokenBundleState": "ACTIVE",
  "networkToken": {
    "networkTokenState": "ACTIVE",
    "tokenizedNumber": "489537XXXXXX5690",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "type": "visa",
    "card": {
      "suffix": "5639",
      "expirationMonth": "12",
      "expirationYear": "2026"
    }
  },
  "issuer": {
    "paymentAccountReference": "V0010013025078536357001803531"
  },
  "metadata": {
    "creator": "testbluefin_sandbox001"
  }
}

Get Payment Credentials

This endpoint is called before processing a payment to retrieve the tokenizedCardId and cryptogram. Additional properties of the tokenizedCard—such as tokenizedNumber, expirationMonth, and expirationYear—are returned in a decrypted form.

To ensure maximum security, each request for credentials associated with the same network token returns a unique cryptogram for each CIT.

🚧

Cryptogram Usage | CITs and MITs

Getting a cryptogram is required for a CIT transaction where the rest of the decrypted networkToken fields are usually stored for subsequent MITs. However, in this case being a large ISV, you could be subject to increased PCI DSS scope requirements.

Overview

Customer initiated transactions (CIT), as the name suggests, are initiated by the customer. For Network Tokens, this is usually also a CNP transaction. Examples include online purchases, in-store purchases and mobile payments.

Merchant initiated transactions (MIT) play a crucial role in situations where the merchant needs to charge the customer on a regular basis or perform transactions without requiring repeated customer interactions. These transactions reduce friction for customers by eliminating the need for repeated manual entries.

MITs are processed based on a prior agreement with the customer.

Request

GET /api/network-token-bundle/{networkTokenId}/payment-credentials

{
  "headers": {
    "Authorization": "Basic {Base64_Encoded_API_KEY}",
    "Content-Type": "application/json",
    "scx-client-reference": "cl000744"
  }
}

Response

{
  "messageId": "1202506261455281262126996",
  "networkTokenBundleId": "7030070000047325639",
  "networkToken": {
    "networkTokenId": "364C5478E9336F06E063AF598E0A96FB",
    "networkTokenState": "ACTIVE",
    "tokenizedNumber": "462294XXXXXX5639",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "type": "visa",
    "cryptogram": "AwAAAAACgYVzzhAF9eD8grEAAAA=",
    "eci": "07",
    "requestorId": "40000000082",
    "card": {
      "suffix": "5639",
      "expirationMonth": "12",
      "expirationYear": "2026"
    }
  },
  "card": {
    "number": "462294XXXXXX5639"
  },
  "issuer": {
    "paymentAccountReference": "V0010013025078536357001803531"
  }
}

📘

ECI: Electronic Commerce Indicator

The ECI value indicates the level of security used in an electronic commerce transaction. It helps the card issuer determine whether the transaction was authenticated and the associated (low or high) risk level. This value is typically represented by a 2-digit numeric code.

For Visa ECI values, check out 5.1 Electronic Commerce Indicator (ECI).

For Mastercard ECI values, see E-Commerce Commerce Indicator.

Delete a Network Token

Some of the reasons to delete a network token can include:

• Customer Request for Data Deletion (PCI DSS Compliance)
• Managing Payment Method Updates
• Deactivating Fraudulent or Compromised Payment Tokens
• End of Business Relationship or Account Termination
• Clearing Inactive or Expired Tokens for System Optimization
• Revoking Access After Payment Gateway Changes

DELETE /api/network-token-bundle/{networkTokenId}

{
  "headers": {
    "Authorization": "Basic {Base64_Encoded_API_KEY}",
    "Content-Type": "application/json",
    "scx-client-reference": "cl000744"
  }
}

The request returns 200 on success.

ShieldConex Tokenization & Network Tokens API

When a merchant is considering a future switch to a different payment processor, ShieldConex provides flexibility. In such cases, the preferred option is to return both the ShieldConex tokens and the associated network token. This ensures that tokenized data remains usable across processors, even in cases where the Network fails to generate a token in a timely manner. ShieldConex tokens play a key role in enabling this portability.

For more information, also see ShieldConex | Tokenization Explained and ShieldConex® Orchestration.

📘

Did you know?

To date, network tokens are used in roughly 30% of Visa and Mastercard transactions.

In combination with Network Tokens, ShieldConex utilizes its tokenization solution so that the customer has the flexibility to switch to a different payment processor, thus delivering processor independence.

If a network token times out or fails, the Tokenization API returns ShieldConex tokens, resulting in a non-network token transaction. ShieldConex tokens are, nonetheless, included once a network token is successfully returned.

Tokenization

With a template field (be it Card Information or Custom Field) as FPT(Format Preserving Tokenization) + Network Tokens, the following request returns both ShieldConex tokens and Network Tokens in response by Creating a Network Token.

Request

POST /api/tokenization/tokenize

🚧

Omit Flag

The tokenization API endpoint can also take the omit flag in the query parameters. For example,

POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize?omit=1

The omit flag used in the tokenization API has had 2 options in the past - when set to 0, the tokens are returned in the response to the request, and when set to 1, the tokens would be cached by Bluefin to be retrieved asynchronously. The default value is 0 or false. We have added an additional option to set this value to 2, which will result in the tokens being returned in the response and cached by Bluefin for up to 1 hour.

{
    "reference":"myref",
    "templateRef":"128ac7acefdd0825a21c126ee1fe6c09",
    "values":[
        {"name":"card_number","value":"4622943123155639"},
        {"name":"card_exp","value":"122026"},
        {"name":"card_cvv","value":"1234"}
    ]
}

🚧

Note

If Creating a Network Token fails, the ShieldConex tokens are included regardless where the networkToken is dropped.

Response

📘

ShieldConex Iframe

This endpoint is also used as part of the ShieldConex Iframe and it returns the same data below, making it flexible across all interfaces.

For more, see iFrame SDK & Tokenization and Iframe-based secure tokenization and detokenization processing.

As mentioned above, the response is the combination of the ShieldConex tokens and Creating a Network Token response.

{
  "messageId": "1202506261456311242669602",
  "reference": "myref",
  "bfid": "djI6MT...",
  "values": [
    {
      "name": "card_number",
      "value": "9246266530387677"
    },
    {
      "name": "card_exp",
      "value": "648413"
    },
    {
      "name": "card_cvv",
      "value": "126"
    }
  ],
  "networkTokenBundle": {
    "networkTokenBundleId": "7030070000047325639",
    "networkTokenBundleState": "ACTIVE",
    "networkToken": {
      "networkTokenState": "ACTIVE",
      "tokenizedNumber": "489537XXXXXX5690",
      "expirationMonth": "12",
      "expirationYear": "2026",
      "type": "visa",
      "card": {
        "suffix": "5639",
        "expirationMonth": "12",
        "expirationYear": "2026"
      }
    },
    "issuer": {
      "paymentAccountReference": "V0010013025078536357001803531"
    },
    "metadata": {
      "creator": "testbluefin_sandbox001"
    }
  }
}

Without detokenizing ShieldConex tokens, the networkTokenId is separately used to get the payment credentials for the merchant to process a payment on behalf of the customer.

For example,

Request

🚧

scx-client-reference

This header is required and is the Client ID tied to the Partner used for API Authentication.

GET /api/network-token-bundle/7030070000047325639/payment-credentials

{
  "headers": {
    "Authorization": "Basic {Base64_Encoded_API_KEY}",
    "Content-Type": "application/json",
    "scx-client-reference": "cl000744"
  }
}

Response

{
  "messageId": "1202506261457491241462510",
  "networkTokenBundleId": "7030070000047325639",
  "networkToken": {
    "networkTokenId": "364C5478E9336F06E063AF598E0A96FB",
    "networkTokenState": "ACTIVE",
    "tokenizedNumber": "462294XXXXXX5639",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "type": "visa",
    "cryptogram": "AwAAAAACix/WzREF9eD8grEAAAA=",
    "eci": "07",
    "requestorId": "40000000082",
    "card": {
      "suffix": "5639",
      "expirationMonth": "12",
      "expirationYear": "2026"
    }
  },
  "card": {
    "number": "462294XXXXXX5639"
  },
  "issuer": {
    "paymentAccountReference": "V0010013025078536357001803531"
  }
}

Detokenization

📘

ShieldConex® Orchestration

Detokenization call with the sensitive card holder data is a use case with ShieldConex® Orchestration where the detokenized values are forwarded to the payment processor if the network tokens are not created and provisioned successfully, payment credentials are not received, or similar.

For more information, refer to ShieldConex® Orchestration.

Non-Sensitive data & Payment Credentials

Another use case is when the merchant wants to get other raw non-sensitive data with the token payment credentials if they are offering a subscription service and want to keep other data encrypted in their database or similar.

JSON

{
  "reference": "myref",
  "bfid": "djI6MT...",
  "values": [
    {
      "name": "card_holder_name",
      "value": "2342342311111"
    },
    {
      "name": "card_holder_last_name",
      "value": "342341234324"
    }
  ],
  "networkToken": {
    "networkTokenId": "7030070000047325639"
  }
}

The detokenize API call returns both the detokenized values and the network token payment credentials.

Request

POST /api/tokenization/detokenize

{
  "reference": "myref",
  "bfid": "djI6MT...",
  "values": [
    {
      "name": "card_number",
      "value": "9246266530387677"
    },
    {
      "name": "card_exp",
      "value": "648413"
    },
    {
      "name": "card_cvv",
      "value": "126"
    }
  ],
  "networkToken": {
    "networkTokenId": "7030070000047325639"
  }
}

Response

{
  "messageId": "1202506261458201241558872",
  "reference": "myref",
  "values": [
    {
      "name": "card_number",
      "value": "4622943123155639"
    },
    {
      "name": "card_exp",
      "value": "122026"
    },
    {
      "name": "card_cvv",
      "value": "242"
    }
  ],
  "networkTokenBundle": {
    "networkTokenBundleId": "7030070000047325639",
    "networkToken": {
      "networkTokenId": "364C5478E9336F06E063AF598E0A96FB",
      "networkTokenState": "ACTIVE",
      "tokenizedNumber": "462294XXXXXX5639",
      "expirationMonth": "12",
      "expirationYear": "2026",
      "type": "visa",
      "cryptogram": "AwAAAAACn+kQVOQF9eD8grEAAAA=",
      "eci": "07",
      "requestorId": "40000000082",
      "card": {
        "suffix": "5639",
        "expirationMonth": "12",
        "expirationYear": "2026"
      }
    },
    "card": {
      "number": "462294XXXXXX5639"
    },
    "issuer": {
      "paymentAccountReference": "V0010013025078536357001803531"
    }
  }
}