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

How It Works

With custom integration, you:

1. Host a product feed at a stable URL (Google Merchant Center XML, Shopify CSV, or JSON file)
2. Implement three merchant endpoints — Account, Cart, and Checkout — to handle the checkout lifecycle
3. Process orders in your backend system

Forter:

1. Fetches your feed periodically (hourly, daily, or custom schedule)
2. Generates and maintains the AI-optimized product data
3. 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)

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"},
  ...
}

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"
}

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"
    }
  }
}

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
  }
}

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
  }
}

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

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:

B. AI Platforms Tab

Enable which AI platforms can sell your products:

C. Product Feed Tab

D. Store Policies

E. Tax Configuration

F. Order Status URL (Optional)

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.

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

Step 5: Testing

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

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 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 — Product data synchronization details
• Checkout & Payments — Payment processing and order management
• FAQ — Common questions

Support

For custom integration questions, contact your Forter representative or email support@forter.com.