• Documentation
• Guides

Network Tokenization

Network Tokenization is a beta feature that is open to Spreedly customers who want to improve their success rates.

Spreedly supports Network Tokenization as part of Spreedly Revenue Optimization. By converting stored credit card data to secure network tokens, merchants get the benefits of higher security, better customer experience, and increased authorization success rates. We offer network tokenization in partnership with Visa and Mastercard and a growing network of gateway partners.

Network Tokens

With the growth of credit cards in e-commerce transactions card networks such as Visa and Mastercard now offer Network Tokenization (NT) services that replace raw card numbers (FPAN) with merchant-specific tokens.

Like regular credit card numbers, these Network Tokens (also called DPAN) are a 16 digit value that can be used for completing e-commerce transactions.

Network tokens offer a wide range of benefits for the merchant and consumers:

• Network tokens are issued in partnership with issuing banks. As a result network token transactions have a higher authorization rate when compared to payment made without network tokens.
• Customers have a better experience as network tokens receive proactive updates from the card networks. Merchants can also choose to leverage detailed card art provided with the network token.
• Network token payments have increased security as they are merchant-specific and each transaction is protected with a one time use cryptogram. As a result, instances of fraud decline with network token use.

Network Tokenization Use Cases

Merchants can benefit from network tokens when the following use cases apply to their business:

• Recurring transactions that need up to date card on file information.
• Offer robust customer experience with up to date payment methods and card art.
• Proactive communication when a customer’s card is suspended or deactivated by the bank.

Spreedly Network Tokenization Service

In order to use network tokens for transactions, a merchant must have a token requestor that has integrated with the card network’s token service (examples include Visa Token Service or Mastercard Digital Enablement Service), be issued a merchant-specific Token Requestor ID (TRID) for each card network, and be integrated with a payment gateway that supports network token transactions.

Spreedly allows merchants to meet all these requirements in a single solution. As a Token Requestor Token Service Provider (TR-TSP), Spreedly has completed integrations with Visa and Mastercard allowing merchants to request network tokens using their merchant-specific TRID.

Furthermore, by pairing the network token to the FPAN in a single Spreedly PCI Token, merchants have the flexibility to take advantage of network tokens on multiple gateways while also being able to use PAN for gateways that have not yet adopted network token transactions.

Supported Gateways

Currently, Spreedly has integrated network token transactions for the following gateways:

• CyberSource
• Nuvei (formerly SafeCharge)
• Adyen
• Orbital
• Checkout.com
• Credorax
• dLocal
• Braintree
• Stripe Payment Intents

Support for additional gateways is in active development. For specific gateway requests, we recommend you contact your Spreedly Account Representative so they can share it with our product team.

Enabling Network Tokenization At Gateways

The following gateways are currently enabled for network tokens at Spreedly but require additional setup at the gateway end before transacting with network tokens via Spreedly.

• Braintree - In order to be enabled for network tokens on Braintree via Spreedly please contact the gateway and request to have “Third Party Card-On-File network tokens” enabled on the corresponding merchant accounts.
• Stripe Payment Intents - Please contact Stripe to have your merchant account configured to use network tokens provisioned through Spreedly.

Supported Card Networks

Spreedly currently supports network tokenization for the following card networks:

• Visa (VTS)
• Mastercard (MDES)

Support for additional card networks is under evaluation. To request the support of a specific network, please notify your Spreedly Customer Contact.

Request A Token Requestor ID

In order for network tokens to be available for merchants, Spreedly must have a Token Requestor ID (TRID) for the merchant. Card networks issue TRIDs independently, so a TRID will be necessary for each network you wish to issue network tokens.

Spreedly can accept existing merchant TRIDs or can help facilitate the acquiring TRIDs from supported card networks. To acquire a new TRID, please fill out the following TRID Request Form and notify your Spreedly contact or support to verify we’ve received the information.

