Create a Custom Payment Component

Use the same credit card payment methods and order processing across B2B/D2C stores by creating a custom payment component for a B2C (LWR) checkout page.

When you create a custom payment component, the checkout stages are of particular importance. Aside from the validation-related stage actions such as PostAuth, the following are specific to payment: BEFORE_PAYMENT and PAYMENT. BEFORE_PAYMENT is an important hook because it is where the component initiates a payment session with the gateway. At this stage the GrandTotalAmount of the WebCart will account for all adjustments including tax, shipping and promotions. For more on checkout stages in your component see UseCheckoutComponent Interface

To create and deploy the payment component, first Commerce SFDX Environment Setup and optionally review Build Custom Components.

  1. In the Visual Studio Code editor, enter SFDX.

  2. Select SFDX: Create an Apex Class or navigate to the project containing an existing payment adapter class.

    The Apex class

    implements the (synchronous or asynchronous) adapter that connects the payment platform in Salesforce and an external payment gateway. You can create your own adapter using the code samples and instructions in Payment Gateway Adapters. For example implementations associated with specific payment platforms, see Sample Payment Gateway Implementation for CommercePayments.

  3. Add a PostAuth request handler to the Apex class.

    The PostAuth request type ensures that the provided payment token is valid. The token, the amount, and currency code are provided to the adapter through the PostAuth input. This validates completion of the client side transaction. The API to do this is the Commerce Webstore Checkout Payment API. For a client side implementation the RequestType that validates and records a client side payment transaction is PostAuth. For convenience, we have provided a client-side API, commerce/checkoutApi.postAuthorizePayment (for more see Storefront APIs). Invoking this API will in turn invoke the processRequest method on your payment gateway adapter with the RequestType being PostAuth.

    For details of the Apex implementation for PostAuth see PostAuthorizationRequest Class (input) and PostAuthorizationResponse Class (output)

  4. Create named credentials for the adapter class.

    1. In Visual Studio Code Explorer, under force-app/main/default, create a subdirectory called namedCredentials.

    2. In namedCredentials, create a file named _payment_.namedCredential.

    3. In the public repo of a reference payment package, such as the Stripe integration payments package, go to the /namedCredentials folder and copy the contents of the Stripe.namedCredential file to your _payment_.namedCredential.

  5. Create the payment Lightning web component.

    1. Create an SFDX project.

    2. Authorize an org for the LWC deployment.

    3. Create the custom UI component.

  6. Deploy the payment component and all the code and metadata required for the integration (LWC, Apex, named credentials, trusted sites) to your org.

    Note that payment provider UI component may require using an externally hosted javascript. To do this you will need to add a Content Security Policy (CSP) for the site as well as add it as a trusted script to the site within Experience Builder. The CSP can be managed via metadata as described in CspTrustedSite. The trusted script however is a manual step and must be done on a site by site basis as described in step 8.

  7. Create a payment gateway, as described in Payment Gateway Adapters.

  8. In Experience Builder, register the third-party trusted sites for scripts that are required to run the LWC, as described in Where to Allowlist Third-Party Hosts for Experience Builder Sites.

  9. If you're implementing an asynchronous payment processing flow, designate the authorization as async in the payment gateway apex adapter by setting the async status to true: When the transaction results are posted, typically via a webhook notification, update the status of the PaymentAuthorization. If the status is updated to Processed then downstream order management operations can be resumed.

See