High-quality widget
",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](https://docs.forter.com/quickstart-custom#b-host-feed-at-stable-url) Host your feed file at a publicly accessible URL: ```plaintext 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)](https://docs.forter.com/quickstart-custom#c-feed-authentication-optional) If your feed requires authentication: - **HTTP Basic Auth (Supported):** ```plaintext Username: your_username Password: your_password ``` **Forter will send:** ```plaintext Authorization: Basic base64(username:password) ``` ## [Step 2: Implement Merchant Endpoints](https://docs.forter.com/quickstart-custom#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: ```json { "event": {"id":"uuid","type":"...","timestamp":"2026-02-09T12:00:00Z"}, "agent": {"source":"openai","platform":"chatgpt_instant_checkout"}, ... } ``` ### [Step 2A: Implement Account Endpoint](https://docs.forter.com/quickstart-custom#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:** ```json { "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:** ```json { "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)](https://docs.forter.com/quickstart-custom#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:** ```json { "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" } } } ``` **Response:** ```json { "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 } } ``` | 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)](https://docs.forter.com/quickstart-custom#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:** ```json { "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 } } ``` **Success Response:** ```json { "success": true, "order_id": "ORD-12345" } ``` **Error Response:** ```json { "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 ## [Step 3: Configure in Forter Portal](https://docs.forter.com/quickstart-custom#step-3-configure-in-forter-portal) Log in to the Forter Portal and navigate to your store's configuration. ### [A. Merchant Platform Tab](https://docs.forter.com/quickstart-custom#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 | ### [B. AI Platforms Tab](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#e-tax-configuration) | Field | Description | Example | |----------------------------|------------------------------------------|----------------------------------| | **Tax Nexus Regions** | US states where you collect sales tax | ["CA", "NY", "TX"] | ### [F. Order Status URL (Optional)](https://docs.forter.com/quickstart-custom#f-order-status-url-optional) | Field | Description | Example | |--------------------------------|-----------------------------------|-------------------------------------------------------| | **Order Status URL Template** | URL for order tracking | "https://mycustomstore.com/orders/{order_id}" | ## [Step 4: Payment & Fraud Settings (Optional)](https://docs.forter.com/quickstart-custom#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)](https://docs.forter.com/quickstart-custom#option-a-merchant-side-validationauthorization-def) **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. ### [Option B: Forter-Side Validation/Authorization (Optional)](https://docs.forter.com/quickstart-custom#option-b-forter-side-validationauthorization-optio) **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 | ## [Step 5: Testing](https://docs.forter.com/quickstart-custom#step-5-testing) ### [A. Test Feed Fetch](https://docs.forter.com/quickstart-custom#a-test-feed-fetch) After configuring the feed URL: 1. Forter attempts to fetch your feed 2. Check Forter Portal logs for fetch status 3. 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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#c-test-endpoints-with-curl) You can also test each endpoint manually: **Test Account Endpoint:** ```bash 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:** ```json {"success":true,"status":"not_found"} ``` **Test Cart Endpoint:** ```bash 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:** ```json { "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:** ```bash 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:** ```json {"success":true,"order_id":"ORD-12345"} ``` ### [D. End-to-End Checkout Test](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#step-6-go-live) ### [Production Checklist](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#troubleshooting) ### [Feed not fetching](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#best-practices) ### [Feed Management](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#quick-reference) ### [Supported Feed Formats](https://docs.forter.com/quickstart-custom#supported-feed-formats) - **Google Merchant Center XML** (feed_format: "google") - **Shopify CSV** (feed_format: "shopify") - **JSON** (feed_format: "json") ### [Merchant Endpoints](https://docs.forter.com/quickstart-custom#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](https://docs.forter.com/quickstart-custom#endpoint-authentication-1) **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](https://docs.forter.com/quickstart-custom#required-checkout-response) ```json { "success": true, "order_id": "..." } ``` ## [Next Steps](https://docs.forter.com/quickstart-custom#next-steps) - [Catalog & Inventory](https://docs.forter.com/catalog-and-inventory-orchestration) — Product data synchronization details - [Checkout & Payments](https://docs.forter.com/checkout-and-payments) — Payment processing and order management - [FAQ](https://docs.forter.com/faq) — Common questions ## [Support](https://docs.forter.com/quickstart-custom#support) For custom integration questions, contact your Forter representative or email support@forter.com.