Merchant Managed

this guide provides enterprise merchants with a comprehensive integration path for forter's orchestration service, enabling unified payment processing with built in fraud protection, predictive routing, and 3ds handling the orchestration api consolidates multiple payment operations into a single, cohesive workflow that replaces traditional psp specific integrations while maintaining enterprise grade reliability and performance integration flow flowchart td a\["customer enters card details"] > b\["phase 1 hosted fields tokenization"] b > c\["phase 2 pre authorization fraud check"] c > d{"fraud decision"} d decline > e\["reject transaction"] d "decline + 3ds recommended" > f\["phase 3 create payment with 3ds"] d approve > g\["phase 3 create payment"] f > h\["handle 3ds challenge"] h > i{"challenge success?"} i no > e i yes > j\["confirm payment"] g > k{"3ds required?"} k yes > h k no > l\["capture payment"] j > l l > m\["phase 5 ppr auto retry on failure"] m > n\["phase 6 webhook notifications"] phase 1 hosted fields integration (tokenization) securely capture payment credentials using forter's hosted fields, replacing psp native checkout fields 1 1 backend session key generation generate an authentication token for the frontend to initialize hosted fields endpoint post /v1/tokenization/client key // node js example router get('/client key', async (req, res) => { const authstring = buffer from( `${forter site id} ${forter site secret}` ) tostring('base64') const authorization = `basic ${authstring}` const response = await axios({ method 'post', url `${baseurl}/v1/tokenization/client key`, headers { authorization authorization, 'content type' 'application/json', }, data { ttlminutes 60 }, }) res json({ token response data clientkey }) }) 1 2 frontend sdk initialization include forter's sdk on your checkout page initialize and configure hosted fields const fortercollect = await window\ checkouttools collect init({ environment 'production', authtoken await getauthtoken(), onvaliditychange (fieldid, isvalid, error) => updatefieldvalidation(fieldid, isvalid, error), oncardbrandchange (cardbrand) => updatecardbranddisplay(cardbrand), }) await fortercollect addfields({ 'card holder name' { type 'card holder name', placeholder 'name on card', style getfieldstyles(), }, 'card number' { type 'card number', placeholder '1234 5678 9012 3456', style getfieldstyles(), }, 'card expiry' { type 'card expiration date', placeholder 'mm/yy', style getfieldstyles(), }, 'card cvc' { type 'card cvc', placeholder 'cvc', style getfieldstyles(), } }) 1 3 token submission const handlepaymentsubmit = async (formdata) => { const tokenresult = await fortercollect submit(); if (!tokenresult success) { handlevalidationerrors(tokenresult errors); return; } await processpayment({ formdata, fortertoken tokenresult token }); }; 1 3 1 upgrade token (optional) if you need to store the payment method and/or provision a network token for it, you must use the /upgrade endpoint calling this endpoint creates a new multi use token and invalidates the existing single use token along with its cvc you can also choose to provision a network token during the upgrade, allowing forter to use it later during authorization example request { "token" "ftr1d8a56cfa6b3745a39e4a42d5ab1048c8", "networktoken" { "provision" true } } example response { "token" "ftr1efsdfew54wetg54ugdn58ns0482ko", "networktokenstatus" { "created" true } } phase 2 pre authorization fraud check prevent fraud before initiating payment authorization 2 1 order creation endpoint post /v3/orders payload includes order id forter token cart and pricing details customer + billing/shipping info response decision approve / decline reason (optional explanation) 2 2 decision logic approve → proceed to payment decline → reject transaction handling decline decisions with 3ds recommendations a decline decision from forter can indicate either a hard decline (irreversible fraud determination) or a borderline decline where the system recommends additional customer verification in borderline cases, the response may include a 3ds recommendation signaling that the merchant should proceed to create a payment and invoke a 3ds challenge if the shopper successfully completes the challenge, forter may reassess and approve the transaction this flow supports nuanced fraud handling and is especially relevant for merchants configured to support 3ds for risk your integration should honor this distinction continue to orchestration only if the decline is accompanied by a 3ds recommendation phase 3 payment processing via orchestration execute payments through forter's unified orchestration layer with 3ds and routing support 3 1 create payment endpoint post /api/payments { "cartitems" \[ { "name" "testitem", "price" 1099, "quantity" 1, "type" "tangible" } ], "amount" 1099, "currency" "usd", "paymentmethod" { "type" "token", "fortertokenstring" "{{paymenttoken}}" }, "capturemethod" "automatic", "confirm" true, "connectioninformation" { "customerip" "127 0 0 2", "useragent" "mozilla/5 0" }, "primarydeliverydetails" { "deliverymethod" "", "deliverytype" "digital" } } set confirm true for immediate capture set capturemethod to automatic or manual 3 2 handle 3ds authentication inspect next action from /payments response if requires action , call checkouttools managedorders manageorder() with the token after challenge completes, check payment status or confirm explicitly 3 3 confirm payment post 3ds endpoint post /payments/\ id/confirm response returns final status authorized or failed 3 4 capture authorized payment use this step when capturemethod was set to manual endpoint post /payments/\ id/capture { "amount" 1099 } phase 5 automatic retry logic – predictive payment routing (ppr) if the selected psp declines or fails, forter automatically generates a new routing recommendation the previous psp + failure reason is sent to ppr the next best psp is returned based on live success metrics forter retries authorization with the new psp transparently retries are idempotent and bounded by configurable limits this is an internal process and does not require any merchant action phase 6 webhooks forter delivers asynchronous updates for every lifecycle event event type description payment authorized payment successfully authorized payment captured funds successfully captured payment failed payment or capture failed payment cancelled payment was cancelled (by merchant or by forter) refund succeeded refund processed successfully refund failed refund failed to process example webhook payload { "type" "payment authorized", "eventid" "123456", "timestamp" "2024 11 07t05 31 56z", "data" { "paymentid" "pay 9981", "processor" "adyen" } } forter webhooks include x forter signature and x forter timestamp headers for validation phase 7 implementation notes forter's hosted fields must be used for pci compliance merchants are never exposed to raw pci data single use forter token expires within a maximum of 24 hours in case the customer chooses to store the payment method, you can upgrade to a long lived token using the forter tokenization api each transaction is idempotent by idempotency key to prevent double charges