Network Tokens
Overview
Process saved cards with a network-issued token instead of the card number.
A network token is a card credential issued by the card network (Visa, Mastercard, American Express) that replaces the primary account number (PAN) for a specific merchant. It is presented at authorization together with a one-time cryptogram, which proves the token was used by the registered merchant for that transaction.
Forter provisions and stores network tokens inside its agnostic card vault and links each one to your Forter token. Your systems continue to store and send only the Forter token — Forter manages the underlying PAN, the network token, and the per-transaction cryptogram.
How it works
Provisioning a network token
Provisioning happens when you create a multi-use Forter token or upgrade a single-use Forter token to a multi-use Forter token with network-token provisioning requested.
Creating a multi-use token
sequenceDiagram
autonumber
participant M as Merchant
participant F as Forter Tokenization Server
participant CN as Card Network
M->>F: Create multi-use token <br/> {card data, networkToken.provision=true}
F->>CN: Provision network token {cardData}
CN->>F: Response {networkToken}
F->>F: Create Forter token & link network token
F->>M: Response {token, networkTokenStatus}
M->>M: Save Forter tokenUpgrading a single-use token to a multi-use token
sequenceDiagram
autonumber
participant M as Merchant
participant F as Forter Tokenization Server
participant CN as Card Network
M->>F: Create / upgrade multi-use token <br/> {card data or single-use token, networkToken.provision=true}
F->>CN: Provision network token {cardData}
CN->>F: Response {networkToken}
F->>F: Create Forter token & link network token
F->>M: Response {token, networkTokenStatus}
M->>M: Save Forter tokenThe Forter (PCI) token is always created. Network-token provisioning is attempted on top of it and may not succeed for every card — see Handling provisioning failures.
Authorizing with a network token
At authorization, the Forter detokenization proxy retrieves the linked network token, requests a fresh cryptogram from the network, and substitutes both into the request sent to your PSP.
sequenceDiagram
autonumber
participant U as Buyer
participant M as Merchant
participant F as Forter Proxy
participant CN as Card Network
participant PSP as PSP
U->>M: Pay with selected card
M->>M: Retrieve Forter token {selectedCardIndex}
M->>F: Authorization request with network-token placeholders {forterToken}
F->>CN: Provision cryptogram {networkToken}
CN->>F: Response {cryptogram}
F->>PSP: Authorization {networkToken, cryptogram, eci}
PSP->>F: Response {authorizationResult}
F->>M: Response {authorizationResult}
M->>U: Payment succeeded / failedThe cryptogram is a secure, time-sensitive authentication value generated per transaction. It cannot be stored or reused.
Before you start: network registration
To issue network tokens on your behalf, Forter registers your business with the card networks and creates a Token Requestor ID (TRID) for you. You do not need to contact the card networks or do anything beyond providing the information below — Forter handles the registration and provisioning.
Network tokenization requires that you're already onboarded to Forter's Card Vaulting solution.
1. Business details
Status | Field | What Forter needs |
|---|---|---|
Required | Official (legal) business name | Must exactly match the name on your business registration — this is used to create your TRID with Visa and Mastercard. Mismatches are the most common cause of onboarding delays. |
Required | Business EIN / Tax ID (or VAT, if outside the US) | Required for TRID creation with Visa and Mastercard. |
Required | Registered business address | The address on file with your business registration. |
Required | Website / URL | Your primary customer-facing site. |
Required | Primary MCC (Merchant Category Code) | If you don't know this, your acquirer or PSP can confirm it. |
2. Card network identifiers
These come from your acquirer or payment processor — you may need to request them if you don't have them on hand.
Status | Network | Identifier |
|---|---|---|
Required | Visa | CAID (Card Acceptor ID) and Acquirer BIN |
Required | Mastercard | Acquirer BIN / ID |
If applicable | American Express | TOC (Top of Chain) SEID — only applicable for an Amex Direct account. Not required for OptBlue. |
Required | Discover | MID (Merchant ID) |
You provide one Visa CAID for your business, and an acquirer BIN for each acquirer you process through. The registration itself is tied to your legal entity rather than to any individual acquirer or PSP, so a separate registration per acquirer is not required.
Provisioning a Network token
Network tokenization is not a separate endpoint. It is requested with the networkToken object on the Tokenization API calls that create a multi-use token. See Tokenization API for authentication, environments, and base URLs.
Field | Type | Description |
|---|---|---|
networkToken.provision | boolean | Request provisioning of a network token alongside the Forter token. |
networkToken.async | boolean | When true, provisioning is performed in the background so the call does not wait for the network response. |
Create a multi-use token
{
"cardNumber": "4111111111111111",
"expirationMonth": "08",
"expirationYear": "2028",
"cardHolderName": "John Doe",
"networkToken": {
"provision": true,
"async": false
}
}Upgrade a single-use token to multi-use
{
"token": "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8",
"networkToken": {
"provision": true
}
}Response
Both endpoints return the Forter token together with the outcome of network-token provisioning.
{
"token": "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8",
"networkTokenStatus": {
"created": true,
"reason": {
"code": {},
"message": ""
}
},
"cardInfo": {
"bin": "411111",
"lastFourDigits": "1111",
"cardBrand": "VISA",
"expirationMonth": 8,
"expirationYear": 2028
}
}Store the returned token and use it for all subsequent payments. Read networkTokenStatus.created to know whether a network token is available for that card.
Using a network token at authorization
You choose between the network token and the PAN per authorization, by which placeholders you include in the payload forwarded through the Detokenization Proxy. There is no separate flag: include the network-token placeholders and Forter substitutes the network token and a fresh cryptogram; include {{card_number}} and Forter substitutes the PAN.
Network tokenization placeholders
Placeholder | Description |
|---|---|
{{network_token}} | The PAN's associated network token. |
{{network_token_cryptogram}} | A one-time cryptogram used with the network token. |
{{network_token_eci}} | The network token's Electronic Commerce Indicator (ECI). |
{{network_token_par}} | The Payment Account Reference (PAR) associated with the network token. |
{{network_token_expiration_m}} | The expiration month of the network token as a single-digit number (e.g., 8). |
{{network_token_expiration_mm}} | The expiration month of the network token as a two-digit number (e.g., 08). |
{{network_token_expiration_yy}} | The expiration year of the network token as a two-digit number (e.g., 28). |
{{network_token_expiration_yyyy}} | The expiration year of the network token as a four-digit number (e.g., 2028). |
The network token carries its own expiration date, which is independent of the underlying card's expiry. Always send the network-token expiry placeholders with a network-token authorization, not the card expiry placeholders.
Example: authorizing through a PSP with a network token
The proxy authentication, CA certificate, and error codes are identical to any other detokenization request — only the payload placeholders change.
curl 'https://checkout-test.adyen.com/v71/payments' \
-x 'https://SITE_ID:[email protected]' \
--proxy-header 'forter-token: ftr1d8a56cfa6b3745a39e4a42d5ab1048c8' \
--cacert [YOUR_CA_CERTIFICATE_FILE_PATH] \
-X POST \
-H 'Content-Type: application/json' \
-H 'X-API-Key: PSP_API_KEY' \
--data '{
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"reference": "ORDER-2356fdse0rr489",
"amount": { "currency": "USD", "value": 1099 },
"paymentMethod": {
"type": "networkToken",
"number": "{{network_token}}",
"expiryMonth": "{{network_token_expiration_mm}}",
"expiryYear": "{{network_token_expiration_yyyy}}",
"holderName": "{{card_holder_name}}"
},
"mpiData": {
"tokenAuthenticationVerificationValue": "{{network_token_cryptogram}}",
"eci": "{{network_token_eci}}"
},
"shopperInteraction": "ContAuth",
"recurringProcessingModel": "Subscription"
}'Field names, and whether the cryptogram belongs in the payment method object or a 3DS/MPI object, differ by PSP. Confirm the network-token authorization schema with your PSP and map the placeholders accordingly. Placeholder substitution works in JSON and form-encoded bodies alike.
Token lifecycle management
Once a network token exists, the card networks push lifecycle events to Forter as the underlying card changes. Forter applies them to your vault, so the Forter token you stored keeps working.
Lifecycle event types include:
- Token Updated
- Token Suspended
- Token Reactivated
- Token Deleted
- New Payment Account Number
- New Payment Account Expiry
When a card is reissued or replaced, the network re-links the existing network token to the new card and notifies Forter. Your systems keep using the same Forter token, and the customer does not need to re-enter their card. Expiration-date changes sync between the network token and the PAN automatically.
Handling provisioning failures
The Forter token is always created. Network-token provisioning is a separate, best-effort step on top of it, and can fail — most often because the issuer or card brand does not support network tokens.
- Check networkTokenStatus.created in the response. When it is false, networkTokenStatus.reason explains why.
- When it is false, continue using the Forter token normally. The PAN remains available for authorization through the proxy.
- Always implement a PAN fallback. If a network-token authorization fails for a reason that suggests a token or cryptogram problem, retry the request using {{card_number}} and the card expiry placeholders. Disruptions do occasionally occur in the network-token ecosystem, and a PAN retry path keeps those from becoming lost sales.
Testing
Use the Tokenization API sandbox environment, which accepts the published hardcoded test PANs. Sandbox testing does not require your TRID registration to be complete, so you can build and validate the integration while network enrollment is in progress.
Validate at least:
- Provisioning succeeds and networkTokenStatus.created is true.
- Provisioning failure is handled gracefully and the Forter token is still usable.
- A network-token authorization reaches your PSP with the correct field mapping, cryptogram, and ECI.
- The PAN fallback path works for a card with no network token.
- Saved-card, subscription, and refund flows all work against the stored Forter token.