Payment

The payment stage converts a customer's purchase intent into a financial transaction. In Composable Commerce, the Payment object stores information about the PSP, the payment method, related transactions, and the current state of the Payment.

Your backend for frontend (BFF) is responsible for the following:

1. Create a Payment object in Composable Commerce that represents the planned payment.
2. Integrate with a PSP to authorize and capture funds.
3. Update the Payment object in Composable Commerce with transaction statuses from the PSP.
4. Handle payment retries and failures gracefully.

Before integrating a payment flow, you must understand the Payment object, which tracks payment information in Composable Commerce.

The Payment object

It does not process payments itself; a PSP handles the actual authorization, capture, and settlement of funds.

Handle multiple payment attempts

This approach ensures that regardless of which payment method eventually succeeds, all associated data remains intact and available for troubleshooting or reconciliation.

Use middleware for PSP integrations

The recommended solution to implement a payment integration is using middleware (your BFF) to limit complexity and third-party constraints. A standard PSP integration comprises two components: synchronous and asynchronous. A synchronous component starts the payment process by exchanging checkout data between the store and payment provider, and an asynchronous component receives payment-related notifications from the PSP.

Maintain Cart integrity during payment

Gracefully handle cases where the cart changes between payment initiation and Order creation to increase successful order rates. The Cart can change when:

• A customer has multiple browser tabs open. They modify the cart in one tab while the payment process is ongoing in another tab.
• A price changes or a discount expires during the time the customer is completing the payment process.

Detect cart changes

Depending on your business requirements, you might want to:

• Proceed to create the Order if the totalPrice of the new Cart is equal to, or less than, the authorized amount.
• Cancel authorization (or refund, in case of capture), notify the customer that the Cart has changed, and ask them to review and confirm before proceeding (re-initiate payment).

Implementation steps

A typical payment flow involves creating a Payment object, linking it to the Cart, and then using a PSP to handle the financial transaction.

Step 1: Create a Payment object

During checkout, a customer may try different payment methods or start multiple payments in separate tabs. Create a dedicated Payment resource to track each initiated payment process, even if aborted and restarted.

async function createPayment(
  amount: number, // Amount in cents, for example, 1000 ($10)
  currency: string, // for example, USD
  paymentInterface: string, // for example, 'STRIPE', 'ADYEN'
  method: string, // for example, CREDIT_CARD
  pspPaymentRef?: string, // PSP charge/intent ID, if known now
  key?: string // your idempotency key for Payment
) {
  const paymentDraft: PaymentDraft = {
    key, // optional but recommended
    interfaceId: pspPaymentRef, // can also be set later via update
    amountPlanned: { centAmount: amount, currencyCode: currency },
    paymentMethodInfo: { method, paymentInterface }, // Optionally add a name, for example, name: { en: "Credit Card" }
  };
  return apiRoot
    .payments()
    .post({
      body: paymentDraft,
    })
    .execute();
}

Step 2: Link the Payment to the Cart

Link each Payment to the Cart without updating or removing previous Payments; each may represent a distinct transaction. This approach ensures you can track all payment attempts, maintain idempotency for retries, and reliably determine which Payment succeeded when creating the Order.

async function linkPaymentToCart(
  cartId: string,
  version: number,
  paymentId: string
) {
  return apiRoot
    .carts()
    .withId({ ID: cartId })
    .post({
      body: {
        version,
        actions: [
          {
            action: "addPayment",
            payment: { id: paymentId, typeId: "payment" },
          },
        ],
      },
    })
    .execute();
}

PSP integration models

Conceptually, there are two primary models for integrating with a Payment Service Provider (PSP). Both methods start with a call to your BFF or backend to create a payment session by securely calling the PSP's API.

