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 token upgrading 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 token the 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 docid\ gnogxpzzthvw9suf4qjot 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 / failed the 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 docid 3 fafzyn4utlp1h4diu2h 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 docid\ lv3mxjmewxkauwqxindld 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\ tokenization site secret\@pci proxy sandbox checkouttools com' \\ \ 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