Sonar

Sonar is Frame's buy-side fraud protection. When a customer reaches your checkout, frame-js running in their browser captures device, behavioral, and contextual signals; when you create a charge, Sonar evaluates those signals against fraud patterns and decides whether to allow the transaction, flag it for review, or block it outright. The evaluation is automatic — there's no Sonar-specific API to call, just data Frame collects + decisions Frame makes during the normal charge flow.

Sonar is the buy-side half of Frame's risk surface. The seller-side equivalent — monitoring creators and sellers receiving funds for risk signals — is Creator Shield. Both run on Frame's risk infrastructure but they evaluate different concerns: Sonar catches bad buyers; Creator Shield catches bad sellers.

What Sonar evaluates

Sonar pulls signals from several sources:

• Device fingerprinting — the browser/device the customer is checking out from, including hardware patterns, browser configuration, IP geolocation. Captured by frame-js running in the customer's browser.
• Behavioral signals — how the customer navigated your site before checkout (rapid form-filling, copy-paste patterns, multi-tab activity, time on page). Captured by frame-js when it's loaded site-wide, not just on the checkout page.
• Velocity patterns — how often this card or device has been used recently across Frame's network. A single card hitting many merchants in rapid succession is a fraud signal even if any individual charge looks fine.
• Cross-merchant patterns — Frame's risk model spans the whole platform. A card that just failed at five other merchants for fraud is risky here regardless of whether your platform has seen it before.
• Network risk signals — issuer-side flags, card-network blacklists, address-mismatch patterns.

The more signal Sonar has, the better the decision. Loading frame-js site-wide (not just on the checkout page) gives Sonar the behavioral observation window it needs; including customer profile data (name, email, billing/shipping address) on the charge gives it cross-correlation points.

How it integrates

Sonar is invisible from the merchant's perspective in the happy path:

1. Frame.js initializes on your site. A Sonar session is created automatically and stored in localStorage under frame_charge_session_id.
2. Customer browses + checks out. Sonar collects signals throughout.
3. You create a charge and include the sonar_session_id from the client. Frame links the charge to the Sonar session and its accumulated signals.
4. Frame evaluates during the charge-completion pipeline. The signals Sonar collected feed Frame's fraud-decision engine (implemented via a Sift workflow under the hood — Sonar is the merchant-facing product name for the signal layer + decisioning together). If the workflow returns a clear/approve decision, the charge proceeds normally. If it returns suspicious, the charge fails with a fraud-related decline code — typically fraudulent.
5. Outcomes feed back — disputes, chargebacks, and refunds on Sonar-evaluated transactions become training signal for future evaluations. The model improves over time.

For the implementation pattern, see Set up Sonar fraud protection.

When Sonar blocks

A blocked transaction shows up as a failed transfer with one of these failure codes:

• fraudulent — Sonar flagged the transaction as fraud based on its signal evaluation.
• merchant_blacklist — the card or device matches an entry on your platform's block list (managed via the dashboard).
• do_not_honor / generic_decline — the issuer declined for fraud-related reasons after Sonar passed the request through (Sonar's evaluation is one of several gates).

The merchant best practice: surface all of these as a generic error message to the customer. Don't disclose that fraud detection blocked the transaction — see decline codes for the rationale.

Tuning vs no-tuning

Sonar runs out of the box without configuration. For most platforms, the default model is the right answer. But:

• High-risk verticals (gaming, alcohol, adult content) can request stricter thresholds.
• Low-risk verticals (B2B SaaS, established marketplaces) can request looser thresholds to reduce false positives.
• Platform-specific block lists let you blacklist specific cards, emails, or device fingerprints that have given you trouble historically, regardless of Sonar's score.

Tuning happens through Frame's risk operations team, not through a self-service API. Talk to Frame support if your fraud rates or false-positive rates aren't where you want them.

Frame.js is the foundation

The single biggest factor in Sonar quality is frame-js coverage. The minimum is loading frame-js on your checkout page; the actual recommendation is loading it on every page of your site so Sonar can observe behavior leading up to checkout.

<script src="https://js.framepayments.com/v1/frame.js"></script>

A few rules:

• Load from js.framepayments.com, not a local copy. Local copies miss Sonar's tracking JavaScript updates and degrade fraud detection significantly.
• Initialize early. Frame.init(publishable_key) should run on page load so the Sonar session starts immediately.
• Pass sonar_session_id on every charge — retrieve it from localStorage.getItem('frame_charge_session_id') on the client and forward it to your backend.

Privacy

Sonar collects information on devices and user behavior. Your privacy policy should disclose this. Frame's suggested language (not legal advice — consult counsel):

We use Frame for payment processing, analytics, and other business services. Frame collects information about devices that connect to its services and uses this data to operate and improve its services, including fraud detection. You can learn more about Frame and read its privacy policy at https://framepayments.com/privacy.

Sonar vs Creator Shield vs 3D Secure

Three related-but-distinct fraud surfaces:

Production platforms run all three. They cover different threat models and stack additively.

Gotchas

Symptom: Sonar's false-positive rate is too high — legitimate customers are being blocked. Why: the default model errs on caution for new platforms. Without behavioral history, ambiguous transactions get flagged. Fix: contact Frame support to tune thresholds, and load frame-js site-wide (not just checkout) to give Sonar more context. The signal gap on isolated-checkout-only integrations is the most common cause of high false positives.

Symptom: you didn't include sonar_session_id on a charge and got an unexpected decline. Why: without a Sonar session, Frame can't evaluate the transaction against device/behavioral signals — depending on your platform's risk configuration, that absence may itself be a soft signal that downgrades the transaction's risk score. Fix: always include sonar_session_id from frame-js's localStorage on every charge.

Symptom: you load frame-js from a CDN copy and Sonar's quality has degraded. Why: local copies don't auto-update with Sonar's continually-improving tracking code, so signal quality decays over time. Fix: always load from https://js.framepayments.com/v1/frame.js. The CDN versions are designed to be loaded directly.

Reference

For the charge flow that includes Sonar evaluation, see POST/v1/transfers. For the integration walk-through, see Set up Sonar fraud protection.