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 IntegrationShopify Integration or SFCC IntegrationSFCC Integration.

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": "[email protected]",
  "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": "[email protected]",
    "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": "[email protected]",
    "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

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": "[email protected]"
  }'

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": "[email protected]", "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": "[email protected]", "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 & InventoryCatalog & Inventory — Product data synchronization details

Checkout & PaymentsCheckout & Payments — Payment processing and order management

FAQFAQ — Common questions

Support

For custom integration questions, contact your Forter representative or email [email protected].