Network tokenization

Spreedly offers Network Tokenization as part of Spreedly's Advanced Vault Product. 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.

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.

Spreedly Network Benefits

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.

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.
• Proactive communication when a customer’s card is suspended or deactivated by the bank.
  Spreedly Network Tokenization Service
• Offer robust customer experience for any Stored Credentials with up to date payment methods and card art

Getting Started with Network Tokens

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 enabled network token transactions for the following gateways:

Enabling Network Tokenization At Gateways*

The following gateways require additional configuration before initiating transactions with network tokens via Spreedly.

• Braintree - Please contact Braintree and request the activation of "Third Party Card-On-File network tokens" on your relevant merchant accounts.
• Stripe Payment Intents - Please contact Stripe to have your merchant account configured to use network tokens provisioned through Spreedly.

Additionally, once you have enabled network tokens on your merchant account at the gateway, you will need to update your gateway at Spreedly with a new field, enabled_network_tokens, set to true.

PUT /v1/gateways/<gateway_token>.json

{
  "gateway": {
    "enabled_network_tokens": true
  }
}

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 ensure your have provided all necessary information via the Advanced Vault onboarding form.

📘

Please note that there can be delays in receiving TRIDs back from the networks depending on request volumes. However, TRID from Mastercard should be available and ready to use immediately after Spreedly processes the request, and within 72 hours after processing the request for VISA.

Enabling Network Tokenization For Your Spreedly Account

Access to network tokens and network token transactions is part of Advanced Vault. To begin taking advantage of network tokens, please first contact your Spreedly Customer Contact to discuss adding Advanced Vault to your Spreedly account, or if that is already completed, please review the Advanced Vault Enablement Guide.

Once Advanced Vault 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 support 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 provisioning 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 token's 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. However, if retain on success is being used and the transaction does not succeed, then retaining will not occur nor will provisioning of the network token

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": "[[email protected]](mailto:[email protected])",  
      ...  
    },  
    "network_tokenization": {  
      "provisioned": true,  
      "token_status": "active",  
      "errors": [  
      ]  
    }  
  }  
}

Possible Card Network Errors

If Spreedly receives an error from the card network when a request is made to provision a network token, we will include the error code and associated message in the transaction response body's errors array.

Visa specific error key and message possibilities:

Mastercard specific error key and message possibilities:

For An Existing Payment Method

To provision a Network Token on an existing payment method token, you can include provision_network_token:true on any of the supported API calls. For example, include provision_network_token:true on a direct retain call. Or, include retain_on_success:trueand provision_network_token:true on a subsequent authorize , purchase or verify using this vaulted payment method. The transaction must still succeed for a provision attempt to occur if retain_on_success is being used, whether or not the PM is already in a retained state.

📘

If the payment method has already been retained, requesting to retain it again will not result in any changes to its state, but will allow the trigger to provision a network token to proceed.

Reprovisioning

As Network Tokens can move from an Active to Inactive state over time, it is possible to attempt to reprovision a network token on a payment method that already has a provisioned network token. Reprovisioning is done the exact same way provisioning is achieved on an existing payment method outlined above. In the case where a request to reprovision is made and the network token status is not ACTIVE, Spreedly will attempt to provision a Network Token and if successful, replace the inactive token with the newly provisioned network token on the existing payment method.

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/<gateway_token>/authorize. HTTPS/1.1

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

Response Body

{  
  "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": [  
      ]  
    }  
  }  
}

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:

1. Is the Payment Method Enrolled in Advanced Vault?
2. Did the merchant include attempt_network_token: true the transaction API request?
3. Does the Spreedly payment method in the transaction have a Network Token with an Active Status?
4. Does the selected Gateway support network token transactions?
5. Has the selected Gateway, if applicable, been enabled for network token transactions?
6. 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.

Understanding Token Status

Active

The Network Token is ready for transactions.

Suspended
The Network Token is suspended and unable to transact. Issuing banks can suspend individual tokens if there is an issue with fraud or if the cardholder locks the card. This can be a temporary state, and the issuer may choose to reactive the token or later choose to make it Deleted or Deactivated.

Deactivated(Mastercard) / Deleted(Visa)
Network token can be in a deactivated or deleted status after it has been permanently deleted by the issuing bank or by the merchant. Issuing banks will delete a token if the account is closed.

