Add cartId to payment handling and improve documentation

This commit integrates `cartId` into payment-related processes, including data handling, API responses, and Stripe return URLs. Additionally, updates were made to the documentation and instructions for configurability, integration of payment components, and support for Apple Pay/Google Pay requirements.

enabler/README.md

@@ -3,6 +3,64 @@ This module provides an application based on [commercetools Connect](https://doc
 
 PSPs provide libraries that can be used on client side to load on browser or other user agent which securely load DOM elements for payment methods and/or payment fields inputs. These libraries take control on saving PAN data of customer and reduce PCI scopes of the seller implementation. Now, with the usage of `enabler`, it allows the control to checkout product on when and how to load the `enabler` as connector UI based on business configuration. In cases connector is used directly and not through Checkout product, this connector UI can be loaded directly on frontend than the libraries provided by PSPs.
 
+## Creating Components for Payment Elements or Express Checkout
+
+To integrate the Stripe Composable connector with commercetools and utilize the Stripe payment elements or express checkout, follow these steps:
+
+### 1. **Load the Stripe Enabler**
+Use the provided enabler URL from the Stripe Composable Connector information page.
+```javascript
+const Enabler = await import(process.env.REACT_APP_ENABLER_BUILD_URL);
+```
+### 2. **Initialize the Payment Component**
+Create a new Enabler instance and specify the `paymentElementType` parameter to configure the component type, either **Payment Element:'payment'** or **Express Checkout:'expressCheckout**.
+```javascript
+new Enabler({
+    processorUrl: COMMERCETOOLS_PROCESSOR_URL, // Backend processor URL
+    sessionId: SESSION_ID,                    // Commercetools session ID
+    currency: "US",                           // Desired currency for the payment
+    onComplete: ({ isSuccess, paymentReference, paymentIntent }) => {
+        onComplete(paymentIntent);            // Callback for completion
+    },
+    onError: (err) => {
+        onError(err);                          // Callback for error handling
+    },
+    paymentElementType: type,                 // Component type:(payment|expressCheckout) Payment Element or Express Checkout
+});
+```
+
+Replace the placeholder variables (`COMMERCETOOLS_PROCESSOR_URL`, `SESSION_ID`, `onComplete`, `onError`, and `type`) with appropriate values based on your application configuration.
+
+## Considerations for Apple Pay and Google Pay
+
+### Apple Pay Requirements
+To enable Apple Pay, you must ensure the following conditions are satisfied:
+
+1. The website must include a `https://www.website.com/.well-known/apple-developer-merchantid-domain-association` call that redirects to:
+   ```text
+   {COMMERCETOOLS_PROCESSOR_URL}/applePayConfig
+   ```
+   This endpoint retrieves the required merchant ID domain association file. For more details, refer to Stripe’s official [Apple Pay domain association documentation](https://support.stripe.com/questions/enable-apple-pay-on-your-stripe-account).
+
+2. The environment and devices must meet Apple Pay testing requirements:
+    - You need an **iOS device** running iOS 11.3 or later, or a **Mac** running macOS 11.3 or later with Safari.
+    - The browser must be configured with an active card in the Apple Wallet in sandbox mode.
+    - A valid Stripe account must be linked with Apple Pay and properly configured.
+    - All webpages hosting an Apple Pay button are HTTPS.
+
+3. Make sure your Stripe account has Apple Pay enabled (this is configured via your Stripe dashboard).
+
+### Google Pay Requirements
+To enable Google Pay, you must ensure the following conditions are satisfied:
+
+1. The device and browser requirements for testing Google Pay are met:
+    - Use a **Chrome browser** on any device (mobile or desktop) supporting Google Pay.
+    - Add a payment method (card) to your Google Pay account and ensure your testing environment is set up for sandbox mode.
+
+2. Additional configuration for your Stripe account:
+    - Ensure **Google Pay** is enabled via your Stripe dashboard.
+    - Stripe automatically manages domain validation for Google Pay—manual setup is not required.
+
 
 ## Getting Started
 Please run following npm commands under `enabler` folder for development work in local environment.

enabler/src/dropin/dropin-embedded.ts

@@ -75,7 +75,8 @@ export class DropinComponents implements DropinComponent {
         errors : processorError,
         sClientSecret : client_secret,
         paymentReference: paymentReference,
-        merchantReturnUrl: merchantReturnUrl } = await fetch(`${this.baseOptions.processorUrl}/payments`,{
+        merchantReturnUrl: merchantReturnUrl,
+        cartId: cartId } = await fetch(`${this.baseOptions.processorUrl}/payments`,{
         method : "GET",
         headers : {
           "Content-Type": "application/json",
@@ -93,7 +94,7 @@ export class DropinComponents implements DropinComponent {
         elements: this.baseOptions.elements,
         clientSecret: client_secret,
         confirmParams : {
-          return_url : merchantReturnUrl
+          return_url : merchantReturnUrl+`?cartId=${cartId}&paymentReference=${paymentReference}`
         },
         redirect : "if_required"
       });

processor/README.md

@@ -163,6 +163,8 @@ N/A
 #### Response Parameters
 - **sClientSecret**: The client secret is used to complete the payment from your frontend. 
 - **paymentReference**: The payment reference of the current process.
+- **merchantReturnUrl**: The URL used as the `return_url` parameter in Stripe's [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) process. After the payment confirmation, Stripe appends the `paymentReference` and `cartId` as query parameters to this URL. For Buy Now, Pay Later (BNPL) payment methods, this URL can be used to reinitialize the commercetools Checkout SDK. More information on implementing the return URL for BNPL payment methods can be found in the [commercetools Checkout SDK documentation](https://docs.commercetools.com/checkout/sdk#return-url).
+- **cartId**: The cartId of the current proccess.
 
 ### Confirm the Payment Intent to commercetools
 This endpoint update the initial payment transaction in commercetools. It is called after the Stripe confirm the payment submit was successful.
@@ -183,13 +185,19 @@ The conversion of the webhook event to a transaction is converted in hte `/src/s
 
 The following webhooks currently supported and transformed to different payment transactions in commercetools are:
 - **payment_intent.canceled**: Modified the payment transaction Authorization to Failure and create a payment transaction CancelAuthorization: Success 
-- **payment_intent.succeeded**: Creates a payment transaction Charge: Success. 
+- **payment_intent.succeeded**: Creates a payment transaction Charge: Success. Create the order from the cart that has the payment referenced. 
 - **payment_intent.requires_action**: Logs the information in the connector app inside the Processor logs.
 - **payment_intent.payment_failed**: Modify the payment transaction Authorization to Failure.
 - **charge.refunded**: Create a payment transaction Refund to Success, and a Chargeback to Success.
 - **charge.succeeded**: If the charge is not captured, create the payment transaction to Authorization:Success.
 - **charge.captured**: Logs the information in the connector app inside the Processor logs.
 
+### Order Creation
+
+The order is created during the processing of the `payment_intent.succeeded` webhook. Before creating the order, the cart must include shipment information.
+
+In the current implementation, the sample application retrieves shipment and address details from the `last_charge` attribute included in the Stripe event payload. This setup serves as an example and can be adapted or reused based on your specific requirements.
+
 #### Endpoint
 `POST /stripe/webhooks`
 
@@ -199,6 +207,18 @@ The [Event object](https://docs.stripe.com/api/events) sent to your webhook endp
 #### Response Parameters
 The endpoint returns a 200 response to indicate the successful processing of the webhook event.
 
+### Apple pay well-know file
+This endpoint return the string of the .well-know call domain [file from Stripe](https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association).
+
+#### Endpoint
+`GET /applePayConfig`
+
+#### Query Parameters
+N/A
+
+#### Response Parameters
+- **string**: The string value of the well-know domain file.
+
 ### Get supported payment components
 Private endpoint protected by JSON Web Token that exposes the payment methods supported by the connector so that checkout application can retrieve the available payment components.
 

processor/src/dtos/stripe-payment.dto.ts

@@ -33,6 +33,7 @@ export const PaymentResponseSchema = Type.Object({
   sClientSecret: Type.String(),
   paymentReference: Type.String(),
   merchantReturnUrl: Type.String(),
+  cartId: Type.String(),
 });
 
 export const ConfigElementResponseSchema = Type.Object({

processor/src/services/stripe-payment.service.ts

@@ -273,6 +273,7 @@ export class StripePaymentService extends AbstractPaymentService {
       sClientSecret: paymentIntent.client_secret ?? '',
       paymentReference: ctPayment.id,
       merchantReturnUrl: merchantReturnUrl,
+      cartId: ctCart.id,
     };
   }
 

processor/test/utils/mock-routes-data.ts

@@ -543,6 +543,7 @@ export const mockRoute__payments_succeed: PaymentResponseSchemaDTO = {
   sClientSecret: 'mock_paymentReference',
   paymentReference: 'mock_paymentReference',
   merchantReturnUrl: 'mock_merchantReturnUrl',
+  cartId: 'mockCartId',
 };
 
 export const mockRoute__paymentsComponents_succeed: SupportedPaymentComponentsSchemaDTO = {