• Client-side tokenization: This model is typically used for card payments. It uses the PSP's UI components on the frontend to collect and tokenize the customer's payment information before sending them to your BFF or backend to authorize or capture payments. Only the tokens are stored; raw card details from your backend are never stored or transmitted.
• Server-side redirect: This model is typically used for alternative payment methods (APMs), such as bank transfers or regional wallets. It uses a redirect URL provided by the PSP to present the payment flow to the customer.

While these patterns are still useful for understanding the core flows, modern payment platforms like Stripe often merge both models into a unified integration. With Stripe, for example, a single session (either via Checkout or PaymentIntent) can support multiple payment methods, dynamically presenting the right ones to the customer based on their location, currency, and device. This means you don't need separate flows for each payment type; Stripe's API and UI handle most of the complexity for you.

Conceptual payment integration models

Typical unified PSP flow

1. Initiate payment session with PSP: At checkout, the backend for frontend (BFF) initiates a payment session or intent with the PSP, often passing the Cart total, customer details, and redirect URLs (success and cancel redirects). The PSP responds with an available list of supported payment methods.
2. Present payment methods to the shopper: The frontend displays the available payment options (like credit card, PayPal, Klarna) from the PSP, often usng its embedded components to ensure PCI compliance and handle 3D Secure authentication.
3. Customer selects payment method:
   • For direct methods (like credit cards), the customer enters card details through the PSP's UI component, which handles tokenization and security checks.
   • For redirect methods (like PayPal), the backend receives a redirect link from the PSP to send the customer to the provider's authentication/approval page.
4. Initiate payment attempt: The BFF creates a Payment object in Composable Commerce and links it to the Cart immediately before sending any authorization request to the PSP. The Payment Object includes the planned amount, method details, and PSP metadata (for example, session or intent ID) and a Transaction of type Authorization with state Pending to record the authorization attempt.
5. Authorize with the PSP: The BFF requests authorization from the PSP (either with a card token or by initiating a redirect flow for an alternative method):
   • If "OK" (approved), the PSP returns the interfaceId or confirmation. Immediatly update the Payment object and add a Transaction of type Authorization with state Success.
   • If futher challenge/redirect is needed (for example, 3D Secure, PayPal), redirect the customer and wait for completion. The Payment object remains Pending until you receive a response.
6. Update Payment Transaction status: The backend uses data from the PSP (direct response or webhook) to update the Payment object in Composable Commerce with the actual transaction result - ensuring payments are only marked successful once verified.
7. Create the Order: Once payment is confirmed by the PSP (ideally via webhook or final redirect), the backend creates the Order from the Cart with its linked Payments.

Let's look at a production-like unified PSP flow in a sequence diagram:

Unified PSP integrations are preferred because:

• They cover all major payment types in one integration.
• They delegate security and PCI compliance to the PSP.
• They enable payment orchestration: handling retries, status updates, and reconciliation in one consistent way.
• They ensure Order creation is only triggered once confirmed payment is received, protecting against fraudulent manipulation or redirect/success URLs.

Handle payment failures and retries

Payment failures can occur for various reasons, such as insufficient funds, network issues, or user cancellations. To handle these scenarios effectively:

• Frontend: Show clear error and offer alternative methods.
• Backend:
  • Create a new Payment on every payment attempt.
  • Update Payment object with failure transaction.
  • Maintain idempotency: if a retry occurs, ensure you do not double-authorize.
  • Avoid dangling authorizations by canceling or voiding if payment will not be captured.

Key takeaways

• Composable Commerce tracks payment data but does not process financial transactions.
• The PSP handles sensitive data. Your backend should only handle tokens or transaction IDs.
• Always link the Payment to the Cart before creating an Order.
• Use webhooks for asynchronous status updates from the PSP.
• Design payment flows for idempotency to prevent duplicate charges.
• Detect Cart changes by comparing versions before and after payment authorization.
• Create a new Payment object for each payment attempt to maintain a clear audit trail.

The next step in the checkout sequence is Order placement and confirmation. You will convert the Cart and the linked Payment into an Order, handle edge cases, and trigger post-purchase workflows.

Test your knowledge