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 "managed order token" > f\["execute 3ds"] d approve > g\["phase 3 create payment"] f > h\["handle 3ds challenge"] h > i{"challenge success?"} i no > e i yes > g g > l\["phase 4 capture payment"] 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) forterdecisioncorrelationid correlation id to be passed to phase 3 payment creation or, in case forter recommends 3ds the response will include managed order token forterdecisioncorrelationid correlation id to be passed to phase 3 payment creation 2 2 decision logic approve → proceed to payment decline → reject transaction managed order token → execute 3ds 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 include the forter orderid from phase 2 in the request body to link the payment to the prior fraud assessment the forterdecisioncorrelationid field is required for merchant managed integrations it links the payment to the pre authorization fraud decision obtained in phase 2, enabling forter to correlate the authorization with the risk assessment request fields orderid — the forter order id from phase 2 amount — payment amount in smallest currency unit (e g cents) currency — iso 4217 currency code (e g usd ) capturemethod — automatic for immediate capture or manual for a manual capture confirm — set to true for immediate authorization or set to false to send another confirm call before authorization forterdecisioncorrelationid — correlation id from the phase 2 fraud decision response paymentmethod type — payment method type (e g token ) paymentmethod fortertokenstring — the forter token obtained from phase 1 connectioninformation customerip — ip address of the customer browserinfo useragent — user agent string of the customer's browser cartitems — list of cart items, each with name , price , quantity , and type shipping deliverymethod — delivery method (e g standard ) shipping deliverytype — delivery type (e g digital ) customer email — customer email address customer firstname — customer first name customer lastname — customer last name { "orderid" "{{orderid}}", "amount" 1099, "currency" "usd", "capturemethod" "automatic", "confirm" true, "forterdecisioncorrelationid" "{{correlationid}}", "paymentmethod" { "type" "token", "fortertokenstring" "{{paymenttoken}}" }, "connectioninformation" { "customerip" "127 0 0 2" }, "browserinfo" { "useragent" "mozilla/5 0 (windows nt 10 0; win64; x64)" }, "cartitems" \[ { "name" "testitem", "price" 1099, "quantity" 1, "type" "tangible" } ], "shipping" { "deliverymethod" "standard", "deliverytype" "digital" }, "customer" { "email" "customer\@example com", "firstname" "john", "lastname" "smith" } } response fields id — unique payment id orderid — the order id associated with this payment amount — requested payment amount amountreceived — amount actually received/authorized createdat — iso 8601 timestamp of payment creation currency — iso 4217 currency code status — payment status authorized , failed connector — the psp/connector used (e g stripe , adyen ) capturemethod — automatic or manual paymentmethodtype — type of payment method used (e g card ) metadata — additional metadata key value pairs { "id" "string", "orderid" "order abc 123", "amount" 9876, "amountreceived" 9876, "createdat" "2025 07 14t12 34 56 789z", "currency" "gbp", "status" "authorized", "connector" "stripe", "capturemethod" "automatic", "paymentmethodtype" "card", "metadata" {} } 3 2 confirm payment use this step when confirm was set to false endpoint post /payments/\ id/confirm response returns final status authorized or failed 3 3 capture authorized payment use this step when capturemethod was set to manual endpoint post /payments/\ id/capture { "amount" 1099 } 3 4 cancel payment cancel a payment that has not yet been captured endpoint post /api/payments/\ id/cancel { "reason" "customer requested cancellation" } phase 4 refunds issue a refund for a captured payment the amount field is optional — omit it for a full refund endpoint post /api/refunds { "paymentid" "{{paymentid}}", "amount" 500, "reason" "customer returned item" } example response { "id" "ref abc123", "amount" 500, "currency" "usd", "status" "succeeded", "reason" "customer returned item", "createdat" "2025 07 14t12 34 56 789z" } you can also retrieve refund details using get /api/refunds/{id} or list all refunds for a payment using get /api/refunds?paymentid={paymentid} 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