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:
CyberSource | Nuvei (formerly SafeCharge) | Adyen |
Orbital | Checkout.com | Credorax |
dLocal | Braintree* | Stripe Payment Intents* |
Decidir | Worldpay | CyberSource Rest |
Plexo | Vantiv eCommerce (formerly Litle) | Authorize.net |
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.
Element | Description |
---|---|
Payment Method | Root Element |
❯ provision_network_token | true if this payment method should be provisioned a network token. Only applicable for payment methods to be retained. |
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.
ELEMENT | DESCRIPTION |
---|---|
transaction | Root element |
❯ network_tokenization | Network tokenization information as part of this transaction, if applicable. |
❯❯ provisioned | true if NT is successfully provisioned; false otherwise. |
❯❯ token_status | Status of the token, if one was provisioned. Can be one of the following:inactive active suspended deactivated |
❯❯ errors | If the request to provision network token is invalid or if tokenization not successful, there will be associated error messages here. Errors may originate as part of Spreedly's validation or come from the card network. Array of { key: "key", message: "message" } pairs. Additional details on specific card network errors can be found below. |
❯❯ key | Error codes that originate from Spreedly can be one of the following:not_enabled_feature not_enabled_for_environment network_service_error unsupported_card_type |
❯❯❯ message | Verbose information on the error code. Messages associated with Spreedly originated error codes can be one of the following: Network Tokenization service is not currently enabled at Spreedly. Network Tokenization is not enabled on this environment. Mastercard/Visa Network Tokenization service down. Unsupported Card Type for Network Tokenization. |
{
"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
The pass through of card network errors is a planned new behavior, pending release as of June 2024.
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:
KEY | MESSAGE |
---|---|
invalid_parameter | The token state does not allow the operation |
card_verification_failed | Your request does not have valid set of parameters required to process the business function |
card_not_eligible | This card cannot be used at this moment. Please try again later, or choose another Visa card. |
not_allowed | Further operations for this card are no longer allowed |
declined | Conflicts with existing token, violates business rules |
tr_config_issue | Input to tokenRequestorId is invalid |
card_not_allowed | The requested action is not allowed for the given PAN |
service_error | Unknown failure reason in processing the request |
json_parse_error | Invalid response received from the NT API. |
Mastercard specific error key and message possibilities:
KEY | MESSAGE |
---|---|
PAN_INELIGIBLE | PAN Ineligible |
INVALID_TOKEN_UNIQUE_REFERENCE | Invalid Token Unique Reference |
MISSING_REQUIRED_FIELD | Missing Required Field - ex: tokenUniqueReference |
INVALID_PAN | Invalid PAN |
INVALID_TOKEN_STATUS | Invalid Token Status |
no_response_from_issuer | Issuer did not respond in time. Retry the request |
duplicate_request | Duplicate Request |
internal_server_err | Internal Server Error |
json_parse_error | Invalid response received from the NT API. |
limit_exceeded | Too Many Requests |
gateway_timeout | Gateway Timeout |
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:true
and 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.
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:
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.
Element | Description |
---|---|
transaction | Root element |
❯ attempt_network_token | true if this transaction should use network token; if one is available. false or omit this element if do not want to use network token for this payment method, and want to use PAN instead. |
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
ELEMENT | DESCRIPTION |
---|---|
transaction | Root element |
❯ network_tokenization | Network tokenization information as part of this transaction, if applicable. |
❯❯ attempted | true if transaction was attempted with a network token. false if PAN was used instead. |
❯❯ errors | If the request to transact with network token is invalid or if the NT transaction was not successful, there will be associated error messages here. Array of { key: "key", message: "message" } pairs. |
❯❯❯ key | Error code. Can be one of the following:not_enabled_feature not_enabled_for_environment unsupported_card_type token_not_provisioned token_not_active no_gateway_support cryptogram_error |
{
"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:
- Is the Payment Method Enrolled in Advanced Vault?
- 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?
- Has the selected Gateway, if applicable, been enabled for 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.
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:
Element | Description |
---|---|
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.
NT Scenarios
Below are some examples that illustrate different NT transaction scenarios that could occur and how to interpret them.
- 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.
- 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": [
]
}
}
}
- 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."
}]
}
}
}
- 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."
}]
}
}
}
- 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."
}]
}
}
}
- 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
Updated 3 days ago