Please note that there can be delays in receiving TRIDs back from the networks depending on request volumes.

For additional information about TRIDs please visit the TRID section of our Network Tokenization FAQ.

Enabling Network Tokenization For Spreedly Account

Access to network tokens and network token transactions is part of the Spreedly Revenue Optimization package.

To begin taking advantage of network tokens, please first contact your Spreedly Customer Contact to discuss enabling Revenue Optimization on your Spreedly account.

Once Revenue Optimization is enabled, your Spreedly Customer Contact will assist in either collecting your existing merchant TRIDs or assisting you in acquiring TRIDs.

While we recommend using network tokens for all supported card networks, it is not a requirement. You may still use network tokenization for a single network so long as that network has issued a TRID for your business.

Your Spreedly Customer Contact will work with our development team to have the TRIDs applied to your Spreedly Account. Once enabled, your Spreedly Customer Contact will notify you when you are able to begin requesting and transacting with network tokens.

Provisioning Network Tokens

In order to take advantage of network token transactions, a network token must first be issued for the card associated with the Spreedly payment method.

For a new retained payment method

The first method allows merchants to request a network token while retaining a new payment method.

When making an API request that supports retained: true or retain_on_success: true, including provision_network_token: true will request a network token be provisioned by the card network for the PAN being retained. This is currently supported for the following API requests:

• Create credit card
• Retain
• Authorize
• Purchase
• Verify

The response body for the request will include elements to indicate if a network token was provisioned, the network tokens status, and any errors that could have occurred during the network token provisioning.

Note that the success of the underlying transaction is independent of the success of the network token provisioning. Errors with the network tokenization provisioning process do not prevent the PAN from being retained and a Spreedly payment method token from being issued.

While we recommend provisioning network tokens for all cards, the element provision_network_token: true does allow merchants to set the value to false and bypass provisioning. This may be advantageous for merchants that wish to do A/B testing and want maximum control of their payment methods. Not including provision_network_token in a request has the same effect as false.

For merchants that wish to provision tokens for all new payment methods, we encourage them to leave provision_network_token: true for all retain requests. Doing so will ensure network tokens are requested for supported card networks and will not impact retaining payment methods for unsupported card networks.

Request Body

^{Existing API properties remain unchanged. Examples below are truncated only to illustrate new API properties for Network Tokenization.
For additional examples and information, please review the Spreedly API Reference.}

POST /v1/payment_methods.json HTTPS/1.1

{
  "payment_method": {
    "credit_card": {
      "first_name": "Joe",
      "last_name": "Jones",
      "number": "5555555555554444",
    },
    ...
    "retained": true,
    "provision_network_token": true
  }
}

Response Body

^{Existing API properties remain unchanged. Examples below are truncated only to illustrate new API properties for Network Tokenization.
For additional examples and information, please review the Spreedly API Reference.}

{
  "transaction": {
    "token": "L46gdNQunedFoor9ySRJfgz7RAk",
    "created_at": "2020-02-11T20:49:32Z",
    "updated_at": "2020-02-11T20:49:32Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    ...
    "payment_method": {
      "token": "VBVmxAmSDxmc7AjUGi7ViUf9avm",
      "created_at": "2020-02-11T20:49:32Z",
      "updated_at": "2020-02-11T20:49:32Z",
      "email": "joey@example.com",
      ...
    },
    "network_tokenization": {
      "provisioned": true,
      "token_status": "active",
      "errors": [
      ]
    }
  }
}

We recommend reading the following sections of the Network Tokenization FAQ to learn more:

• Provisioning Network Tokens
• Network Token Statuses
• Testing Network Tokens

For an existing payment method

(In Development)

The second method for requesting a network token is to pass in an existing Spreedly payment method.

The development team is actively working on this feature. Guides will be updated and early NT adopters notified when this feature is available.

Transacting with Network Tokens

Once your Spreedly vault has payment methods with network tokens you will be ready to use network tokens to complete tokenized transactions.

