Class FraudAppHooks
dw.apps.checkout.hooks
Class FraudAppHooks
dw.apps.checkout.hooks.FraudAppHooks
This interface defines Commerce App hook extension points for the fraud domain.

These hooks provide integration points for external fraud detection services installed via the Commerce App framework. They enable ISV fraud providers to perform risk assessments at key points in the payment lifecycle.

IMPORTANT: These hooks should only be implemented and registered by Commerce Apps (applications installed via the Commerce App framework with a CAP file). They are not intended for custom merchant cartridges or storefront implementations.

Hook Registration

A function must be defined inside a JavaScript source and must be exported. The script with the exported hook function must be located inside a site cartridge. Inside the site cartridge a package.json file with a 'hooks' entry must exist: 

 "hooks": "./hooks.json"

The hooks entry links to a JSON file, relative to the package.json file. This file lists all registered hooks inside the hooks property: 

 "hooks": [
      {"name": "sfcc.app.fraud.beforePayment", "script": "./beforePayment.js"},
      {"name": "sfcc.app.fraud.afterPayment", "script": "./afterPayment.js"}
 ]

A hook entry has a name and a script property:

  • The name contains the extension point name (the hook name).
  • The script contains the script path relative to the hooks file, with the exported hook function.

Function Naming Convention: The exported JavaScript function name must match the last segment of the extension point name: beforePayment.

Lifecycle Context

The beforePayment hook fires as a pre-authorization fraud check. It is invoked during basket-to-order conversion when fraud assessment conditions are met. The hook fires on each attempt to create an order from the basket, after all Basket Payment Instruments have been created and payment details are available, but before order creation and before payment authorization/capture is attempted.

The afterPayment hook fires as a post-authorization fraud check. It is invoked by the platform when ALL payment instruments on the Order have reached AUTHORIZED or CAPTURED status. The hook fires after payment authorization/capture succeeds but before the order is placed.

Decision Values and Storefront Behavior

beforePayment Decisions (Pre-Authorization)

Decision Meaning Storefront Behavior
APPROVED Transaction is deemed safe Proceed with basket-to-order conversion
DECLINED Transaction is deemed unsafe Block checkout - do NOT create order
CHALLENGE Transaction requires further verification Proceed with additional authentication challenges during authorization

afterPayment Decisions (Post-Authorization)

Decision Meaning Storefront Behavior
GUARANTEED Order is guaranteed against chargebacks by the fraud ISV Proceed with order placement
NOT_GUARANTEED Order is not guaranteed; ISV recommends rejection Block checkout - fail order and trigger payment reversal
PENDING ISV decision is pending; will arrive asynchronously via webhook Hold order in CREATED status

Hook Precedence

  • When sfcc.app.fraud.beforePayment is registered by a Commerce App, the platform invokes it during the basket-to-order conversion.
  • When sfcc.app.fraud.afterPayment is registered by a Commerce App, the platform invokes it after all payment instruments are authorized/captured.
  • If the Commerce App hook is not registered (no fraud app installed), the platform skips the fraud check and records the pre-auth and post-auth fraud results as NOT_REVIEWED by default.

Error Handling

beforePayment

  • Approve: Set PaymentTransaction.PRE_AUTH_FRAUD_DECISION_APPROVED on the approved payment transaction(s) and return Status.OK with code PRE_AUTH_FRAUD_DECISION_APPROVED. The platform continues the basket-to-order transition.
  • Challenge: Set PaymentTransaction.PRE_AUTH_FRAUD_DECISION_CHALLENGE on the payment transaction(s) to challenge, and return Status.OK with code PRE_AUTH_FRAUD_DECISION_CHALLENGE. The platform continues the basket-to-order transition. The payment ISV will perform additional authentication challenges during authorization
  • Decline (blocking): Set PaymentTransaction.PRE_AUTH_FRAUD_DECISION_DECLINED on the declined payment transaction(s) and return Status.ERROR with code PRE_AUTH_FRAUD_DECISION_DECLINED. The platform rolls back the basket-to-order transition and returns an error to the caller.
  • Exception: If the hook throws an exception (including timeout), the platform treats the transaction as for Decline above

