Fraud Decisioning: how orchestration layers integrate with Signifyd and Riskified

In a payment orchestration stack, the fraud decisioning engine sits at one of two points: pre-authorization as an advisory check that runs before the PSP call, or post-authorization as a decisioning layer that runs after the PSP returns an auth response and can hold the payment for manual review. Where it sits determines what data the fraud provider can see, which payment methods are eligible, and what the orchestrator is allowed to do with the response. Hyperswitch ships native Fraud and Risk Management (FRM) connectors for Signifyd and Riskified, configured at the per-gateway, per-payment-method level, with flow: "pre" or flow: "post" selected independently for each combination.

This post covers how FRM connectors integrate with Hyperswitch, what each provider's API surface looks like at the call sites Hyperswitch actually uses, and where the boundary sits between the fraud provider, the orchestrator, and the downstream PSP - Adyen, Stripe, Worldpay, Cybersource, and the rest of the connector roster.

Why FRM sits adjacent to the orchestrator, not inside it

Hyperswitch does not score fraud. It assembles the order context from the merchant's payment intent, calls Signifyd or Riskified at the configured lifecycle point, normalizes the decision into the frm_message artifact attached to the payment, and acts on that decision at the routing layer. The decision itself and the chargeback liability that comes attached to it is owned by the FRM provider, depending on the product type being used by the merchant.

All FRM platforms offer fraud scoring and decisioning, but differ on liability. Adyen RevenueProtect is score-only with no chargeback indemnification, liability always stays with the merchant. Stripe Radar is also score-only by default, but has an optional Chargeback Protection add-on with reimbursement. Riskified backs every approved order with a full chargeback guarantee as its core, non-negotiable model. Signifyd offers both models, a guaranteed model where it assumes full liability, and a non-guaranteed tier where merchants retain liability but get help fighting disputes.

This liability shift along with the merchant industry is what changes the integration shape: the fraud provider needs to see the full transaction context like cart, customer, device, shipping, billing before underwriting it, and that's more data than a PSP authorization request carries.

Hyperswitch's job is to assemble that context once, send it through whichever FRM provider the merchant has configured for the gateway and payment method in play, and route the response into the rest of the payment lifecycle.

The two integration positions

FRM in Hyperswitch is configured per (gateway, payment method) pair via the frm_configs block on the merchant connector account:

"frm_configs": [
  {
    "gateway": "stripe",
    "payment_methods": [
      { "payment_method": "card",   "flow": "post" },
      { "payment_method": "card", "flow": "pre"  }
    ]
  },
  {
    "gateway": "adyen",
    "payment_methods": [
      { "payment_method": "card", "flow": "pre" }
    ]
  }
]

The FRM connector identity (Signifyd or Riskified) is set once per merchant connector account; the lifecycle position is set per (gateway, payment method) pair underneath it.

Pre-authorization fraud check

The pre-auth flow is supported for any payment method but is pre-dominantly used for cards. Transaction details are sent to the FRM provider before any PSP call, and Hyperswitch acts on the response Accept or Decline. In Hyperswitch's current pre-auth contract, the configured action is "Continue on Accept" or “Cancel on Reject”.

Post-authorization fraud check

Post-auth is card-only in Hyperswitch and is the flow with the richer state machine. The PSP authorization runs first, and the FRM call happens against the resulting authorization plus the order context. Post-auth supports three actions: continue on Accept, halt on Decline, and Review for manual review. A Review decision moves the Hyperswitch payment into the Requires Merchant Action state. This is a canonical Hyperswitch state for "held for human decision." The merchant's review on the FRM provider's dashboard is then mirrored back via webhook: an approval triggers capture, a decline triggers void.

The constraint that triggers people: post-auth manual review requires the underlying PSP to support manual capture. If the gateway leg in question is configured for automatic capture, the auth has already settled by the time the review webhook lands and the payment cannot cleanly transition through Review. Hyperswitch requires that any connector configured for post-authorization manual review must support manual capture. Routing a manually reviewed order through an auto-capture-only connector will bypass the intended hold, defeating the purpose of the review step.

Signifyd integration architecture

Signifyd's API surface for the Hyperswitch integration centers on two endpoints: the pre-auth Checkout endpoint and the post-auth Sale endpoint, both keyed on orderId.

The decision endpoints