Null
The most common cause for a 'null' status is we're awaiting a response from the network after first requesting the network token. After provisioning, in cases where the network did not activate it immediately, Spreedly will await a callback notification updating the status. This notification typically arrives 4-5 seconds after provisioning.

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:

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.

NT Scenarios

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

1. Action:Merchant does not set the NT flag in the request.
   Use Case: 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. Action: Merchant requests an NT transaction which succeeds.
   Use Case: As a merchant, I would like to see if network token was 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. Action: Merchant attempts to use NT, but NT is not available for that payment method. Transaction succeeds with PAN.
   Use Case: As a merchant, I could use this response to cue the payment method for an attempt to provision.

Request

Include 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. Action: Merchant attempts to use NT, but gateway does not support NT, so PAN is used.
   Use Case: 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. Action: Merchant attempts to use NT, but NT is deactivated because the bank account is deactivated. PAN transaction fails because bank account is closed.
   Use Case: 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. Action: Merchant attempts to use NT, but run into an NT error fetching the cryptogram, so PAN is used.
   Use Case: 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."  
        }]  
      }  
    }  
}

Reporting

Detailed reporting on your Network Token utilization are located in your Spreedly Dashboard Reports section, underneath the Payment Methods tab.

Under this tab, you'll be able to see:

• Overall count of Retained Payment Methods with provisioned Network Tokens
• Details on the number of Network Tokens provisioned broken out by month.
• Counts of Transactions attempted with a Network Token
• Success Rates of NT transactions
• Card brand breakdowns for NT provisioning and transacting

Additional Supported Calls

GET Token Status

It is possible to check the current status of a provisioned Network Token via our API. To do so, you will need the token of the payment method that was originally tokenized.

Simply pass the payment method token in as a parameter to the following endpoint:
/v1/network_tokenization/token_status.<format>?payment_method_token=<payment_method_token>

Response

The response will indicate the current status of the network token:

{  
  "token_status": "ACTIVE"  
}

Additional notes:

This API request is non-billable for currently enrolled AV customers, otherwise it is considered billable.

Spreedly will perform an update of the Network Token during this request, if any such updates are possible. For example, if status is requested and we determine that the status, year, month, or number have changed, we will update the Network Token in our system to reflect the new value(s) and then return the most up to date status in the response.

Please see our Spreedly API Reference for details.

GET Card Metadata

If you would like to view the metadata available for a given Visa Network Token, you can do so by providing the token of the payment method that was originally tokenized as a parameter to the following endpoint:

/v1/network_tokenization/card_metadata.<format>?payment_method_token=<payment_method_token>

Response

This response will return Network Token metadata.

{  
  "card_metadata": {  
    "backgroundColor": "0x7aff54",  
    "foregroundColor": "0x7aff54",  
    "labelColor": "0x7aff54",  
    "contactEmail": "[[email protected]](mailto:[email protected])",  
    "contactNumber": "1-800-432-4357",  
    "contactName": "test contact",  
    "privacyPolicyURL": "<https://www.freeprivacypolicy.com/>",  
    "termsAndConditionsURL": "<https://termsconditions.com/>",  
    "termsAndConditionsID": "fa66dcacb71f426c80ed4b3c5e109cbf",  
    "shortDescription": "My Test Issuer",  
    "longDescription": "My Test Issuer",  
    "cardData": [  
      {  
        "guid": "4428da983173468a8435f056e4984997",  
        "contentType": "cardSymbol",  
        "content": [  
          {  
            "mimeType": "image/png",  
            "width": "100",  
            "height": "100"  
          }  
        ]  
      }  
    ],  
    "issuerFlags": {  
      "deviceBinding": true,  
      "cardholderVerification": true,  
      "trustedBeneficiaryEnrollment": true,  
      "delegatedAuthenticationSupported": true,  
      "oboDeviceBinding": true  
    }  
  }  
}

Additional Notes:

Please note that the content of the card_metadata object is determined and can be changed by the card network, at any time. Because of this, the keys in the response are potentially variable and should not be considered idempotent.

This API request is non-billable for currently enrolled AV customers, otherwise it is considered billable.

Spreedly will perform an update of the Network Token’s metadata during this call if any such updates are possible.

Please see our Spreedly API Reference for a full description of response fields.

Using without a Network Token

If either of these endpoints is used with a payment method for which there is no Network Token assigned, you will receive the following error response:

{
  "errors": [
    {
      "key": "errors.network_tokenization.not_tokenized",
      "message": "You must provision a network token for this payment method before you can perform this action."
    }
  ]
}