afterPayment

Constants
extensionPointAfterPayment  :  String = "sfcc.app.fraud.afterPayment"
The extension point name sfcc.app.fraud.afterPayment.
extensionPointBeforePayment  :  String = "sfcc.app.fraud.beforePayment"
The extension point name sfcc.app.fraud.beforePayment.
Properties
Constructor Summary
This class does not have a constructor, so you cannot create it directly.
Method Summary
afterPayment(order : Order) : Status
The function is called by extension point extensionPointAfterPayment.
beforePayment(basket : Basket) : Status
The function is called by extension point extensionPointBeforePayment.
Method Detail
afterPayment
afterPayment(order : Order) : Status
The function is called by extension point extensionPointAfterPayment. It performs a post-authorization fraud assessment after all payment instruments on the Order have been authorized or captured.

This hook supports two integration patterns:

Synchronous Pattern

Call the fraud service during hook execution and return a decision immediately. If the order is guaranteed, set POST_AUTH_FRAUD_DECISION_GUARANTEED and return Status.OK with code POST_AUTH_FRAUD_DECISION_GUARANTEED to proceed with order placement. If the order is not guaranteed, set POST_AUTH_FRAUD_DECISION_NOT_GUARANTEED and return Status.ERROR with code POST_AUTH_FRAUD_DECISION_NOT_GUARANTEED to fail the order. If there is an error calling the fraud service, return Status.ERROR.

Asynchronous Pattern

Submit the order to the fraud service but do not wait for a decision. Set the post auth fraud decision in the payment transaction details to POST_AUTH_FRAUD_DECISION_PENDING and return Status.OK. If there is an error submitting the order, return Status.ERROR.

Later when the fraud service webhook arrives with a decision for the order, set the post auth fraud decision to the corresponding value. Call OrderMgr.attemptOrderTransition(Order) to proceed with order placement, or call OrderMgr.failOrder(Order, Boolean) to fail the order.

Do not call OrderMgr methods directly in a hook implementation. The platform will use the decision to determine the next course of action. Only call those methods in an asynchronous webhook handler.

Note: to omit a post-authorization fraud check, set code POST_AUTH_FRAUD_DECISION_NOT_REVIEWED and return Status.OK.

Error Handling:

  • If the hook implementation returns null or throws an error, the platform will behave as for Status.ERROR
Parameters:
order - the order for which to perform a post-authorization fraud assessment
Returns:
Status.OK or Status.ERROR
beforePayment
beforePayment(basket : Basket) : Status
The function is called by extension point extensionPointBeforePayment. It performs a pre-authorization fraud assessment after a Basket Payment Instrument has been created and payment details are available, but before order creation and before payment authorization/capture is attempted.

Error Handling:

  • Status.OK with code PRE_AUTH_FRAUD_DECISION_APPROVED — Proceed with payment authorization.
  • Status.OK with code PRE_AUTH_FRAUD_DECISION_CHALLENGE — Proceed with additional authentication challenges.
  • Status.ERROR with code PRE_AUTH_FRAUD_DECISION_DECLINED — Block order creation.
  • Exception (including timeout) — Platform treats as Status.ERROR.

The ISV can persist shopper-specific pre-auth fraud signals as custom attributes on the Basket. ISV-specific outputs such as a risk score or a reason code also can be persisted as custom attributes on the Basket within hook execution, if needed.

Note: to omit a pre-authorization fraud check, set code PRE_AUTH_FRAUD_DECISION_NOT_REVIEWED and return Status.OK.

Timeout: ISVs must configure HTTP timeouts via LocalServiceRegistry.

Parameters:
basket - the fully calculated basket being checked out
Returns:
Status.OK to proceed or Status.ERROR to block.