Detokenization Proxy

overview the forter detokenization proxy is a forward http proxy designed to facilitate detokenization for merchants interacting with third party apis that require sensitive pci data this enables you to process transactions securely without handling or storing sensitive cardholder information key benefits securely retrieve tokenized pci data avoid direct pci data handling compatible with standard http libraries and tools pass pci tokenized authorization payloads to any psp from a single card vault vendor proxy environments sandbox https //pci proxy sandbox checkouttools com production https //pci proxy checkouttools com authentication the forter detokenization proxy requires http basic authentication using the proxy authorization header in the following format proxy authorization basic to base64(site id\ site secret) the same credentials are used for both the detokenization proxy and the tokenization api trusted ca certificate to establish a secure connection, you must trust forter’s ca root certificate sandbox certificate begin certificate miicudccaaaccqdx1qoya/sqhtanbgkqhkig9w0baqsfadaemqswcqydvqqgewjj tdepma0ga1uecgwgrm9ydgvymb4xdtiymdgyntezmdmymfoxdtmymdgymjezmdmy mfowhjelmakga1uebhmcsuwxdzanbgnvbaombkzvcnrlcjccasiwdqyjkozihvcn aqebbqadggepadccaqocggebaosmh9wdhkaceirpwfvbfvpvhiq0h5tmkzixjrzn qvgpexd+e65fpjndztxpt06an2dqimh9vlef6wx9e6zxeqzzxkmwuu5rwjwx0hq2 5rbh9lery0xlcf4rpdaaqd74eoqwppj+5gbthjxweipag0wb6yb++d1kdhvt5yxd qxqc9gl1hxex4ozexctr5xjcpfruzgc/78sf8h0gg5vwoq8vprn0951tw7w1gha4 hl51alzkv4vucehr1fdqfrw6n2irahyhkyg38p3p+1kft9n01/qa3yap2judm4md ewy/roczavrregxeh0xrhw5pzubad4wmk1zfqkbwa0b2wwscaweaatanbgkqhkig 9w0baqsfaaocaqeaqjx8oas5glqfh/vb9hk2zr9kcxgxm+66wde+cdfilpfx8j9p j15ab37sgwk1v+6ov29z2znqjx4goonjlwlbazhr9dsjdodysjtrbrshxby5u/ys bh0essuafbiuzqu2ce2dhuluabvzc789hefyof16vdntfikxpvsj/ahqemawhbto us8/rygmxh0n655p7tzor8fotfvywqw8ie6zt/8susd6dmbysgxn3q6hwfziac2k f5vp/750ylkw2dv2swjo7ouz20qithq6+cjdbvtvrvleqgvtzevpkidgw5dxmpnt 3b8bjmiovuecw7123hwdqrht2ccqr9pv+cqzxw== \ end certificate production certificate begin certificate miicnjccayyccqcqd/jdclqxidanbgkqhkig9w0baqsfadarmq8wdqydvqqkdazg b3j0zxiwhhcnmjixmtixmtmyndq4whcnmjcxmtiwmtmyndq4wjarmq8wdqydvqqk dazgb3j0zxiwggeima0gcsqgsib3dqebaquaa4ibdwawggekaoibaqc4ngifmqm5 mkadtixzockuai4+xgbwmlobfqqtmluun3pe4chpfourcbtxreshzq0ywwftut51 armh+tsuw+dzbh35t0ytvmxbpfzhikg9ufxuhc9eon/mfpzxym15lh78nakxumpt +5r0+cg5tbjppcnvzbxmtyqocoqggj4zszlf4ijgnqlkrvua90uql1pttud8p6vg /o8vo0icrsa9qz7vljovxi4jai8gomjc0b+8r+fihakq146rpn9f5zajpou83btk n59njwjwbg7jqd0gtb+5mcywofsgr+emaaimvrek1bgftewjmzuzdxgsecgul/xy 6qb3ejr8mtj5agmbaaewdqyjkozihvcnaqelbqadggebagcmjleiqesbl5cud6i6 2pijpa1zk7cjz+fmpsch7bda/gmdc5ong4gb4qkbawsnxppeysbtkyzcwsgo5isr kfhxrcn/egyduwyzm1cenfuut+v7tzdnmstaa5xhcebukue3rqdy+qqlnewl/fai 3p0taiojifypsz04thavxagjztetszigzsexsamduuycczipgijrxr/onckjapxz lirdwllo5hu+wn+zvoprkuvrrhvrz/wqkmdqa2iu7oavi0mrrft/wvw73wozzhzo nwlgh2tlek6wv+bt9qhzdmv045l9lg9phnopct5k4rdgus6prymzdzq870nhho9p ccy= \ end certificate setup download and store the certificate in your http framework, add it as a trusted ca without overriding the default ca list using the detokenization proxy to use the proxy, replace sensitive pci data in the request payload with placeholders , and include the forter token in the request header token types payment method token a forter issued pci token for payment credentials cvc only token a specialized token for periodic cvc authentication required headers for payment method tokens when using a payment method token issued by forter, you have two integration options using the forter token directly this requires including the forter token header with the token string using a token alias if a token alias was previously specified in a /tokenize request to the forter tokenization api, you must provide the alias information via the following headers forter token alias key the alias key assigned in the tokenization request forter token alias value the corresponding alias value for cvc only tokens when using the cvc only token , the following headers must be included the primary forter token string forter token or forter token alias key and forter token alias value the cvc specific token issued by forter forter cvc token or forter cvc token alias key and forter cvc token alias value request placeholders placeholders are strings enclosed in double curly brackets ( {{ }} ) these placeholders should be inserted into the request payload sent to the detokenization proxy to ensure the correct request body format for the final third party target standard placeholders placeholder description {{card number}} the full credit card primary account number (pan) {{expiration m}} the expiration month as a single digit number (e g , 8) {{expiration mm}} the expiration month as a two digit number (e g , 08) {{expiration yy}} the expiration year as a two digit number (e g , 28) {{expiration yyyy}} the expiration year as a four digit number (e g , 2028) {{cvc}} the card’s security code (cvv/cvc) note the cvc is only available when using a single use token {{card holder name}} the name of the cardholder {{card bin}} the card’s bank identification number (bin) {{card last four}} the last four digits of the card number 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) custom placeholder fields placeholder description {{ text field }} extra fields from the tokenization api can be included ensure the placeholder name must match the original casing and wording handling errors the detokenization proxy uses special status codes to distinguish its own errors from third party api responses http status code description 407 proxy authentication error (check credentials) 502 network error while reaching the third party api 555 token not found 556 validation error (check inputs) 565 unexpected internal error other codes relayed directly from the third party api hmac request signing some payment service providers (psps) require hmac signing to verify request integrity forter supports multiple hashing algorithms and allows you to sign requests seamlessly supported hmac algorithms sha256 sha512 sha1 md5 hmac headers header name description forter hmac algo hmac algorithm (e g , sha256 ) forter hmac target header name of the header storing the computed signature forter hmac secret shared secret for signing forter hmac payload template template for the signed payload for the forter hmac payload template special placeholder values denoted in curly braces are supported {{ request body }} the full outgoing request body, after detokenization, as a single string {{ http method }} the http method used in the request {{ http path }} the relative path used in the request {{ header name }} any header sent along the request can be used to construct the signing payload the header name must be converted to lowercase psp specific signing methods disclaimer payment service providers (psps) employ various signing algorithms, and we can support a range of them for assistance with your specific requirements, please reach out to us ixopay to implement signing for https //documentation ixopay com/docs/guides/production/additional security#signing requests , include the following header forter ixopay signature shared ixopay key this will generate x signature and date headers in the proxied request to ixopay examples sending a request to forter forter's order api curl 'https //api forter secure com/v3/orders/{id}' \\ x https //site id\ tokenization site secret\@pci proxy sandbox checkouttools com \\ \ proxy header 'forter token ftr1df95272f9e204c5791427722cc4ef407' \\ \ cacert \[your ca certificate file path] \\ x post \\ h 'content type application/json' \\ h 'x forter siteid site id' \\ h 'api version api version' \\ h 'authorization basic dgvzddo=' \\ \ data ' { "orderid" "2356fdse0rr489", "ordertype" "web", "authorizationstep" "pre authorization", "totalamount" { "amountusd" "99 95", "amountlocalcurrency" "105 55", "currency" "cad", "amountmerchantmaincurrency" "125 95", "merchantmaincurrency" "eur" }, "totaldiscount" { "couponcodeused" "fathersday2015", "discounttype" "coupon" }, "payment" \[ { "creditcard" { "nameoncard" "{{ card holder name }}", "bin" "{{ card bin }}", "lastfourdigits" "{{ card last four }}", "cardtype" "credit", "expirationmonth" "{{ expiration mm }}", "expirationyear" "{{ expiration year }}" "fullcreditcard" "{{ card number }}" }, "billingdetails" { "personaldetails" { "fullname" "or paul", "email" "or paul\@gmail com" }, "phone" \[], "address" { "zip" "90043", "address1" "123 17th st", "city" "santa monica", "region" "ca", "country" "us" } }, "amount" { "currency" "eur", "amountlocalcurrency" "90 00", "amountusd" "100 00" } }, "primaryrecipient" { "personaldetails" { "firstname" "john", "lastname" "smith", "gender" "male", "birthdate" "1987 05 22", "email" "john s\@test com" }, "address" { "address1" "235 montgomery st ", "address2" "ste 1110", "zip" "94104", "city" "san francisco", "region" "ca", "country" "us", "company" "generic corp ltd ", "saveddata" { "usedsaveddata" true, "chosetosavedata" false } }, "comments" { "usercommentstomerchant" "please wrap with care!!", "messagetobeneficiary" "enjoy the gift john!", "merchantcomments" "shipping delayed" } }, "phoneorderinformation" { "customerwebid" "123456789", "callerfirstname" "john", "callerlastname" "smith", "callerid" "2121234567", "callstarttime" 1412345911, "callduration" 4, "remarks" "the customer is buying the product for a friend", "merchantagentdata" { "merchantagentname" "john smith", "merchantagentid" "hg36885tz" } }, "historicaldata" { "orderstatus" "completed", "merchantorderstatus" "shipped", "fraud" "fraud chargeback" } } ' sending a request to a psp stripe securely paying using a newly collected cvc token import {httpsproxyagent} from "https proxy agent"; import url from "url"; import stripe from "stripe"; import tls from 'tls'; const stripe = stripe("sk test "); const secureproxyhttpsagent = new httpsproxyagent("https //pci proxy sandbox checkouttools com",{ // passing the "ca" option will override the default mozilla trusted ca bundle, so we need to specify it explicitly again ca \[ tls rootcertificates, await fs readfile(' /forter proxy ca pem')], headers { "proxy authorization" `basic ${btoa('site id\ site secret')}`, "forter token" "ftr1df95272f9e204c5791427722cc4ef407", }, }); stripe sethttpagent(secureproxyhttpsagent); const cvctoken = await stripe tokens create({ cvc update { cvc "{{ cvc }}" }, }); const paymentintent = await stripe paymentintents create({ payment method 'abcd', customer '1234', amount 1099, currency 'usd', confirmation method 'manual', confirm true, payment method options {card {cvc token cvctoken}}, }); worldpay authorizing a transaction using authorizations api and a token alias // note we must trust the require proxy ca certificate in nodejs, this can be done in one of two ways // 1 saving the ca certificate to a file, and using the node extra ca certs environment variable // e g export node extra ca certs=\[your ca certificate file path] // 2 extending nodejs list of trusted cas (shown below) import {httpsproxyagent} from "https proxy agent"; import url from "url"; import axios from "axios"; import fs from "fs/promises"; import tls from 'tls'; const secureproxyhttpsagent = new httpsproxyagent("https //pci proxy sandbox checkouttools com", { // passing the "ca" option will override the default mozilla trusted ca bundle, so we need // to specify it explicitly again ca \[ tls rootcertificates, await fs readfile(' /forter proxy ca pem')], // contains forter's custom ca certificate headers { "proxy authorization" `basic ${btoa('site id\ site secret')}`, "forter token alias key" "zooz", "forter token alias value" "abcabc123", }, }); // securely calling worldpay's authorizations api axios post( "https //try access worldpay com/payments/authorizations", // note we are using a stringified payload as worldpay uses integers to represent dates which becomes // invalid json when replaced with our placeholders `{ "transactionreference" "memory265 13/08/1876", "merchant" { "entity" "mindpalaceltd" }, "instruction" { "narrative" { "line1" "mind palace" }, "value" { "currency" "gbp", "amount" 250 }, "paymentinstrument" { "type" "card/plain", "cardnumber" "{{ card number }}", "cardexpirydate" { "month" {{ expiration month }}, "year" {{ expiration year }} } } } }`, { httpsagent secureproxyhttpsagent } ); fiserv calculate a sha256 hash based hmac and store the result in a new header called message signature curl 'https //prod emea api fiservapps com/sandbox/ipp/payments gateway/v2/payments/' \\ x 'https //site id\ tokenization site secret\@pci proxy sandbox checkouttools com' \\ \ proxy header 'forter token ftr1df95272f9e204c5791427722cc4ef407' \\ x post \\ h 'content type application/json' \\ h 'client request id 123456' \\ h 'api key fiserv api key' \\ h 'timestamp 655846200000' \\ h 'forter hmac target header message signature' \\ h 'forter hmac algo sha256' \\ h 'forter hmac secret signing secret' \\ h 'forter hmac payload template {{ api key }}{{ client request id }}{{ timestamp }}{{ request body }}' \\ d ' { fullcreditcard "{{ card number }}", nameoncard "{{ card holder name }}", expirationmm "{{ expiration mm }}", expirationyy "{{ expiration yy }}", }'