Fraud Commerce Apps (Beta)
Fraud Commerce Apps is a beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this beta service is at the Customer’s sole discretion.
Breaking changes are possible until GA. While these domains are in beta, Salesforce reserves the right to change hook signatures, extension-point names, data model field names and shapes (including paymentDetails and transactionDetails), Script API surfaces introduced for these domains, and commerce-app.json manifest fields, without the notice period or deprecation window that applies to GA APIs. Changes will be included in release notes for the release in which they land. Once GA is declared, standard backward-compatibility guarantees apply from that point forward.
A fraud Commerce App runs risk assessments at two points around payment authorization and returns decisions that steer order creation and order placement. It has two parts: hooks that run on the server and, optionally, extension components in the Storefront Next storefront that collect device data.
- Payments Orchestration is enabled on the instance. The feature toggle
PaymentFraudOrchestrationEnabledis off by default. Contact Salesforce Customer Support to enable it. - SCAPI hook execution is enabled. The feature toggle
ScapiHookExecutionEnabledis off by default. Contact Salesforce Customer Support to enable it. - Your app is installed on the site.
- Your app registers at least one fraud hook. An app that registers neither
beforePaymentnorafterPaymenthas no effect. If it registers only one, the other phase is recorded asNOT_REVIEWED.
Unlike payment, a fraud Commerce App doesn’t claim payment methods. The platform dispatches the fraud extension points for every checkout after the prerequisites are met, and only one fraud Commerce App can be installed per site. beforePayment runs on every order creation. afterPayment runs only for orders placed through attemptOrderTransition. For backward compatibility, code can still place an order directly with OrderMgr.placeOrder, which skips afterPayment.
Fraud depends on the payment domain for its data: beforePayment reads the payment details on the basket’s instruments, and afterPayment reads the transaction details the payment app recorded. afterPayment still runs when attemptOrderTransition runs on an order paid only with gift cards. The beforePayment hook fires during POST /orders, before the order is created and before any authorization. The afterPayment hook fires inside attemptOrderTransition, after all payment transactions on the order reach AUTHORIZED or CAPTURED. The pre-authorization decision (APPROVED, CHALLENGE, DECLINED, or NOT_REVIEWED to skip) is recorded on the transaction. A failed hook call blocks order creation. See Failure Handling. The post-authorization decision (GUARANTEED, NOT_GUARANTEED, PENDING, or NOT_REVIEWED to skip) decides whether the order is placed, held, or failed.
Register your hooks. In your site cartridge, add a package.json that points to hooks.json. Script paths in hooks.json are relative to that file. Each exported function name must match the last segment of its extension point.
For signatures and the latest class details, see the Script API reference for dw.apps.checkout.hooks.FraudAppHooks.
sfcc.app.fraud.beforePayment(basket) fires during POST /orders, before the order is created and before any authorization. This happens on every order-creation path, including OrderMgr.createOrder. You receive the basket with its payment instruments. Card details are available. Authorization results and the address verification (AVS), card verification code (CVC), and 3D Secure (3DS) results aren’t available.
APPROVED(Status.OK): order creation proceeds.CHALLENGE(Status.OK): order creation proceeds. The payment app reads the decision and decides whether to request 3DS. The platform doesn’t force it.DECLINED(Status.ERROR): the platform rolls back order creation. No order exists, and the shopper stays on the basket.NOT_REVIEWED(Status.OK): you skipped the check. Order creation proceeds.
The fraud app sets the decision and returns the matching Status. The platform enforces the decision. Only a failed hook call blocks creation: Status.ERROR, an exception, a timeout, or a null return (see Failure Handling). The persisted decision alone doesn’t block creation. Script callers of OrderMgr.createOrder get a CreateOrderException.
- A decline leaves no record on the platform. When you return
Status.ERROR, order creation rolls back, and so does everything your hook wrote: theDECLINEDdecision and any basket custom attributes. Keep decline evidence on your side, keyed bybasket.getUUID(). OnAPPROVED,CHALLENGE, andNOT_REVIEWED, the platform records the decision on the order. - Which instruments you see. You see the payment instruments on the basket when
POST /ordersruns, with their card details. If the basket has no instruments yet, no instrument exists to hold a decision. Decide from the basket alone and return the matchingStatus. - The hook runs once per order attempt. A shopper who is declined and retries calls you again with the same basket UUID. Make your vendor submission idempotent on it.
sfcc.app.fraud.afterPayment(order) runs inside attemptOrderTransition, normally once per order; see Can run twice below. It fires when every payment instrument on the order, gift cards included, is AUTHORIZED or CAPTURED and their transaction amounts together cover the order’s gross total.
It supports a synchronous pattern (decide and return) and an asynchronous one (set PENDING, return OK, and resolve through your webhook).
GUARANTEED(Status.OK): the platform places the order.NOT_GUARANTEED(Status.ERROR): the platform reverses the order’s payments (see Payment Commerce Apps), refunds captured gift cards, fails the order, and reopens the basket. A persistedNOT_GUARANTEEDhas this effect even if you returnStatus.OK.PENDING(Status.OK): the order stays inCREATEDuntil your webhook sets a final decision.NOT_REVIEWED(Status.OK): you skipped the check. The platform places the order. The platform also sets this post-auth value when no fraud app is installed or the decision is left unset. The pre-auth decision staysnullwhen no fraud app is installed, and on an instrument added to the order withPOST.
Status.ERROR, an exception, a timeout, or a null return all fail the order. To let an order through when your service is down, see Failure Handling.
Decision semantics.
- One decision per order. Set the same decision on every instrument. Different decisions per instrument aren’t supported: one
NOT_GUARANTEEDrejects the order, and onePENDINGholds it. GUARANTEEDis your contract, not the platform’s. The platform places the order. It doesn’t enforce any chargeback guarantee.GUARANTEEDdoesn’t guarantee placement. Placement can still fail after you return. The order history then recordsplacement_failed. TreatGUARANTEEDas “intended to place” and reconcile against the order’s final status.- Gift cards are already captured. The amounts you see include gift card tender. A
NOT_GUARANTEEDrefunds them. - Can run twice. Concurrent
attemptOrderTransitioncalls, such as a payment webhook and a shopperPATCH, can both reachafterPayment. UseorderNoas your idempotency key.
Each fraud hook has a fixed 1-second execution budget. A hook that exceeds it is treated as an error: beforePayment blocks order creation, and afterPayment fails the order.
- Set your service’s HTTP timeout below the budget, through the
LocalServiceRegistryservice profile. A platform timeout can’t be caught in script, but your own shorter timeout can. - If your vendor can’t reliably answer within the budget post-auth, use the asynchronous pattern.
- Pre-auth has no asynchronous option, so decide whether to fail open when the vendor is slow.
| Outcome | beforePayment | afterPayment |
|---|---|---|
Status.ERROR | Blocks order creation | Fails the order and reverses payment |
| Exception or timeout | Blocks order creation | Fails the order and reverses payment |
null return | Blocks order creation | Fails the order and reverses payment |
Status.OK, no decision set | Proceeds; decision backfilled to NOT_REVIEWED | Proceeds; decision backfilled to NOT_REVIEWED |
The platform fails closed. To fail open when your service is unavailable, set your service timeout below the 1-second budget, catch the error, set NOT_REVIEWED on every instrument, and return Status.OK. Whether to fail open is a merchant policy decision, so expose it as an app setting.
Service errors don’t throw. A LocalServiceRegistry service returns a Result with ok set to false for HTTP errors and timeouts. Check it and throw, or the fail-open path never runs. Set the service profile timeout to about 700 milliseconds: the 1-second budget also covers building the request body and platform overhead.
The afterPayment fail-open variant is the same pattern with POST_AUTH_FRAUD_DECISION_NOT_REVIEWED.
| Decision Set on Transaction | Return |
|---|---|
PRE_AUTH_FRAUD_DECISION_APPROVED | new Status(Status.OK, PaymentTransaction.PRE_AUTH_FRAUD_DECISION_APPROVED) |
PRE_AUTH_FRAUD_DECISION_CHALLENGE | new Status(Status.OK, PaymentTransaction.PRE_AUTH_FRAUD_DECISION_CHALLENGE) |
PRE_AUTH_FRAUD_DECISION_DECLINED | new Status(Status.ERROR, PaymentTransaction.PRE_AUTH_FRAUD_DECISION_DECLINED) |
PRE_AUTH_FRAUD_DECISION_NOT_REVIEWED | new Status(Status.OK, PaymentTransaction.PRE_AUTH_FRAUD_DECISION_NOT_REVIEWED) |
POST_AUTH_FRAUD_DECISION_GUARANTEED | new Status(Status.OK, PaymentTransaction.POST_AUTH_FRAUD_DECISION_GUARANTEED) |
POST_AUTH_FRAUD_DECISION_NOT_GUARANTEED | new Status(Status.ERROR, PaymentTransaction.POST_AUTH_FRAUD_DECISION_NOT_GUARANTEED) |
POST_AUTH_FRAUD_DECISION_PENDING | new Status(Status.OK, PaymentTransaction.POST_AUTH_FRAUD_DECISION_PENDING) |
POST_AUTH_FRAUD_DECISION_NOT_REVIEWED | new Status(Status.OK, PaymentTransaction.POST_AUTH_FRAUD_DECISION_NOT_REVIEWED) |
The platform reads only whether the Status is an error. The code string is for logs and metrics.
Set the decision on every payment instrument, gift cards included. beforePayment receives the basket, and afterPayment receives the order. Iterate getPaymentInstruments() on whichever you receive. Any instrument you leave unset is backfilled to NOT_REVIEWED, which then counts as your decision, and afterPayment isn’t called again for that order. Set the same decision on all of them.
In beforePayment, persist vendor outputs (case ID, risk score, reason codes) as custom attributes on the basket, because no order exists yet. They copy to the order at creation, so afterPayment reads them from order.custom. On a decline, the platform rolls back these writes. For naming and declaration, see Provider-Specific Data on Custom Attributes.
Webhook endpoint. Use a site controller, as the sample does. Custom SCAPI endpoints always require a shopper or Account Manager token, so a vendor can’t call one directly.
- Correlate by order number and token. Send
order.orderNoandorder.orderTokenwith the submission, and look up the order withOrderMgr.getOrder(orderNo, orderToken). - Gate on order status. If the order is no longer
CREATED, acknowledge and stop. This makes duplicate and late deliveries safe. - Set the final decision on every instrument, gift card included. One remaining
PENDINGholds the order.afterPaymentisn’t called again, so nothing else resolves it. - Commit the decision, and then call
OrderMgr.attemptOrderTransition(order)in a separate transaction, for both outcomes. OnGUARANTEEDit places the order. OnNOT_GUARANTEEDit reverses the payments, refunds gift cards, fails the order, and recordsfraud_rejected. Don’t callfailOrderyourself. Keeping remote reversals out of the decision’s transaction means a rollback can’t lose the decision. - Check the result.
isError()on aGUARANTEEDorder means placement failed. Log it and reconcile with your case. Return HTTP 200 once the decision is committed. - Use
orderNoas your idempotency key for the submission and the callback. - Authenticate the endpoint. Verify the vendor’s signature (see the payment guide’s Webhook Handling section).
- A pending decision doesn’t exempt the order from auto-fail. If the merchant sets the Auto-Fail Orders site preference, the job fails orders still in
CREATED, including ones awaiting your decision.
The Script API surface is intentionally provider-neutral. Provider-specific fields, such as case identifiers, risk scores, contributing factors, and decline reasons, go on Commerce App custom attributes on the Basket, Order, and PaymentTransaction objects, not on the platform Script API.
Prefix all custom attribute IDs with your app name (example_ above) to avoid collisions with other apps installed on the same site. Declare the attribute schema in your app’s IMPEX metadata, on both Basket and Order for basket attributes. Basket, instrument, and transaction custom attributes copy to the order at creation.
You access all fraud data through the Script API classes described in this section.
The decision constants are Strings, not enum values. The decision fields are null until set or backfilled.
| Constant | Description |
|---|---|
PRE_AUTH_FRAUD_DECISION_NOT_REVIEWED | No pre-authorization fraud evaluation ran. Order creation proceeds. |
PRE_AUTH_FRAUD_DECISION_APPROVED | Low risk. Order creation proceeds. |
PRE_AUTH_FRAUD_DECISION_CHALLENGE | Medium risk. Order creation proceeds. The payment app reads the decision and decides whether to request 3DS. |
PRE_AUTH_FRAUD_DECISION_DECLINED | High risk. Return it with Status.ERROR to block order creation. |
POST_AUTH_FRAUD_DECISION_NOT_REVIEWED | No post-authorization fraud evaluation ran. The platform places the order. |
POST_AUTH_FRAUD_DECISION_GUARANTEED | Approved with fraud coverage. |
POST_AUTH_FRAUD_DECISION_NOT_GUARANTEED | Rejected post-authorization. |
POST_AUTH_FRAUD_DECISION_PENDING | Held for asynchronous review. The order stays in CREATED until a final decision is set. |
The fraud Commerce App reads instrument and transaction attributes from the payment domain’s Script API classes. See Payment Commerce Apps for the full field list. The fraud domain uses these fields.
SalesforceCardPaymentDetails: read atbeforePaymentfor pre-authorization risk evaluation.token,tokenType,brand,walletType,last4,bin,fundingType,issuingCountry, anddpanLast4are the primary velocity and risk signals.SalesforceCardTransactionDetails: read atafterPaymentfor post-authorization risk evaluation.cvcResult,avsResult,threeDSResult,threeDSVersion,threeDSTransactionId, andelectronicCommerceIndicatorare the primary post-authorization signals.PaymentTransaction: read atafterPaymentfor authorization outcome. Useamounttogether withstatus.- Order-level signals:
Order.customerEmail. To score the shopper’s IP or user agent, forward them from your storefront extension as basket custom attributes (see Handing the Session Identifier to beforePayment).
What you can read at each hook:
| Signal | beforePayment (basket) | afterPayment (order) |
|---|---|---|
| Items, totals, shipping and billing address, promotions | Yes | Yes |
customerEmail, customerNo; registered customer profile via getCustomer() | Yes | Yes |
Card details (SalesforceCardPaymentDetails) | Yes | Yes |
Authorization result, AVS, CVC, 3DS (SalesforceCardTransactionDetails) | No | Cards only |
| Shopper IP or user agent | Only what your storefront extension forwards | Same, copied from the basket |
| Device or session ID | Only what your storefront extension forwards | Same, copied from the basket |
Non-card methods (PayPal, Klarna, and others) carry no AVS, CVC, or 3DS results. Score them on method, amount, and customer signals. token is a payment service provider (PSP) vault token, not a card number, so velocity on it works within one PSP’s vault, not across PSPs. Extra Script API reads, such as customer order history, count against the 1-second budget.
Device data comes from the vendor beacon and goes in custom attributes. For integrators who use an order management system (OMS), order export and import carry <fraud-decisions>.
This section shows how fraud screening fits into checkout when a payment app is also installed.
When a fraud Commerce App is installed alongside a payment Commerce App, the two domains cooperate through the sequence in which their hooks fire.
- The storefront calls
POST /orders. The platform dispatchessfcc.app.fraud.beforePayment(basket)on every order-creation path, includingOrderMgr.createOrder. OnStatus.ERROR, order creation rolls back and the flow stops. Otherwise the platform creates the order inCREATEDstatus with your decision on each instrument. - The order transition runs: the storefront calls the payment app’s order transition endpoint, which calls
attemptOrderTransition. The payment app reads your decision when it authorizes. - If any instrument is still
PENDING, the flow pauses until the payment app callsattemptOrderTransitionagain. - After payment is complete, the platform dispatches
sfcc.app.fraud.afterPayment(order). OnPENDING, the flow pauses until your webhook resolves it. - On
GUARANTEEDorNOT_REVIEWED, the platform places the order. OnNOT_GUARANTEEDor an error, it reverses the payments, refunds captured gift cards, fails the order, and reopens the basket.
Steps 3 to 5 run inside attemptOrderTransition. Each call skips steps already complete, so retries and duplicate webhooks don’t re-run finished work.
Your app decides which device and behavioral signals it collects and how it scores them. Whatever they are, they must reach beforePayment on the basket, because the hook sees only the basket. Your app writes its beacon, mounts it in the storefront, and writes what the hook needs to basket custom attributes before order creation. Storefront Presence shows one way to do this, with a session cookie and an action hook.
- No outcome hook. The platform doesn’t call your app when an order is placed, canceled, refunded, or charged back. To feed outcomes back to your service, run a job that queries orders and calls your feedback API.
- No reversal after placement. After an order is placed, your app can’t change its fraud decision through these hooks. A merchant who needs to stop a placed order uses their normal cancellation process.
CHALLENGEdepends on the payment app. The platform passes it to the payment app and does nothing else. With a payment app that doesn’t request 3DS onCHALLENGE, the order proceeds as if approved. If step-up is essential, decline instead, or check inafterPaymentand returnNOT_GUARANTEEDwhen your pre-auth decision wasCHALLENGEand no 3DS authentication ran.
The fraud domain doesn’t define named storefront UI targets. Fraud Commerce Apps have no shopper-facing surfaces on cart, checkout, or order confirmation. Merchant-facing surfaces, such as case review dashboards and override tooling, live in the fraud vendor’s own portal.
A fraud Commerce App usually ships a client-side beacon: your JavaScript that collects the device and behavioral data your service uses. The platform doesn’t provide one. Delivering it has two parts: mounting the script early in the storefront lifecycle, and getting what beforePayment needs onto the basket before order creation. The rest of this section is an example that uses a session cookie. Use whatever mechanism suits your service.
Fraud Commerce Apps use the same client-side SDK injection pattern payment Commerce Apps use. See Building Your Commerce App: Injecting External SDK Scripts.
Mount the beacon as a context provider so it initializes at the application root and covers every page the shopper touches. Register the provider in your extension’s target-config.json:
The provider loads the vendor script, initializes it with the merchant’s site key, and has the script set a session cookie (for example, _examplefraud_sid) as the shopper browses. No React state is required. The provider exists so the script mounts once and persists across route changes.
In this example, the beacon sets a session cookie, and an action hook on the storefront server reads it and writes it to a basket custom attribute. The beforePayment hook then reads the attribute from the basket.
The storefront action-hook framework exposes two hooks that can carry the write. Register a handler for one, or both, in your extension’s target-config.json. Register afterSubmitContactInfo if any checkout path can skip beforePlace:
sfcc.checkout.fraud.afterSubmitContactInfo: fires after the shopper submits email and phone. Non-blocking.sfcc.checkout.fraud.beforePlace: fires during place order, before thesfcc.checkout.payments.beforePlaceOrderhook and order creation. Blocking. It doesn’t fire for zero-total orders when the storefront allows zero-total checkout (off by default), or when a payment extension places the order itself. In both casesbeforePaymentstill runs at order creation. A payment app that places the order itself is the usual case, so write the identifier inafterSubmitContactInfo, and treatbeforePlaceas a second chance.
Registering both is safe: the second write is idempotent when the identifier hasn’t changed. Give each hook ID its own handler file that re-exports a shared helper. Registering one file for both hook IDs generates a duplicate import, and the build fails.
Example handler that reads the vendor cookie and writes it to the basket:
beforePlace is blocking. Every action hook handler has a 5-second timeout. Throwing ActionHookError(message, hookId, 'placeOrder') returns HTTP 400 and the order isn’t created. Any other error fails the action. A fraud integration should usually fail open, as shown. Define example_fraudSessionId, example_shopperIp, and example_userAgent on Basket and Order in your app’s IMPEX.
- Forward what the hook can’t see.
beforePaymentgets no shopper IP, user agent, or device ID. In Storefront Next, SCAPI calls come from the storefront server, so the IP the platform sees is the server’s. Forward the shopper’s IP and user agent from the storefront request, as shown. - A missing session ID is a degraded signal, not a decline. Score the order without device data. If a merchant requires device data, throw
ActionHookErrorinstead of failing open. - The cookie must be first-party. The action hook runs on the storefront server and sees only cookies sent to the storefront’s own domain. Configure the beacon to set its session cookie on that domain.
- Custom attribute names differ by API. SCAPI request bodies use the
c_prefix (c_example_fraudSessionId). Script code reads the same attribute without it (basket.custom.example_fraudSessionId). - Which IP header to read depends on your hosting. The storefront server sits behind a CDN or proxy, so the shopper’s IP comes from a forwarding header, not the connection.
The beforePayment hook on the Commerce App side reads the same attribute from the basket:
Name and declare the attribute as described in Provider-Specific Data on Custom Attributes, on both Basket and Order.
Install your app on a sandbox with the prerequisites met. Cover at least these scenarios:
- Pre-auth outcomes: approve, challenge, and decline.
- Vendor down: fail closed, and fail open if you offer it.
- Async outcomes: approval and rejection.
- Duplicate callback: a repeated callback, and a callback that arrives before
afterPaymentreturns. - Order auto-failed: the order fails while a decision is pending.
Decisions appear on the order’s payment transactions and in the order export.
Testing without a payment app. beforePayment runs on every order creation, so you can test it on any sandbox checkout. afterPayment runs only inside attemptOrderTransition, which a payment app calls. Without a payment app installed, call it from a test script: set each instrument’s transaction to STATUS_AUTHORIZED with amounts that cover the order total, and then call OrderMgr.attemptOrderTransition(order).
See Testing and Validation for installation, uninstallation, and storefront checks that apply to every Commerce App.