POST https://api.signifyd.com/v3/orders/events/checkouts # pre-auth
POST https://api.signifyd.com/v3/orders/events/sale # post-auth

Both accept the same order schema: orderId, purchase block (cart items, totals, currency), userAccount, recipient, transactions, and device-level fingerprint data. The decision is returned synchronously inside decision.checkpointAction, which is one of:

ACCEPT - Signifyd recommends approval; the guarantee attaches
REJECT - Signifyd recommends decline
HOLD - held for manual review by a Signifyd analyst
CHALLENGE - Signifyd recommends 3DS challenge or another verification step

Hyperswitch maps these into its internal frm_status. ACCEPT becomes the continuation path. REJECT halts on Decline (post-auth only). HOLD is what surfaces the payment as Requires Merchant Action in Hyperswitch. Signifyd's hold SLA is measured in minutes to hours depending on the merchant's plan, which is exactly why this state exists as a discrete payment status rather than a synchronous wait.

orderId as primary key for deduplication

Signifyd's API treats orderId as the primary key for an order across attempts. Sending another Checkout event with the same orderId updates the existing order and generates a new decision, up to 100 updates beyond which Signifyd will return REJECT automatically.

Webhooks for state changes

Signifyd fires webhooks on case decisioning, guarantee disposition changes, and order updates. Hyperswitch's connector verifies the webhook signature and updates the frm_message on the payment. Signifyd retries failed webhooks up to 15 times over four days; an endpoint that returns anything outside the 2xx range is treated as a failure.

Signifyd boundary statement

Signifyd owns: the ML model that produces the recommendation for the merchant, the chargeback guarantee on ACCEPT decisions, the review queue for HOLD cases, and the post-purchase signals that can revoke guaranteeDisposition.

Hyperswitch owns: assembly of the checkouts or sale payload from the payment intent, mapping Signifyd recommendation to the internal frm_status, transitioning the payment into the right statuses like Requires Merchant Action on HOLD, webhook retroval and action, and persisting caseId and guaranteeDisposition against the payment_id.