Network token transactions leverage existing payment transaction API requests and your existing Spreedly tokens. In a similar manner to provisioning network tokens, when a merchant uses the Spreedly API to complete a payment transaction for a given Spreedly token they can include the element attempt_network_token: true to attempt using a network token for the transaction.

Currently, the following payment transaction APIs are supported:

• Authorize
• Purchase
• Verify

Successful authorizations using network tokens are simply Captured or Voided in the same manner as PAN transactions. Likewise completed Captures or Purchases can be Voided or Credited.

Similar to provisioning network tokens, we encourage merchants to always set attempt_network_token: true to take advantage of network tokens whenever possible unless the gateway being transacted against requires merchants to be enabled ahead of time.

Spreedly has logic that checks multiple variables to determine if a network token will work for a transaction; if any variable does not pass, then the transaction will be made using the PAN associated with the Spreedly payment method token. This process is documented in the following section.

For merchants wishing to have more control of their payments attempt_network_token: false can be used to force the use of the PAN for the transaction. Use cases for false include A/B testing and combining network tokens with 3DS2 and/or smart routing.

Request Body

^{Existing API properties remain unchanged. Examples below are truncated only to illustrate new API properties for Network Tokenization.
For additional examples and information, please review the Spreedly API Reference.}

POST /v1/gateways//authorize. HTTPS/1.1

{
  "transaction": {
    "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
    "amount": 100,
    "currency_code": "USD",
    "attempt_network_token": true
  }
}

Response Body

^{Existing API properties remain unchanged. Examples below are truncated only to illustrate new API properties for Network Tokenization.
For additional examples and information, please review the Spreedly API Reference.}

{
  "transaction": {
    "on_test_gateway": true,
    "created_at": "2018-11-07T15:01:46Z",
    "updated_at": "2018-11-07T15:01:46Z",
    "succeeded": true,
    ...
    "payment_method": {
      "token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
      "created_at": "2017-06-26T17:04:38Z",
      "updated_at": "2018-11-07T15:01:45Z",
      ...
    },
    "network_tokenization": {
      "attempted": true,
      "errors": [
      ]
    }
  }
}

We recommend reading the following sections of the Network Tokenization FAQ to learn more:

• Testing Network Tokens
• Using Network Tokens and 3DS2
• Using Network Tokens and Smart Routing

Understanding When Network Tokens Are Used

Ultimately the goal of network tokens is to have a successful transaction with higher authorization and security.

However, there are many factors that determine if a network token is appropriate to use for a transaction. Spreedly takes into consideration the following factors before attempting to use a network token for a requested transaction:

• Is RO enabled for a merchant’s Spreedly Account?
• Did the merchant include attempt_network_token: true the transaction API request?
• Does the Spreedly payment method in the transaction have a Network Token with an Active Status?
• Does the selected Gateway support network token transactions?
• Can a cryptogram or a previous network transaction ID be used to securely use the network token?

Rather than task the merchant with evaluating these factors, Spreedly evaluates all these factors when the transaction API request is submitted.

When all scenarios evaluate to true, Spreedly will use the network token to complete the transaction.

If any factors evaluate to false, then Spreedly will instead use the PAN associated with the Spreedly payment to complete the transaction.

We recommend reading the following sections of the Network Tokenization FAQ to learn more:

• Network Token Statuses
• Network Tokens and Cryptograms
• Network Tokens and Recurring Transactions

Interpreting NT Transaction Responses

As discussed in the previous section, Spreedly handles determining if a network token will work for a given transaction request.

In an effort to be transparent and empower merchants with data for internal reporting and logging purposes, authorization and purchase API transactions requesting the use of a network token include a network_tokenization data element in the API response. The network_tokenization data element explains whether or not a network token was used and information as to why.

While a detailed version of the response body and it’s various elements can be found in our API documentation, the following is a brief summary of the data available:

