Integrate with EDS storefront

Integrate your Out-of-Process Payment Extensions (OOPE) payment method with the Edge Delivery Service (EDS) Storefront.

Prerequisites

The following prerequisites are required to integrate your OOPE payment method with the EDS Storefront:

Integrate EDS Storefront with Adobe Commerce.
Configure Storefront in EDS with the checkout dropin component.
- The checkout dropin component allows users to enter shipping and payment information, review their order details, and confirm their purchase.
- To access the latest EDS Storefront boilerplate with dropin components, see EDS Adobe Commerce Boilerplate.

Integrate with checkout drop-in components

The payment gateway typically requires a session to start the payment process, and it provides a dropin component UI to draw on the payment form using that session ID.

The following example integrates the OOPE method with the checkout dropin component by creating a session from the payment gateway action in App Builder and setting up the payment form based on the session response.

Integration methods can vary depending on your use case. Refer to the checkout dropin component documentation and your payment gateway documentation for further information.

Import your payment gateway SDK to your project.

<script src="https://cdn.your-paymentgateway.com/sdk.js"></script>
Copied to your clipboard
<script src="https://cdn.your-paymentgateway.com/sdk.js"></script>

Create a session from the OOPE payment gateway and get the session data.

async function createSession(endpoint, request) {
  return (
    await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(request),
    })
  ).json();
}
Copied to your clipboard
async function createSession(endpoint, request) {
  return (
    await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(request),
    })
  ).json();
}

Start payment in the checkout dropin component. The following example starts the payment instead of placing the order when the user selects the OOPE payment method.

export default async function decorate(block) {
    ...
  CheckoutProvider.render(PlaceOrder, {
      handlePlaceOrder: async ({ cartId, code }) => {
          try {
              if (code === 'oope_adyen') {
                  // Start payment when OOPE payment method is selected
                  await startPayment(cartData, environment, sessionUrl, clientKey, returnUrl);
              } else {
                  await orderApi.placeOrder(cartId);
              }
          } catch (error) {
              console.error(error);
              throw error;
          }
      },
    })($placeOrder),
    ...
]);

async function startPayment(cartData, environment, sessionUrl, clientKey, returnUrl) {
  const createSessionRequest = {
    amount: {
      value: cartData.prices.grandTotal.value,
      currency: cartData.prices.grandTotal.currency,
    },
    reference: cartData.id,
    returnUrl: returnUrl,
    countryCode: cartData.billingAddress.country.code,
  };

  // Create a session from the OOPE payment gateway, a function from the previous step
  const sessionData = await createSession(
    createSessionEndpoint,
    createSessionRequest,
  );

  const configuration = {
    session: {
      id: sessionData.message.id,
      sessionData: sessionData.message.sessionData,
    },
    environment: environment,
    amount: {
      value: sessionData.message.amount.value,
      currency: sessionData.message.amount.currency,
    },
    locale: sessionData.message.shopperLocale,
    countryCode: sessionData.message.countryCode,
    clientKey: clientKey,
    analytics: {
      enabled: true,
    },
    onPaymentCompleted: async () => {
        // Place an order once payment is completed
        await checkoutApi.placeOrder();
    },
    ...
  };

  // Draw your payment gateway dropin component UI on the page
  await mountPaymentDropin('#id-to-mount', configuration);
}
Copied to your clipboard
export default async function decorate(block) {
    ...
  CheckoutProvider.render(PlaceOrder, {
      handlePlaceOrder: async ({ cartId, code }) => {
          try {
              if (code === 'oope_adyen') {
                  // Start payment when OOPE payment method is selected
                  await startPayment(cartData, environment, sessionUrl, clientKey, returnUrl);
              } else {
                  await orderApi.placeOrder(cartId);
              }
          } catch (error) {
              console.error(error);
              throw error;
          }
      },
    })($placeOrder),
    ...
]);

async function startPayment(cartData, environment, sessionUrl, clientKey, returnUrl) {
  const createSessionRequest = {
    amount: {
      value: cartData.prices.grandTotal.value,
      currency: cartData.prices.grandTotal.currency,
    },
    reference: cartData.id,
    returnUrl: returnUrl,
    countryCode: cartData.billingAddress.country.code,
  };

  // Create a session from the OOPE payment gateway, a function from the previous step
  const sessionData = await createSession(
    createSessionEndpoint,
    createSessionRequest,
  );

  const configuration = {
    session: {
      id: sessionData.message.id,
      sessionData: sessionData.message.sessionData,
    },
    environment: environment,
    amount: {
      value: sessionData.message.amount.value,
      currency: sessionData.message.amount.currency,
    },
    locale: sessionData.message.shopperLocale,
    countryCode: sessionData.message.countryCode,
    clientKey: clientKey,
    analytics: {
      enabled: true,
    },
    onPaymentCompleted: async () => {
        // Place an order once payment is completed
        await checkoutApi.placeOrder();
    },
    ...
  };

  // Draw your payment gateway dropin component UI on the page
  await mountPaymentDropin('#id-to-mount', configuration);
}

