Custom/Native Integration Guide

complete guide for integrating your custom commerce backend with forter agentic orchestration this guide is for merchants who have built their own commerce solution and manage their own backend, inventory, and order processing for shopify or sfcc, see shopify integration docid\ knzyqgc1qwoupurkebuq2 or sfcc integration docid\ zgflwpyfqbfokjtufxtme how it works with custom integration, you host a product feed at a stable url (google merchant center xml, shopify csv, or json file) implement three merchant endpoints — account, cart, and checkout — to handle the checkout lifecycle process orders in your backend system forter fetches your feed periodically (hourly, daily, or custom schedule) generates and maintains the ai optimized product data orchestrates the checkout flow , calling your endpoints at each stage (account lookup, cart pricing, and order creation) you provide feed url + three merchant endpoint urls you implement account, cart, and checkout endpoint handlers prerequisites before starting, ensure you have product feed — google merchant center xml, shopify csv, or json format hosted at a stable url backend system — ability to receive and process post requests on three https endpoints https endpoints — all merchant endpoint urls must use https forter account — contact your forter representative to enable agentic orchestration tax configuration — list of us states where you have tax nexus step 1 host your product feed a feed format options choose one of the supported formats google merchant center xml \<?xml version="1 0" encoding="utf 8"?> \<rss version="2 0" xmlns\ g="http //base google com/ns/1 0"> \<channel> \<title>your store\</title> \<link>https //yourstore com\</link> \<description>product feed\</description> \<item> \<g\ id>sku 001\</g\ id> \<g\ title>premium widget\</g\ title> \<g\ description>high quality widget for all your needs\</g\ description> \<g\ link>https //yourstore com/products/widget\</g\ link> \<g\ image link>https //yourstore com/images/widget jpg\</g\ image link> \<g\ price>29 99 usd\</g\ price> \<g\ availability>in stock\</g\ availability> \<g\ brand>mycustomstore\</g\ brand> \<g\ gtin>1234567890123\</g\ gtin> \<g\ condition>new\</g\ condition> \</item> \<! more products > \</channel> \</rss> shopify csv handle,title,body (html),vendor,product category,type,tags,published,option1 name,option1 value,variant sku,variant grams,variant inventory tracker,variant inventory qty,variant inventory policy,variant price,image src,variant image,variant barcode widget premium,premium widget,"\<p>high quality widget\</p>",mycustomstore,,widgets,"gadgets,premium",true,,,sku 001,500,shopify,100,deny,29 99,https //yourstore com/widget jpg,,1234567890123 b host feed at stable url host your feed file at a publicly accessible url examples \ https //yourstore com/feeds/products xml \ https //cdn yourstore com/feed xml \ https //s3 amazonaws com/yourbucket/feed xml (with public access or pre signed url) requirements must be https must return content type application/xml (for xml) or text/csv (for csv) file size limit 500mb response time < 30 seconds c feed authentication (optional) if your feed requires authentication http basic auth (supported) username your username password your password forter will send authorization basic base64(username\ password) other authentication methods if your feed url requires other authentication methods (e g , bearer token, api key header, custom authentication), contact your forter representative to configure the credentials securely forter can support custom authentication headers on a case by case basis step 2 implement merchant endpoints forter calls three separate endpoints on your backend during the checkout lifecycle each endpoint receives a json post request with an event envelope and an agent context block all requests include an event envelope { "event" { "id" "uuid", "type" " ", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, } understanding reference id a reference id is a sticky identifier that lets you correlate calls across the three endpoints any endpoint response can include a reference id , and forter will pass it to all subsequent endpoint calls in the same checkout flow use it to link an account lookup to a cart to an order in your system step 2a implement account endpoint purpose look up whether a customer account exists in your system endpoint post https //yourstore com/api/account when called when a customer begins checkout and provides their email or phone this endpoint is non fatal — if it fails or returns an error, checkout continues without account information request { "event" { "id" "evt abc123", "type" "account login", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "email" "customer\@example com", "phone" "+14155551234" } response { "success" true, "account id" "cust 123", "reference id" "ref abc", "status" "active" } field type description success boolean whether the lookup succeeded account id string (optional) your internal customer id reference id string (optional) sticky id passed to subsequent calls status string "active" , "blocked" , or "not found" step 2b implement cart endpoint (required) purpose price the cart items, return available shipping options, and compute totals endpoint post https //yourstore com/api/cart when called when a customer adds items to cart or updates their cart (shipping address, coupon, etc ) this endpoint is fatal — if it fails, the checkout cannot proceed request { "event" { "id" "evt def456", "type" "cart created", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "reference id" "ref abc", "currency id" "usd", "account id" "cust 123", "items" \[ { "product id" "sku 001", "quantity" 2 } ], "coupon" "save10", "buyer" { "email" "customer\@example com", "first name" "john", "last name" "doe", "phone" "+14155551234", "address" { "line one" "123 main st", "city" "san francisco", "region id" "ca", "country id" "us", "postal code" "94102" } }, "recipient" { "shipping id" "standard", "first name" "john", "last name" "doe", "address" { "line one" "123 main st", "city" "san francisco", "region id" "ca", "country id" "us", "postal code" "94102" } } } the event type will be "cart created" for new carts or "cart updated" when the customer changes items, address, or shipping option response { "success" true, "reference id" "ref abc", "items" \[ { "product id" "sku 001", "quantity" 2, "price" 29 99, "effective price" 29 99, "subtotal" 59 98 } ], "shipping options" \[ { "id" "standard", "title" "standard shipping", "description" "5 7 business days", "price" 5 99 }, { "id" "express", "title" "express shipping", "description" "2 3 business days", "price" 12 99 } ], "totals" { "subtotal" 59 98, "discount" 0, "tax" 4 80, "shipping" 5 99, "total" 70 77 } } important all prices must be in dollars (decimal) , not cents for example, 29 99 not 2999 field type description items\[] price number original unit price items\[] effective price number price after item level discounts items\[] subtotal number effective price quantity shipping options array available shipping methods with prices totals object subtotal, discount, tax, shipping, and total step 2c implement checkout endpoint (required) purpose create the order in your system, process payment, and return an order id endpoint post https //yourstore com/api/checkout when called when the customer confirms the order and payment is ready to be processed this endpoint is fatal — if it fails, the order is not created request { "event" { "id" "evt ghi789", "type" "order created", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "reference id" "ref abc", "account id" "cust 123", "currency id" "usd", "items" \[ { "product id" "sku 001", "quantity" 2, "price" 29 99, "effective price" 29 99, "subtotal" 59 98 } ], "buyer" { "email" "customer\@example com", "first name" "john", "last name" "doe", "phone" "+14155551234", "address" { "line one" "123 main st", "city" "san francisco", "region id" "ca", "country id" "us", "postal code" "94102" } }, "recipient" { "shipping id" "standard", "first name" "john", "last name" "doe", "address" { "line one" "123 main st", "city" "san francisco", "region id" "ca", "country id" "us", "postal code" "94102" } }, "payment" { "provider" "stripe", "token" "tok visa 4242", "card" { "brand" "visa", "last4" "4242", "exp month" 12, "exp year" 2027 } }, "totals" { "subtotal" 59 98, "discount" 0, "tax" 4 80, "shipping" 5 99, "total" 70 77 } } the payment block includes provider — payment provider name (e g , "stripe" , "adyen" ) token — tokenized payment credential from the ai platform's pci compliant vault card — card metadata (brand, last4, expiration) for display/logging purposes success response { "success" true, "order id" "ord 12345" } error response { "success" false, "error code" "inventory unavailable", "error message" "product sku 001 is out of stock" } response requirements http status 200 (for success) or 400 500 (for errors) response time < 10 seconds content type application/json endpoint authentication forter supports two authentication methods for merchant endpoints both can be enabled simultaneously bearer token authentication forter sends your webhook secret as a bearer token in the authorization header authorization bearer {webhook secret} this is the simplest method verify the token matches your configured secret // node js example const webhooksecret = process env forter webhook secret; const authheader = req headers\['authorization']; if (authheader !== `bearer ${webhooksecret}`) { return res status(401) send('unauthorized'); } \# python example webhook secret = os environ get('forter webhook secret') auth header = request headers get('authorization') if auth header != f'bearer {webhook secret}' return 401 # unauthorized hmac sha256 payload signing forter signs the request body with hmac sha256 and sends the signature in a header {your store name} signature hmac sha256=abc123 important always verify the hmac signature to ensure the request body has not been tampered with \# python example import hmac import hashlib def verify signature(payload, signature, secret) computed = hmac new( secret encode('utf 8'), payload encode('utf 8'), hashlib sha256 ) hexdigest() expected = f"hmac sha256={computed}" return hmac compare digest(expected, signature) \# usage payload body = request body # raw request body signature header = request headers get('your store name signature') webhook secret = os environ get('forter webhook secret') if not verify signature(payload body, signature header, webhook secret) return 401 # unauthorized // node js example const crypto = require('crypto'); function verifysignature(payload, signature, secret) { const computed = crypto createhmac('sha256', secret) update(payload) digest('hex'); const expected = `hmac sha256=${computed}`; return crypto timingsafeequal( buffer from(expected), buffer from(signature) ); } // usage const payloadbody = req body; // raw request body const signatureheader = req headers\['your store name signature']; const webhooksecret = process env forter webhook secret; if (!verifysignature(payloadbody, signatureheader, webhooksecret)) { return res status(401) send('unauthorized'); } you can enable bearer token authentication, hmac payload signing, or both in the forter portal step 3 configure in forter portal log in to the forter portal and navigate to your store's configuration a merchant platform tab select custom platform and configure your three merchant endpoints field description example required account endpoint url customer account lookup "https //yourstore com/api/account" optional cart endpoint url cart pricing and shipping "https //yourstore com/api/cart" yes checkout endpoint url order creation "https //yourstore com/api/checkout" yes authentication enable bearer token auth toggle on/off recommended webhook secret secret for bearer token and/or hmac signing auto generated or custom yes payload signing enable hmac sha256 payload signing toggle on/off optional authentication and payload signing can be enabled independently or together authentication on — forter sends authorization bearer {secret} header payload signing on — forter sends {store name} signature hmac sha256={digest} header both on — both headers are sent on every request b ai platforms tab enable which ai platforms can sell your products field description chatgpt toggle to enable openai/chatgpt integration gemini toggle to enable google gemini integration search & discovery allow ai agents to browse and recommend your products checkout allow ai agents to complete purchases payment provider which payment provider processes orders (e g , stripe) c product feed tab field description example required feed url url to your hosted product feed "https //mycustomstore com/feed xml" yes feed format format of your feed "google" (google merchant center xml) yes update frequency how often to fetch every 24 hours yes feed active enable automatic fetching true yes feed username http basic auth username "api user" optional feed password http basic auth password •••••••• (encrypted) optional d store policies field description terms of service url link to your terms privacy policy url link to your privacy policy return policy url link to your return policy return window (days) days allowed for returns (e g , 30 ) e tax configuration field description example tax nexus regions us states where you collect sales tax \["ca", "ny", "tx"] f order status url (optional) field description example order status url template url for order tracking "https //mycustomstore com/orders/{order id}" the {order id} placeholder will be replaced with the order id from your checkout endpoint response step 4 payment & fraud settings (optional) by default, you handle payment validation and authorization in your webhook handler this section is only needed if you want forter to handle fraud detection and payments option a merchant side validation/authorization (default) what happens forter calls your webhook with order details and payment reference your webhook processes payment through your payment provider your webhook handles fraud checks through your existing rules configuration no additional setup needed this is the default behavior settings in portal enable forter validation false (default) enable forter authorization false (default) enable forter capture false (default) option b forter side validation/authorization (optional) what happens forter validates orders for fraud before calling your webhook forter authorizes/captures payments via forter payment orchestration your webhook receives orders with completed payment status configuration required contact your forter representative to obtain field description validation api key forter fraud detection credentials payment api key forter payment orchestration credentials settings in portal enable forter validation true enable forter authorization true enable forter capture true (or false for manual capture) step 5 testing a test feed fetch after configuring the feed url forter attempts to fetch your feed check forter portal logs for fetch status verify products appear in the portal common issues 403 forbidden check feed url is publicly accessible timeout ensure feed responds within 30 seconds parse error validate xml/csv format b use the portal endpoint test tool the forter portal includes an endpoint test tool that sends test requests to all three of your merchant endpoints and validates the responses navigate to merchant platform > test endpoints to run automated tests against your account, cart, and checkout endpoints c test endpoints with curl you can also test each endpoint manually test account endpoint secret="your webhook secret" curl x post https //yourstore com/api/account \\ h "content type application/json" \\ h "authorization bearer $secret" \\ d '{ "event" { "id" "test 001", "type" "account login", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "email" "test\@example com" }' expected response { "success" true, "status" "not found" } test cart endpoint curl x post https //yourstore com/api/cart \\ h "content type application/json" \\ h "authorization bearer $secret" \\ d '{ "event" { "id" "test 002", "type" "cart created", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "currency id" "usd", "items" \[{ "product id" "sku 001", "quantity" 1 }], "buyer" { "email" "test\@example com", "first name" "test", "last name" "user" } }' expected response { "success" true, "items" \[{ "product id" "sku 001", "quantity" 1, "price" 29 99, "effective price" 29 99, "subtotal" 29 99 }], "shipping options" \[{ "id" "standard", "title" "standard shipping", "description" "5 7 days", "price" 5 99 }], "totals" { "subtotal" 29 99, "discount" 0, "tax" 2 40, "shipping" 5 99, "total" 38 38 } } test checkout endpoint curl x post https //yourstore com/api/checkout \\ h "content type application/json" \\ h "authorization bearer $secret" \\ d '{ "event" { "id" "test 003", "type" "order created", "timestamp" "2026 02 09t12 00 00z" }, "agent" { "source" "openai", "platform" "chatgpt instant checkout" }, "currency id" "usd", "items" \[{ "product id" "sku 001", "quantity" 1, "price" 29 99, "effective price" 29 99, "subtotal" 29 99 }], "buyer" { "email" "test\@example com", "first name" "test", "last name" "user" }, "recipient" { "shipping id" "standard", "first name" "test", "last name" "user", "address" { "line one" "123 test st", "city" "san francisco", "region id" "ca", "country id" "us", "postal code" "94102" } }, "payment" { "provider" "stripe", "token" "tok test visa 4242", "card" { "brand" "visa", "last4" "4242", "exp month" 12, "exp year" 2027 } }, "totals" { "subtotal" 29 99, "discount" 0, "tax" 2 40, "shipping" 5 99, "total" 38 38 } }' expected response { "success" true, "order id" "ord 12345" } d end to end checkout test after testing individual endpoints, verify the full flow by triggering a purchase through an ai platform in test mode check your server logs to confirm all three endpoints were called in sequence account, cart, then checkout step 6 go live production checklist replace test credentials with production credentials verify production feed url is accessible test webhook endpoint with production domain verify https certificate is valid configure monitoring and error alerting test at least one production order end to end enable ai platform distribution (openai, google, etc ) monitoring use the forter portal to monitor feed health — fetch status, product count, parse errors webhook success — delivery rate, response times, errors order volume — checkout sessions, completions, failures error rates — failed webhooks, timeouts troubleshooting feed not fetching solution verify feed url returns 200 ok check content type header is correct ensure feed size is under 500mb test feed url in browser review forter portal logs for specific errors endpoint authentication failing solution bearer token verify authorization bearer {secret} header matches your configured webhook secret hmac signing verify webhook secret matches portal configuration hmac signing check you're using the raw request body (not parsed json) hmac signing ensure signature header name matches your store name use crypto timingsafeequal() for comparison (prevents timing attacks) check which auth methods are enabled in portal (authentication toggle, payload signing toggle) cart endpoint returning errors solution verify all items in the request have valid product id values matching your catalog ensure prices are returned in dollars (decimal) , not cents return shipping options array (at least one option required) return complete totals object with subtotal, discount, tax, shipping, total check response time is under 10 seconds checkout endpoint failing solution verify the payment token is being processed correctly by your payment provider check that totals in the request match what your cart endpoint returned ensure you return { "success" true, "order id" " " } on success process order asynchronously if needed (return 200 immediately, fulfill in background) add request timeout monitoring orders not created in your system solution check all three endpoint logs for errors (account, cart, checkout) verify endpoint urls are correct in portal use the portal endpoint test tool to validate all endpoints ensure each endpoint returns proper json responses best practices feed management update frequency daily for most merchants, hourly for high velocity inventory feed size keep under 100mb for faster processing (use pagination if larger) product data include high quality images, detailed descriptions, accurate pricing webhook security always verify signatures — never process unverified webhooks use https — never expose webhook endpoints over http rate limiting — implement rate limiting to prevent abuse idempotency — handle duplicate webhook calls gracefully (use order id as dedup key) error handling retry logic — forter will retry failed webhooks (exponential backoff, up to 3 times) alerting — monitor webhook failure rates logging — log all webhook calls for debugging quick reference supported feed formats google merchant center xml ( feed format "google" ) shopify csv ( feed format "shopify" ) json ( feed format "json" ) merchant endpoints endpoint event type fatal purpose account account login no customer lookup cart cart created , cart updated yes pricing, shipping, totals checkout order created yes order creation endpoint authentication bearer token authorization bearer {webhook secret} hmac signing {your store name} signature hmac sha256={hex digest} both methods can be enabled simultaneously in the forter portal required checkout response { "success" true, "order id" " " } next steps catalog & inventory docid\ zi2ppkf2jiiqfyijnqbui — product data synchronization details checkout & payments docid\ vd6rt6wkn75pli dxv5he — payment processing and order management faq docid bq5wl97vl zdwzglo9pl — common questions support for custom integration questions, contact your forter representative or email support\@forter com mailto\ support\@forter com