• attempted - True or False statement as to if a network token was attempted for the transaction.
• token_status - The status of the token at the time of the transaction.
• errors - A combination of an error key and verbose description for why the network token was not used.

Along with the information provided in the network_tokenization element, the existing transaction response structure will return with the standard response. The combination of both elements in the response provides merchants with the full picture of the transaction - whether or not the transaction was successful and whether or not a network token was used for the transaction.

We recommend reading the following sections of the Network Tokenization FAQ to learn more:

• Network Token Statuses

Example NT Transaction Scenarios

Here are some examples that illustrate different NT transaction scenerios that could occur and how to interpret them.

^{Existing API properties remain unchanged. Examples below are truncated only to illustrate new API properties for Network Tokenization.
For additional examples and information, please review the Spreedly API Reference.}

1. Merchant does not set the NT flag in the request.

As a merchant, I do not want to use a network token for the transaction.

Request

attempt_network_token is not included in the request.

Response

Returns standard response. network_tokenization object is not included in the response.

2. Merchant requests an NT transaction which succeeds.

As a merchant, I would like to see if network token were used for the transaction.

Request

"attempt_network_token": true

Response

{
  "transaction": {
    "created_at": "2018-11-07T15:01:46Z",
    "updated_at": "2018-11-07T15:01:46Z",
    "succeeded": true,
    ...
    "network_tokenization": {
      "attempted": true,
      "errors": [
      ]
    }
  }
}

3. Merchant attempts to use NT, but NT is not available for that payment method. Transaction succeeds with PAN.

As a merchant, I could use this response cue the payment method for ‘re-tokenization’.

Request

"attempt_network_token": true

Response

{
  "transaction": {
    "created_at": "2018-11-07T15:01:46Z",
    "updated_at": "2018-11-07T15:01:46Z",
    "succeeded": true,
    ...
    "network_tokenization": {
      "attempted": false,
      "errors": [{
        "key": "token_not_provisioned",
        "message": "No Network Token provision request made for provided Payment Method."
      }]
    }
  }
}

4. Merchant attempts to use NT, but gateway does not support NT, so PAN is used.

As a merchant, I could use this response to adjust my NT gateway strategy or alert Spreedly of an issue.

Request

"attempt_network_token": true

Response

{
  "transaction": {
    "created_at": "2018-11-07T15:01:46Z",
    "updated_at": "2018-11-07T15:01:46Z",
    "succeeded": true,
    ...
    "network_tokenization": {
      "attempted": false,
      "errors": [{
        "key": "no_gateway_support",
        "message": "Network Tokenization service not supported on requested gateway."
      }]
    }
  }
}

5. Merchant attempts to use NT, but NT is deactivated because the bank account is deactivated. PAN transaction fails because bank account is closed.

As a merchant, I could use this response to trigger a ‘save’ program for the payment, that could notify the user to adjust their card details since neither the token or PAN worked.

Request

"attempt_network_token": true

Response

{
  "transaction": {
    "created_at": "2018-11-07T15:01:46Z",
    "updated_at": "2018-11-07T15:01:46Z",
    "succeeded": false,
    ...
    "network_tokenization": {
      "attempted": false,
      "errors": [{
        "key": "token_not_active",
        "message": "Network Token for requested Payment Method is not currently active to use in transactions."
      }]
    }
  }
}

6. Merchant attempts to use NT, but run into an NT error fetching the cryptogram, so PAN is used.

As a merchant, I could use this response to understand if there were unexpected errors with using network tokens.

Request

"attempt_network_token": true

Response

{
  "transaction": {
      "created_at": "2018-11-07T15:01:46Z",
      "updated_at": "2018-11-07T15:01:46Z",
      "succeeded": true,
      ...
      "network_tokenization": {
        "attempted": false,
        "errors": [{
          "key": "cryptogram_error",
          "message": "Cryptogram could not be successfully retrieved for Network Token."
        }]
      }
    }
}