Mount the payment gateway dropin component UI on the page using the session created through your OOPE gateway. The following example using the Adyen library draws the dropin componentUI on the page.

async function mountPaymentDropin(mountId, configuration) {
  await window.AdyenWeb.AdyenCheckout(configuration).then((checkout) => {
    const dropin = new window.AdyenWeb.Dropin(checkout, {
      paymentMethodComponents: [window.AdyenWeb.Card],
    });
    dropin.mount('#id-to-mount');
  });
}
Copied to your clipboard
async function mountPaymentDropin(mountId, configuration) {
  await window.AdyenWeb.AdyenCheckout(configuration).then((checkout) => {
    const dropin = new window.AdyenWeb.Dropin(checkout, {
      paymentMethodComponents: [window.AdyenWeb.Card],
    });
    dropin.mount('#id-to-mount');
  });
}

Extend OOPE GraphQL Schema

If you want to retrieve OOPE payment method information from the Commerce instance, you can extend the GraphQL query using drop-in components with the GraphQL Extensibility API.

In build.mjs of the boilerplate, add the following code to extend the OOPE GraphQL schema:

overrideGQLOperations([
  {
    npm: '@dropins/storefront-checkout',
    operations: [
      `
  fragment CHECKOUT_DATA_FRAGMENT on Cart {
    available_payment_methods {
      code
      title
      oope_payment_method_config {
        backend_integration_url
        custom_config {
          ... on CustomConfigKeyValue {
              key
              value
          }
        }
      }
    }
    selected_payment_method {
      code
      title
      oope_payment_method_config {
        backend_integration_url
        custom_config {
          ... on CustomConfigKeyValue {
              key
              value
          }
        }
      }
    }
  }
`,
    ],
  },
]);
Copied to your clipboard
overrideGQLOperations([
  {
    npm: '@dropins/storefront-checkout',
    operations: [
      `
  fragment CHECKOUT_DATA_FRAGMENT on Cart {
    available_payment_methods {
      code
      title
      oope_payment_method_config {
        backend_integration_url
        custom_config {
          ... on CustomConfigKeyValue {
              key
              value
          }
        }
      }
    }
    selected_payment_method {
      code
      title
      oope_payment_method_config {
        backend_integration_url
        custom_config {
          ... on CustomConfigKeyValue {
              key
              value
          }
        }
      }
    }
  }
`,
    ],
  },
]);

Extend the OOPE GraphQL schema in the checkout dropin component initializer. It enables the drop-in component to retrieve the OOPE data.

await initializeDropin(async () => {
  ...
  return initializers.mountImmediately(initialize, {
      langDefinitions,
      models: {
        CartModel: {
            transformer: (data) => {
              return {
                  availablePaymentMethods: data?.available_payment_methods,
                  selectedPaymentMethod: data?.selected_payment_method,
              };
            },
        },
      },
  });
})();
Copied to your clipboard
await initializeDropin(async () => {
  ...
  return initializers.mountImmediately(initialize, {
      langDefinitions,
      models: {
        CartModel: {
            transformer: (data) => {
              return {
                  availablePaymentMethods: data?.available_payment_methods,
                  selectedPaymentMethod: data?.selected_payment_method,
              };
            },
        },
      },
  });
})();

Retrieve the OOPE payment method information from the data coming from the event responses.

events.on('checkout/initialized', handleCheckoutInitialized, { eager: true });
Copied to your clipboard
events.on('checkout/initialized', handleCheckoutInitialized, { eager: true });

Retrieve Cart information from the data coming from the event responses.

events.on('cart/data', handleCartData, { eager: true });
Copied to your clipboard
events.on('cart/data', handleCartData, { eager: true });

Connect to Adobe Commerce

CI/CD

Last updated 2/11/2025

Was this helpful?

Yes

Integrate with EDS storefront

Prerequisites.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Integrate with checkout drop-in components

Extend OOPE GraphQL Schema

Prerequisites