Jump to a Section:
- What is Network Tokenization
- Opt-Into Network Tokenization at Spreedly
- Token Requestor IDs (TRIDs)
- Provisioning Network Tokens
- Transacting with Network Tokens
- Deleting Network Tokens
- Network Token Statuses
- Testing Network Tokens
- Imports, Exports, and Network Token Distribution
- Using Network Tokens and 3DS2
- Using Network Tokens and Smart Routing
Token Requestor IDs (TRIDS)
How Long Does Will It Take to Issue TRIDs?
The amount of time it takes to issue TRIDs will depend on the amount of TRIDs the networks are currently processing. For planning purposes, please plan for a time period between 2 weeks to 2 months. This being the case, we recommend requesting TRIDs as soon as you are interested in using network tokenization.
I already have TRIDs from another token requestor. Can I use my existing TRIDs?
If you have TRIDs from a previous token requestor, you can use those TRIDs with your Spreedly account to issue network tokens.
Please notify your Spreedly contact or support that you have TRIDs and they will work with you to have your TRIDs associated with your Spreedly account.
What if I only have received TRIDs for a single network? Can I start using network tokens?
While Spreedly's network solution supports multiple card networks, you do not need to have TRIDs for every network to being requesting network tokens. Take the example that you receive your Mastercard TRID prior to your Visa TRID; in this example, you can begin provisioning and transacting with Mastercard network tokens while you wait for your Visa TRID to be issued.
Provisioning Network Tokens
Please note that while network token adoption is rapidly rising globally, there are individual countries that can be ahead or behind in each region.
What factors determine if a network token will be provisioned for a requested credit card?
When you request a network token be provisioned for a credit card, several factors determine if a token will be provisioned:
- Spreedly must support network tokenization for the card. Currently, Spreedly supports network tokenization for Visa and Mastercard.
- Your Spreedly account must have the network-specific TRID associated. Without the network TRID, networks and issuing banks cannot return a merchant-specific token.
- The issuing bank must participate in network tokenization. Adoption of network tokenization by issuing banks depending on the region the issuing bank is located. North American banks currently have the highest adoption, while Latin American and European bank support is growing rapidly.
When I provision a token during a purchase transaction, will the token be used for the initial transaction? How will that impact transaction latency?
When a network token is provisioning is requested, the request must travel to both the card network and the issuing bank. This provisioning process can take between 5-6 seconds, which is much too long for a purchase transaction.
As a result, any purchase transaction that also requests a network token be provisioned will default to using the PAN for the initial transaction. Subsequent transactions for the same Spreedly payment method token can use the network token since it will be stored with the payment method.
What if I have network tokens from a previous token requestor? Can the existing tokens be imported to Spreedly?
Network tokens are transferrable between token requestors. Depending on the number of existing network tokens, it is often advisable to transfer existing tokens rather than spend time reissuing tokens.
The transfer does require coordination between Spreedly, the original token requestor, and the card networks. If you have existing network tokens you would wish to transfer to Spreedly, please contact your Spreedly contact or support.
Network Token Statuses
The token has been requested but the token has not yet been activated.
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.
How can I view a network token's status?
Please read our API documentation to learn how to use the Show or List API calls.
If the payment method has a network token associated with it, it will return a network token object in the response as seen in the example below. Otherwise, if there is no network token associated with the payment method, the response will not return the network token object.
"full_name": "Test Test",
Testing Network Tokens
Before you can begin testing network token provisioning and transactions, you will need to have been issued Token Requestor IDs by the card networks.
Once your TRIDs are available (one or all), Spreedly support can assist you in enabling network tokens for your production environment.
The TRIDs will be used when making requests to provision network tokens and for transactions with network tokens; these requests will involve communication with the networks and issuing banks.
Provisioning a Network Token for a single payment method
Please refer to the Provisioning Network Tokens section of our guides for detailed code examples.
Once your product environment has been enabled for network tokens, you’re ready to start requesting network tokens.
Network token provisioning can be completed on a per payment method basis. As such, you’re able to test provisioning network tokens with individual payment methods and single API calls.
Please note that the networks do not supply test cards.
Since this is the case, we recommend you test provisioning on a handful of trusted payment methods, be them personal cards or QA cards you use for testing transactions.
Once you’ve identified the cards you’d like to test, you can provision a network token by setting the `provision_network_token: true` in your API requests. For testing we recommend this in two ways:
- For an existing payment method, you can include the `provision_network_token: true` in an authorization call to the Spreedly test gateway. This requests an actual token, while replying with a mock authorization
- For a new payment method, you can include `provision_network_token: true` while retaining the payment method
Once you’ve submitted your API request, please note `network_tokenization` element of the response body.
A successful tokenization will include `”provisioned": true` in the network tokenization section of the response.
We recommend trying this process multiple times as not all issuing banks will provide tokens. This should result in several tokens issued and also the display error messages as well when tokens cannot be issued.
Testing transactions with a single network token.
Please refer to the Transacting with Network Token section of our guides for detailed code examples.
Much like provisioning a network token, transactions with network tokens can also be made on a per-transaction basis. This will allow you to make single API requests using network tokens without needing to change your existing flows.
Once you’ve issued a network token for a payment method, you can now use that payment method to complete a transaction on a gateway that supports network tokens.
We recommend making several low dollar amount transactions such as Authorize, Purchase, and Verify transactions with your gateway of choice to test these transactions. Setting the element attempt_network_token: true in the requests will pass the network token to the gateway.
Should the network token not be used for the transaction, our response will return `"attempted": false` in the network token section of the response and an error code provided to explain why NT was not used. In this event, the transaction will have used the PAN to attempt to complete the transaction.
For those curious to test this functionality, we recommend routing the transaction to a gateway that does not support NT transactions, while also leaving the element attempt_network_token: true in the request. Since the gateway does not support NT, the transaction will always fall back to the PAN.
A/B Testing with Network Tokens
Since transactions with network tokens can be enabled or disabled per transaction, this allows your engineering team to A/B test network tokens vs PAN transactions.
As an example, if I want to test network token transactions with 10% of my transactions, then I can have my application set element attempt_network_token: true for every 10th transaction.
The analysis of the success of NT over PAN can be conducted by reviewing the responses.
Transactions that request NT be attempted will contain the element
Alternatively, if attempted:false is in the response, then Spreedly completed the transaction with PAN instead and will have supplied a reason why NT could not be used.
The method above can be used for your own data analytics. However, we recommend partnering with your Spreedly customer account manager to let them know of any testing you plan.
Our product team can run aggregated reports for your transactions that can assist in analyzing the success of network tokens. (Note that these reports are planned to be added to your Spreedly dashboard in the future)