The orderId (Hyperswitch's payment_id) is the artifact that crosses this boundary in both directions. It's what guarantee claims submitted to Signifyd's claims API are keyed on.

Riskified integration architecture

Riskified's contract is structurally different. Decisioning runs through /api/decide, which can be configured to fire either before or after PSP authorization. Riskified's account configuration determines when the synchronous Decide call happens, and the integration has to match that configuration.

The endpoint set

POST {sync_base}/api/decide # synchronous decision
POST {base}/api/checkout_create # register checkout (pre-auth flow)
POST {base}/api/checkout_denied # notify if PSP declined the auth
POST {base}/api/decision # notify of merchant approve/decline

/api/decide is the call that returns the actual decision; it lives on Riskified's synchronous analyze base URL, which is distinct from the base URL used for the lifecycle notification endpoints. The decision response status field is one of:

Approved - proceed with the payment (or capture, depending on flow)
Declined - decline the payment
Submitted - Riskified will decision asynchronously and notify via the configured endpoint

The submitted status is the awkward one for synchronous checkout: Hyperswitch cannot hold a customer's checkout open indefinitely waiting for an async decision. The connector handles this by treating submitted the same as it treats Signifyd's HOLD. The payment moves to Requires Merchant Action and the eventual decision webhook resolves it.

HMAC-SHA256 signature verification

Riskified webhooks are signed using HMAC-SHA256 over the request body, with the signature placed in the X-RISKIFIED-HMAC-SHA256 header. Hyperswitch's connector verifies this header against the shared secret stored in the merchant connector account before acting on the decision. A signature mismatch causes the webhook to be rejected with a 401 — which is correct security behavior, but is also the most common reason webhooks "stop working" after a credential rotation in Riskified's dashboard.

The lifecycle notification surface

Riskified expects merchants to call /api/checkout_denied when the PSP declines the auth, and /api/decision when the merchant manually approves or declines an order. These are feedback endpoints that improve Riskified's model. Hyperswitch fires /api/checkout_denied automatically when the PSP returns a hard decline on a transaction Riskified had advised on, and surfaces /api/decision as part of the manual review resolution flow.

Riskified boundary statement

Riskified owns: the ML model behind /api/decide, the chargeback guarantee on approved transactions, the storefront beacon that captures device and behavioral data on the checkout page, and the asynchronous review pipeline that resolves submitted cases.

Hyperswitch owns: matching the integration's call sequencing to whether Riskified is configured for pre-auth or post-auth decisioning, verification and consumption of inbound webhooks, the state machine that handles submitted payments without timing out the merchant, and firing /api/checkout_denied and /api/decision lifecycle notifications at the right moments.

Configuring FRM in Hyperswitch

FRM connectors are configured under the FRM Processor in the Hyperswitch dashboard, with credentials passed through the connector authentication block. From the Hyperswitch code base perspective the relevant transformer files live under crates/hyperswitch_connectors/src/connectors/signifyd/ and crates/hyperswitch_connectors/src/connectors/riskified/.

Provider	Auth surface	Notes
Signifyd	API key (Basic auth, key as username with empty password)	Webhook secret stored separately for signature verification
Riskified	Shop URL + auth token	HMAC-SHA256 secret used both for signing outbound calls and verifying inbound webhooks

What breaks - failure modes

Post-auth manual review configured against a connector without manual capture

Symptom: Payments routed to a particular gateway with post-auth FRM never enter the Requires Merchant Action state cleanly. Either the auth captures automatically before review can happen, or the review webhook returns and Hyperswitch tries to capture an already-captured payment.

Root cause: Post-auth manual review only works when the underlying gateway is in manual capture mode, so Hyperswitch can hold the auth open and capture (or void) once the review decision lands. If the gateway leg is set to automatic capture, the funds have already moved by the time review completes.

Fix: Either switch the gateway leg to manual capture in the connector configuration, or move FRM to pre-auth for that gateway, or skip the Review action and configure FRM to act only on Accept/Decline. This is documented as an explicit warning in Hyperswitch's FRM activation guide.

Riskified HMAC verification failing after credential rotation

Symptom: Riskified webhooks rejected by Hyperswitch with 401, payments stuck in Requires Merchant Action indefinitely.

Root cause: The auth token stored in Hyperswitch's Riskified connector configuration does not match the active token in Riskified's dashboard. Riskified's /api/decide calls work fine with the old token until rotation propagates, so the failure mode shows up only on inbound webhooks where the stale token is used to verify the HMAC.

Fix: Update the auth token in the Riskified connector configuration in Hyperswitch. Riskified retries failed webhooks but a credential mismatch will exhaust those retries before the operator notices. Backlogged decisions need to be replayed from Riskified's Control Center after the fix.

Signifyd orderId not stable across smart retries

Symptom: Signifyd's decision quality on retried payments is materially worse than on first attempts. Approval rates drop on traffic that hits the retry path.

Root cause: A custom integration is using the Hyperswitch attempt_id (which changes per retry) rather than the payment_id (which is stable across the payment lifecycle) as the Signifyd orderId. Signifyd treats each retry as a fresh order with no context from prior attempts, and its model penalizes the velocity it sees.

Fix: Use payment_id as orderId. The default Signifyd connector in Hyperswitch already does this — this failure mode shows up in custom integrations or when overriding the default mapping. The right behavior is to let Signifyd see the retry chain as updates to a single order so its model can interpret the velocity correctly.

How new FRM connectors slot in

Hyperswitch's connector model is the same for FRM as for PSPs and vaults. Adding a new fraud provider namely Forter, Sift, Kount, ClearSale, NoFraud means writing a new connector under crates/hyperswitch_connectors/src/connectors/<name>/ with a transformers.rs that maps the provider's API into Hyperswitch's internal request and response types. The trait the FRM-specific code implements is shared across the FRM connectors, so once a provider's request/response transformers are written, the lifecycle hooks (pre-auth, post-auth, webhook handling, manual review state transitions) come from the same code path that Signifyd and Riskified use.

This is what makes the architecture transferable: a merchant who runs Signifyd today and decides to add a second FRM provider for a specific traffic segment doesn't change anything about the payment lifecycle they configure a second merchant connector account, set the frm_routing_algorithm to split traffic, and let the new provider's transformers handle the API shape differences.

The frm_message block on the payment carries the decision artifact across providers in a normalized form: frm_name, frm_transaction_id (the provider's case or order ID), frm_status (the normalized status), and frm_reason (the provider-specific reason code, preserved unaltered for the merchant's downstream pipeline). Chargeback claims submitted to the FRM provider's claims API are keyed on frm_transaction_id.

Industries

Solutions