Payment, Gift Cards, and 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.
Note
Breaking changes are possible until GA. While these domains are in beta, hook signatures, data model fields, and manifest fields can change without the deprecation window that applies to GA APIs. Changes are called out in the release notes.
Warning
Payments Orchestration is the platform-controlled sequence that coordinates payment, fraud, and gift card Commerce Apps when a shopper places an order. Commerce Apps are packaged integrations that merchants install on their B2C Commerce sites. The platform owns the order of operations and the rollback on failure. Your Commerce App handles your provider’s part of checkout, and the platform calls it at the right point.
This page explains how the three domains fit together and what your app is responsible for. For hook contracts, data fields, and code samples, see the domain guides.
Before Commerce Apps, each payment, fraud, and gift card vendor defined its own APIs and fields and chose its own place in the checkout sequence. A payment cartridge couldn’t read a fraud cartridge’s results, and a gift card cartridge couldn’t read either. System integrators (SIs) stitched the three together as custom code for every merchant, including split-tender sequencing (paying for one order with more than one payment method) and the rollback when one step failed.
The diagram contrasts the two models. Before, each merchant site needed custom code connecting every pair of vendors. With Payments Orchestration, each app connects only to the platform.
1flowchart LR
2 subgraph Before["Before: custom integration per merchant"]
3 direction TB
4 P1[Payment cartridge] <-- "SI custom code" --> F1[Fraud cartridge]
5 P1 <-- "SI custom code" --> G1[Gift card cartridge]
6 F1 <-- "SI custom code" --> G1
7 end
8 subgraph After["With Payments Orchestration"]
9 direction TB
10 PLPlatform orchestration and standard data model
11 P2[Payment app] <--> PL
12 F2[Fraud app] <--> PL
13 G2[Gift card app] <--> PL
14 end
15 Before ~~~ AfterPayments Orchestration replaces that per-merchant work with a shared model:
You build an app for one domain, the one that matches your service. The apps in the other domains are built by other vendors, and the platform coordinates them with yours. Fraud and gift card apps are optional. In Beta, a site runs one app per domain.
Server-side hooks are scripts in your Commerce App Package (CAP) that the platform calls at defined points. Storefront components are React extensions that render in the Storefront Next checkout. A webhook receiver is an endpoint in your app that your provider calls when a result arrives later. For how to package them, see Building Your Commerce App.
| Domain | What your app does | What you ship |
|---|---|---|
| Payment | Claims the payment methods it handles, such as credit cards, wallets, or bank redirects, and authorizes, captures, refunds, and reverses them with your payment service provider (PSP). | Server-side hooks, storefront components that collect the payment and drive order placement, an order transition endpoint, and a webhook receiver for asynchronous results. |
| Fraud | Scores the order at two points, before payment and after payment, and returns a decision. | Server-side hooks, a client-side beacon that collects device and behavioral data, and a webhook receiver if your service decides asynchronously. |
| Gift card | Checks balances, captures gift card funds, and refunds them if the order fails. | Server-side hooks and storefront components for applying a gift card. |
Each app builds two things: the calls to its own provider, and the standard data and responses the other domains depend on. The hooks define when your app runs. The shared data model defines what your app leaves behind for the next app to read. Because every app in a domain writes the same fields and honors the same responses, a payment app works with any fraud or gift card app without knowing which one is installed. The same data stays on the order for merchants and their order systems to use.
1flowchart LR
2 PSP["Payment app"] -- "writes card details and authorization results" --> DM[("Standard data model")]
3 DM -- "reads risk signals" --> FR["Fraud app"]
4 FR -- "writes fraud decision" --> DM
5 DM -- "reads decision, can request 3DS on challenge" --> PSP
6 GC["Gift card app"] -- "records its capture" --> DMA payment app connects checkout to a PSP and records what happened at each stage in standard fields.
For more information, see Payment Commerce Apps.
Fraud and gift card apps only respond when the platform calls them. The payment app’s storefront extension also drives checkout. When the shopper selects Place Order, it creates the order and then calls the app’s order transition endpoint, which asks the platform to complete it. It does this for every order, including orders paid entirely by gift card. Your payment app’s webhook makes the same call when a delayed result arrives.
A fraud app reads the standard payment data, sends it to its risk service, and returns one of a fixed set of decisions that the platform and the payment app act on.
The fraud app never calls the PSP. It influences payment only through its decision, so its decisions work the same way with any payment app. For more information, see Fraud Commerce Apps.
A gift card app is one payment instrument among several on an order, and it follows the same standard interfaces as the other domains.
For more information, see Gift Card Commerce Apps.
Order placement runs in two phases, with automatic rollback if a step fails.
1flowchart TD
2 S0([Shopper enters payment and applies gift card]) --> T1["Payment app: tokenize card and add it to the basket"]
3 T1 --> S([Shopper places order])
4 S --> A1
5
6 subgraph P1["Phase 1: Create order"]
7 A1[Platform: reserve inventory] --> A2{"Fraud app (optional): before payment"}
8 A2 -- "approve or challenge" --> A3[Platform: create order and commit tax]
9 end
10
11 A2 -- decline --> X([Checkout ends, no order created])
12 A3 --> B0([Payment app's extension requests order completion])
13
14 subgraph P2["Phase 2: Complete order"]
15 B0 --> B1["Gift card app (if applied): capture"]
16 B1 --> B2{"Payment app: authorize"}
17 B2 -- succeeded --> B3{"Fraud app (optional): after payment"}
18 B2 -. pending .-> W1([Order waits for payment webhook])
19 W1 -. result .-> B2
20 B3 -. pending .-> W2([Order waits for fraud app's decision])
21 W2 -. decision .-> B3
22 end
23
24 B3 -- approve --> OK([Order placed])
25 B1 -- fails --> R
26 B2 -- fails --> R
27 B3 -- reject --> R
28 R[["Platform rollback: fail order, release inventory, reverse payments, refund gift card, cancel tax"]]The next diagram shows the same flow by actor: what the shopper, the storefront, the platform, and each app does, in order.
1sequenceDiagram
2 actor Shopper
3 participant SF as Storefront
4 participant PL as Platform
5 participant GC as Gift card app
6 participant PA as Payment app
7 participant FR as Fraud app
8
9 Shopper->>SF: Enters card and applies gift card
10 Note over SF: Payment app's component tokenizes the card with the PSP
11 SF->>PL: Add payment and gift card to the basket
12 Note over PL,PA: Payment app records card details for the fraud app to read
13 Shopper->>SF: Places order
14 SF->>PL: Create the order
15 PL->>FR: Score the basket and card details before payment
16 FR-->>PL: Approve, challenge, or decline
17 alt Decline
18 PL-->>SF: Checkout ends, no order created
19 else Approve or challenge
20 PL-->>SF: Order created
21 end
22 SF->>PL: Payment app's extension requests order completion
23 PL->>GC: Capture the gift card amount
24 GC-->>PL: Captured or failed
25 PL->>PA: Authorize the remaining amount
26 Note over Shopper,PA: On a challenge, the payment app can request 3DS, and the shopper verifies before authorization completes
27 PA-->>PL: Succeeded, failed, or pending
28 PL->>FR: Decide after payment
29 FR-->>PL: Approve, reject, or pending
30 alt Every step succeeded
31 PL-->>SF: Order placed
32 SF-->>Shopper: Confirmation
33 else A step failed or fraud rejected
34 PL->>PA: Reverse the payment
35 PL->>GC: Refund the gift card
36 PL-->>SF: Order failed, basket reopened
37 SF-->>Shopper: Retry
38 endPhase 1: Create order. The shopper submits checkout with the payment method and any gift card already on the basket, and the platform converts the basket to an order. If a fraud app is installed, it scores the basket first. A decline at this point stops checkout before an order exists, so there’s nothing to roll back.
Phase 2: Complete order. This phase starts when the payment app’s storefront extension calls the app’s order transition endpoint, and a payment or fraud webhook can resume it later. The platform captures gift cards, asks the payment app to authorize the rest, and then asks the fraud app for its after-payment decision. When every step succeeds, the order is placed.
Asynchronous steps. When a step finishes outside the shopper’s request, such as a redirect or a fraud decision that your service makes later, the order waits until the owning app reports the result, either when the shopper returns or through a webhook. See Payment Flow Patterns.
Rollback. If any step in Phase 2 fails, the platform fails the order and unwinds it: it releases inventory, asks each payment app to reverse its payment, asks the gift card app to refund, and cancels committed tax. When the failure happens while the shopper is checking out, the basket reopens so they can try again. Your app implements its own reversal or refund; the platform decides when to call it.
The platform is firm about the order of steps and how the apps hand off to each other:
Everything inside your app’s part of the flow is yours to design around your provider. That includes when your storefront collects payment data, whether you authorize synchronously or asynchronously, and which hooks your app implements. Some payment apps never use certain hooks; others depend on them. Beyond claiming its payment methods and reversing its payments on rollback, which every payment app does, there’s no single required set of hooks, so choose based on how your PSP works, using the domain guides.
A payment flow pattern is the way a payment method reaches a result with its PSP. PSPs and payment methods differ: some return an authorization in a single call, some send the shopper to a hosted page, and some confirm only later. Your app uses whatever pattern your PSP and each payment method require. The orchestration is the same for all of them, because the platform needs only one thing from your app at each step: the payment either succeeded, failed, or is still pending.
| Pattern | How it works | Typical methods |
|---|---|---|
| Synchronous | Your app authorizes with the PSP during order placement, and the order is placed in the same request. | Cards without a challenge, many wallets |
| Redirect or challenge | Your app starts the payment and marks it pending. The shopper completes a step on the provider’s page or in a 3DS challenge, then returns to the storefront, and your app finalizes the payment. | Bank redirects, hosted payment pages, cards with a 3DS challenge |
| Asynchronous | Your app submits the payment, and the PSP reports the result later through a webhook. The order waits until your app reports success or failure. | PSPs that confirm authorizations by notification, including for cards |
These patterns are common shapes, not a fixed menu. Your PSP might combine them or work differently, and one payment app often uses more than one, for example synchronous for most card payments and redirect when a card needs a 3DS challenge. When your app reports the result, the platform continues with the after-payment fraud check and places the order, or rolls the order back if the payment failed. Fraud and gift card apps work the same way whichever pattern you use.
For the implementation of each pattern, see Flow Patterns in Payment Commerce Apps.
This example follows one order through the three domains. The domain guides cover how to implement each step.
A merchant installs a payment app that handles credit cards, a gift card app, and a fraud app. The shopper applies a gift card for part of the total and pays the rest by credit card. None of the three apps knows which of the others is installed.
If the fraud app had rejected the order instead, the platform would fail it, ask the payment app to void the authorization and the gift card app to refund, and reopen the shopper’s basket. Either way, the fraud app returned only a decision, the payment app acted on it, and each app undid only its own work.
Each domain guide covers prerequisites, hook contracts, the data your app reads and writes, and code samples:
To get started, read the guide for your domain, then see Building Your Commerce App to package and install your app.
j