Troubleshooting

No Forter calls are happening at all

forterEnabled is false. This short-circuits every hook and the storefront snippet template. Check Merchant Tools > Site Preferences > Site Custom Preferences > Forter - Core Configuration.

int_forter_sfra isn't in the cartridge path, or isn't ordered before app_storefront_base. Check Administration > Sites > Manage Sites > [site] > Settings > Cartridges.

Metadata wasn't imported. Check whether the Forter - Core Configuration group exists at all under Site Custom Preferences. If it's missing, re-import metadata/site_template.zip.

The device fingerprint snippet isn't rendering. View source on any storefront page and search for ftr__script. If forterEnabled is true and forterSiteID is set but the tag is still missing, check for an empty or whitespace-only forterSiteID. See Logging and Snippet Verification.

The PSP declined the payment. postAuthorizationHandling.js only calls Forter when the payment authorized without error. A processor decline means no post-auth Forter call is ever made. This is expected behavior, not a bug.

If none of these explain it, confirm you're checking the right log: Forter writes to the custom forter category. See Logging and Snippet Verification.

401 Unauthorized on API calls

forterSecretKey and forterSiteID are both case-sensitive; check for leading or trailing whitespace from a paste. A wrong Site ID also routes calls to the wrong subdomain, and the resulting error can look like a credentials problem.

Validate call succeeds, but the decision doesn't appear on the order

Check forterAuthTiming. Under PRE_AUTH, the decision depends on the session.privacy to order.custom mirror in postAuthorizationHandling.js.

Confirm app.post.auth is still registered to ./hooks/postAuthorizationHandling in hooks.json.

Check for a shadowed checkoutHelpers.js. If a cartridge earlier in the path defines its own cartridge/scripts/checkout/checkoutHelpers.js, it can override the Forter one. Enable forterEnableDebugLogging, place a test order, and search the log for Entering Forter pre-auth processing for order {N}. If that line appears but order.custom.forterDecision is still empty, the override is almost certainly shadowing it.

Confirm the custom attributes exist on the Order object: forterDecision, forterOrderLink, forterRecommendations, forterReasonCode, forterRetryNumber. If metadata import failed, these won't exist and the mirror writes silently fail.

Confirm bm_forter is in the Business Manager cartridge path: Administration > Sites > Manage Sites > Business Manager > Settings > Cartridges.

Confirm the Forter module is enabled for your role: Administration > Organization > Roles & Permissions > [Role] > Business Manager Modules > Forter.

Log out and back in. Business Manager sometimes caches menu definitions.

ForterOrderUpdateSFRA job runs but updates no orders

The job only targets orders with forterDecision set to APPROVED, DECLINED, or NOT_REVIEWED. Orders with FAILED or ERROR decisions are intentionally excluded and never sync. See Order Status Sync.

The job also only looks back forterWeeksAmount weeks from today. An order older than that window won't sync, regardless of its decision. See Configure Decisions.

Confirm the job is scheduled for the correct site. Jobs are site-scoped.

Confirm the forter.rest.update service is reachable via Administration > Operations > Services. Its credential URL should be api.forter-secure.com/v3/platforms/sfcc/status/, with no https:// prefix. The service constructs https://{siteId}. at runtime.

Confirm a mapper template is deployed for your site. The status endpoint routes through Forter's backend mapper. If the per-site template is missing, every status call returns 500 and the job silently fails every order. Contact your Forter implementation team to confirm it's in place.

Pre-auth works for registered customers but not guest checkout

The cartridge has no branching on customer type. If this happens, it's almost always in the merchant's own code:

A custom Checkout.js or CheckoutServices.js override that skips logic for guests.

basket.custom.forterPreAuthOrderNo missing on the guest basket. It's a standard system custom attribute and works for guest baskets by default; if it's missing, metadata wasn't imported.

Forter is blocking checkout with no decline reason

Only a void processorAction should ever block checkout. Anything else blocking checkout is a cartridge bug.

Search custom-forter-*.log for Forter pre-auth threw or Forter post-auth threw. Either means a non-void exception is bubbling past the fail-open try/catch.

Check PlaceOrderError.code. On a real void decision, the customer-facing error message derives from this code. If it's empty, the decision object is malformed.

PII is leaking into production logs

Confirm forterEnableDebugLogging isn't true in production. Flip it to false immediately.

Search the merchant's own cartridge code for log.info or log.debug calls that reference basket, customer, or payment-instrument data directly.

Calls are failing intermittently or timing out

Check the forter.prof service profile: Administration > Operations > Services > Service Profiles > forter.prof. It ships with a 5-second connection timeout and a rate limit of 5 calls per 10 seconds. Raise both if your order volume needs it.

A throttled or timed-out call fails open, so checkout proceeds without a decision instead of showing a visible error. Check custom-forter-*.log for retry and fail-open messages.

General diagnostic approach

For anything not on this list:

Set forterEnableDebugLogging to true in sandbox.

Place a test order and watch custom-forter-*.log line by line.

Look for the hook markers Entering Forter pre-auth processing for order {N} and Entering Forter post-auth processing for order {N}. Whichever is missing narrows the problem to that hook's registration or an early return.

Inspect session.privacy and basket.custom mid-checkout, via a debug log or script debugger.

If the behavior still doesn't match what's documented for the cartridge, it's most likely a shadowed override or a metadata gap.