Version: next

Implement a Front-Commerce payment method

Choose the payment workflow wisely

Payment can be handled synchronously or asynchronously.

If Front-Commerce allows both strategies to work, we highly recommend you to implement an asynchronous payment method (using IPN) whenever it is possible.

This will prevent your payments from being rejected later within the provider process without your backend application knowing about it.

In this guide, we'll implement an asynchronous Front-Commerce payment method.

Implement the server logic

Front-Commerce allows you to implement your own payment method. New embedded payment methods have to be registered from a GraphQL module. Let’s create a new "PWAy" payment module for a fictive payment provider.

Create a new GraphQL module

Register the payment method in the module’s contextEnhancer

my-extension/runtime.ts
export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }) => {
    // [...] initialization here
    const loader = new MyPaymentLoader();

    const METHOD_CODE = "pway_awesomecheckout";
    const METHOD_TITLE = "PWAy";
    loaders.Payment.registerEmbeddedPaymentMethod(
      METHOD_CODE,
      METHOD_TITLE,
      // this method is called following the onAuthorize call in the AdditionalDataComponent (see below)
      // e.g. to trigger the payment authorization on the provider (validation and capture will be handled asynchronously by IPN)
      (paymentData, orderId, orderPaymentDetails) => {
        return loader.order(paymentData, orderId, orderPaymentDetails);
      },
      null,
      // The notification processor will handle IPN notifications from the payment provider
      new MyPaymentNotificationProcessor(hipayConfig)
    );

    return {}; // you may export loaders here in case the payment provides custom Queries (to fetch a payment token for instance)
  },
});

Implement your loader's `order` method to process a payment

my-extension/loaders/MyPaymentLoader.ts
export default class MyPaymentLoader {
  constructor(/* ... */) {
    /* ... */
  }

  async order(paymentData, orderId, orderPaymentDetails) {
    // process the paymentData and call the payment provider
    const paymentStatus = call(/* ...  */);

    // return payment DomainEvents representing what happened in the remote payment system.
    // These events are broadcasted by Front-Commerce to the registered external event listeners
    // that can use this information to update other remote systems (e.g: adding an Order comment in Magento)
    switch (paymentStatus.status) {
      case SUCCESS:
        // as the IPN handler will handle final authorisation it is often only an authorisation at this step
        return new PaymentAuthorized(
          new PurchaseIdentifier({ orderId }),
          paymentStatus.paymentReference
        );
      case REFUSED:
        return new PaymentRefused(
          new PurchaseIdentifier({ orderId }),
          paymentStatus.reason
        );
    }
  }
}

Implement the notification processor (for IPN handling)

See the existing DomainEvent classes to update the order.

See the existing EarlyNotificationAck classes below

my-extension/loaders/MyPaymentLoader.ts
import {
  AcknowledgeNotification,
  RefuseNotification,
  NotificationProcessor,
  type PaymentCommandDispatcher
} from "@front-commerce/core/graphql/payment";

export default class MyPaymentNotificationProcessor extends NotificationProcessor {
  constructor(...) {
    ...
  }

  async getEarlyNotificationAck(notificationData: {notificationPayload: any}) {
    const data = notificationData.notificationPayload;

    // ensure the notification payload is valid (IPN often uses checksums and hashes with a key to allow you to ensure the notifications can be trusted)

    if (valid) {
      return new AcknowledgeNotification("Accepted");
    } else {
      return new RefuseNotification("Invalid notification");
    }
  }

  async process(notificationData: {status: string}, paymentCommandDispatcher: PaymentCommandDispatcher) {
    // process the notification properly here depending on the status

    switch(notificationData.status) {
      case "IN_PROGRESS":
        // create the order in the backend application using the paymentCommandDispatcher
        const paymentDetails = new PaymentDetails(
          cartId, // this is needed to know which cart is to be placed as an order
          orderTotalAmount,
          orderCurrency
        );
        const orderId = await paymentCommandDispatcher.execute(
          new PlaceOrderCommand(
            paymentDetails, // payment details will be used to ensure the payment corresponds to the cart value and avoid "cart jacking" (insertion of an item in the cart while the payment is processing)
            {
              code: METHOD_CODE,
              additionalData: [
                // additionnal data to be stored in the order
                { key: "transactionId", value: transactionId },
              ],
            },
            guestCartId // for unlogged customer, the guestCartId is needed as it can differ from a logged in user's cartId
          )
        );

        // return an array of DomainEvent that will be stored into the order in the backend, the last event will define the order's status
        return [
          new PaymentCaptureStarted(new PurchaseIdentifier({ orderId }), {
            transactionId,
          }),
        ];
      case "PAID":
        return [
          new PaymentCaptured(
            new PurchaseIdentifier({ cartId })
          ),
        ];
      case "ERROR":
        // process error cases and return the relevant DomainEvent
        return [...];
    }
  }
}

Early Notification returns

Early notifications can be used by notification processors to acknowledge or reject a notification for security reasons (invalid authenticity proof).

See the acknowledgment implementations here

AcknowledgeNotification

When a notification is acknowledged the payment provider is answered with a status 200 - OK

RefuseNotification

When a notification is refused the payment provider is answered with a status 403 - Forbidden

Handle a sublist of payment methods

You may need to dynamically set the list of payment methods displayed for your module.

This is achieved by registering a replacement handler

my-extension/runtime.ts
export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }) => {
    /* ... */
    loaders.Payment.registerEmbeddedPaymentMethod(
      /* ... */
    );

    loaders.Payment.registerMultiplePaymentMethods({
      isMethodToReplace: (method) => method.code === METHOD_CODE,
      getReplacementMethods: async () => {
        try {
          // custom call to fetch the allowed payment methods list
          const paymentMethods = call(/* ... */);
          return paymentMethods.map((method) => ({
            // this is the method code provided to the checkout workflow
            // note that all payment methods must have a common prefix
            code: `${prefix}_${method.id}`,
            // the displayed payment method name on the checkout page
            title: method.description,
            // this method is called following the onAuthorize call in the AdditionalDataComponent (see bellow) instead of the default method defined with registerEmbeddedPaymentMethod
            callback: (paymentData, orderId, orderPaymentDetails) =>
              return loader.order(paymentData, orderId, orderPaymentDetails);
            })),
        } catch (error) {
          // handle the error here
          return [];
        }
      },
    });
    /* ... */
  },
});

Display the new payment method on the UI with additional information

While payment methods provided by Front-Commerce don't need any additional information, you may require some, for example, if you want to let users enter a comment related to the payment method/checkout.

note

See the payment workflows specificities for changes to the current example for each workflow.

Display a custom input for a payment method

You should register a new component in getAdditionalDataComponent.js by following this template:

my-extension/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js
import MyCustomComponent from "theme/modules/CustomComponent/CustomComponent";

const ComponentMap = {
  "<method_code>": MyCustomComponent,
};

// ... the rest of the code should be kept intact

The Custom component referenced here should be created within your my-extension extension, and display the additional information of your payment method to the user.

my-extension/theme/modules/CustomComponent/CustomComponent.tsx
import SubmitPayment from "theme/modules/Checkout/Payment/SubmitPayment";

const CustomComponent = ({
  onAuthorize,
  value,
  gscAccepted,
  error,
  method,
}: {
  onAuthorize: (additionalData: Record<string, string>) => void;
  value: Record<string, string>;
  gscAccepted: boolean;
  error?: string | null;
  method: {
    code: string;
    title: string;
  };
}) => {
  const [comments, setComments] = useState(value?.comments ?? "");

  return (
    <div className="custom-component">
      <input
        onChange={(event) => setComments(event.target.value)}
        value={comments}
        type="text"
      />
      <SubmitPayment
        gscAccepted={gscAccepted}
        onSubmit={() => {
          onAuthorize(gscAccepted ? { comments } : null);
        }}
        error={error}
      />
    </div>
  );
};

export default CustomComponent;

There are a few things to understand here:

The SubmitPayment component is a common component across all payment methods to ensure consistency in how methods are managed.
method the current selected method.
value contains initial additional data (usually it is always null).
onAuthorize should be called with the additional data on <SubmitPayment>'s on submit method.
gscAccepted whether or not the user have accepted the general sales conditions (checkbox above the "Place my order" button). Just forward this to the <SubmitPayment> component.
error an error object if there is an error. Just forward this to the <SubmitPayment> component.

In this example we're only setting a comments as additional information, but you could as well implement a more complex form, by fetching a list for the user to pick from GraphQL and displaying them here for example.

Updating an existing method Additional Data

Sometimes you may need to add an extra field to the additional data of an existing payment method. You first need to check if this payment method already has an AdditionalDataComponent registered.

If AdditionalDataComponent has been registered, you should then override the AdditionalDataComponent and add your custom modifications.
If no AdditionalDataComponent is registered, you can then follow the Display a custom input for a payment method docs, using the existing method's method_code.

Adding a field to all payment methods

In case you require adding a field to all existing payment methods, you should enhance the AdditionalDataComponent by following this template:

my-extension/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js
import CustomEnhancer from 'theme/modules/CustomModule/CustomEnhancer'

const ComponentMap = {
  ..., // registered additional data
};

const getAdditionalDataComponent = (method) => {
  const Component = ComponentMap[method.code];
  return CustomEnhancer(Component);
};

export default getAdditionalDataComponent;

The CustomEnhancer referenced here should be created in your own extension. It should display the base component sent to it and add additional data fields and override the onAuthorize method.

my-extension/theme/modules/CustomModule/CustomEnhancer.tsx
import SubmitPayment from "theme/modules/Checkout/Payment/SubmitPayment";

const CustomEnhancer =
  (BaseComponent) =>
  ({
    onAuthorize,
    value,
    gscAccepted,
    error,
    method,
  }: {
    onAuthorize: (additionalData: Record<string, string>) => void;
    value: Record<string, string>;
    gscAccepted: boolean;
    error?: string | null;
    method: {
      code: string;
      title: string;
    };
  }) => {
    const [comments, setComments] = useState(value?.comments ?? "");

    return (
      <div className="custom-enhancer">
        <input
          onChange={(event) => setComments(event.target.value)}
          value={comments}
          type="text"
        />
        {BaseComponent ? (
          <BaseComponent
            onAuthorize={(additionalData) => {
              onAuthorize({ ...additionalData, comments });
            }}
            value={value}
            gscAccepted={gscAccepted}
            error={error}
            method={method}
          />
        ) : (
          <SubmitPayment
            gscAccepted={gscAccepted}
            onSubmit={() => {
              onAuthorize(gscAccepted ? { comments } : null);
            }}
            error={this.props.error}
          />
        )}
      </div>
    );
  };

export default CustomEnhancer;

Payment workflows specificities

Front-Commerce provides different hooks allowing you to use the payment method of your choice. This section explains the implementation specificities of each payment workflows.

note

The documentation here only explains changes to apply to the default implementation example for each workflow.

See the basic implementation tutorial for a detailed implementation
See the high-level workflow explanation to choose the right implementation for your usecase.

Async Order

This workflow is recommended for payments that are fully front-end (e.g. Payzen/Lyra, Paypal)

Server changes

Ensure the direct payment processor call does nothing in the extension's contextEnhancer:

my-extension/runtime.ts
export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }) => {
    // ...
    loaders.Payment.registerEmbeddedPaymentMethod(
      METHOD_CODE,
      METHOD_TITLE,
-      (paymentData, orderId, orderPaymentDetails) => {
-        return loader.order(paymentData, orderId, orderPaymentDetails);
-      },
+      () => {
+        throw new Error(
+          "The payment method should only be handled by IPN notifications"
+        );
+      },
      null,
      new MyPaymentNotificationProcessor(hipayConfig)
    );

    return {}; // you may export loaders here in case the payment provides custom Queries (to fetch a payment token for instance)
  },
});

note

This implies the order method in the module’s loader is not needed for this method (your may need to implement other methods instead to be used by the NotificationProcessor)

my-extension/loaders/MyPaymentLoader.ts
export default class MyPaymentLoader {
-  async order(paymentData, orderId, orderPaymentDetails) {
-   // ...
-  }
}

Theme changes

Override theme/pages/Checkout/checkoutFlowOf.js to indicate the use of the asyncOrder workflow for the pway_awesomecheckout method code

app/theme/pages/Checkout/checkoutFlowOf.js
const checkoutFlowOf = (method) => {
  ...
+  if (method === "pway_awesomecheckout") return "asyncOrder";

  return "directOrder";
};

export default checkoutFlowOf;

Direct Order

A direct order handles directly the payment on onAuthorize call in the CustomComponent you created (my-extension/theme/modules/CustomComponent/CustomComponent.js).

This onAuthorize call will provide the information to loader.order() implemented server-side. This last method is responsible to handle the full payment process.

Sub workflow : Direct Order with additional action

You may need to handle a second payment step with a Direct order workflow (3DS validation, etc).

In this case, perform the following steps:

Reference the payment workflow

Override theme/pages/Checkout/checkoutFlowOf.js to indicate the use of directOrderWithAdditionalAction

app/theme/pages/Checkout/checkoutFlowOf.js
const checkoutFlowOf = (method) => {
  ...
+  if (method === "pway_awesomecheckout") return "directOrderWithAdditionalAction";

  return "directOrder";
};

export default checkoutFlowOf;

Create an additional action component to handle the addtional payment step

my-extension/theme/AdditionalAction/MyAdditionalAction.tsx
import { useIntl } from "react-intl";
// Other imports...

const MyAdditionalAction = ({ onOrderPlacedArgs, originalOnOrderPlaced }) => {
  const intl = useIntl();
  const orderId = onOrderPlacedArgs[0];

  // call originalOnOrderPlaced() when the additionnal action is successfull

  return (/* ... */);
};

export default MyAdditionalAction;

Reference the additional action component

my-extension/theme/modules/Checkout/PlaceOrder/getAdditionalActionComponent.js
import None from "theme/modules/Checkout/PlaceOrder/AdditionalAction/None";
import MyAdditionalAction from "theme/AdditionalAction/MyAdditionalAction";

const ComponentMap = {};

const getAdditionalActionComponent = (paymentCode, paymentAdditionalData) => {
  if (paymentCode === "pway_awesomecheckout")) {
    return MyAdditionalAction;
  }
  return ComponentMap?.[paymentCode] ?? None;
};

export default getAdditionalActionComponent;

Redirect Before Order

warning

This workflow is only supported for Magento2, please contact us if you need this workflow with another backend server

A redirect before order workflow allows to interact with payment providers handling the complete payment workflow on their side.

Front-Commerce will only redirect to the payment provider and ensure the order creation afterwards.

Server changes

Register the payment method payment processor with

registerRedirectBeforeOrderPaymentMethod module’s contextEnhancer

Replace the extension's contextEnhancer with the following

my-extension/runtime.ts
export default createGraphQLRuntime({
  contextEnhancer: ({ loaders, config }) => {
    const shopConfig = config.shop;
    const METHOD_CODE = "pway_awesomecheckout";
    const METHOD_TITLE = "PWAy";

    // [...] initialization here
    const loader = new MyPaymentLoader(shopConfig, METHOD_CODE, ...);

    loaders.Payment.registerRedirectBeforeOrderPaymentMethod(
      METHOD_CODE,
      METHOD_TITLE,
      loader,
    );

    return {}; // you may export loaders here in case the payment provides custom Queries (to fetch a payment token for instance)
  },
});

Implement the three required methods in the loader

my-extension/loaders/MyPaymentLoader.ts
type PaymentCaptured = {
  transactionId: string; // the transactionId from the payment provider, it allows the merchant to make the link between an order and a payment
  success: boolean; // the capture succeed
  cancel: boolean; // the capture was canceled
  // NOTE: if both success and cancel are false, the capture is considered failed (throwing an error will lead to the same event)
}

export default class MyPaymentLoader {
  constructor(shopConfig, methodCode, ...) {
    ...

    this.callbackUrl = `${shopConfig.url}/checkout/payment/${methodCode}`;
  }

  /**
   * @param {{paymentId: any, cart: any}} paymentData the paymentId is the paymentMethod registered previously
   * @returns {PaymentCaptured} the captured payment status
   */
  mapCartPaymentToRedirect({ paymentId, cart }) {
    return {
      url: true, // set it to true for URL redirection
      html: true, // set it to true for HTML code insertion
      value: `...?callbackUrl=${this.callbackUrl}`, // the URL or HTML code to handle the redirection to the payment provider
    }
  }

  /**
   * @param {any} data : callbackUrl query parameters
   * @returns {boolean} is the payment authorized or not, returning false will lead to the checkout cancellation
   */
  async isReturnSuccess(data) {
    return true | false;
  }

  /**
   * proceed to the payment capture in the payment provider
   * NOTE: this stage follows the order creation in Magento, you should provide the orderId to the payment provider for the transaction to be easily found by the merchant
   * @param {any} additionalData : callbackUrl query's additionalData parameter -> "https://callbackUrl?additionalData=..."
   * @param {string} orderId : magento order Id
   * @param {{ currency:string, totalInclTax: number }} paymentDetails : the currency and value of the order (please ensure the payment has the same value and currency to prevent cart hijack)
   * @returns {PaymentCaptured} the captured payment status
   */
  async capturePayment(additionalData, orderId, paymentDetails) {
    return {
      transactionId,
      success: true,
      cancel: true,
    };
  }
}

Theme changes

warning

No AdditionalDataComponent is required for this implementation as there is no frontend component displayed by Front-Commerce

Using this workflow, you will need to override theme/pages/Checkout/checkoutFlowOf.js to indicate the use of redirectBeforeOrder:

app/theme/pages/Checkout/checkoutFlowOf.js
const checkoutFlowOf = (method) => {
  ...
+  if (method === "pway_awesomecheckout") return "redirectBeforeOrder";

  return "directOrder";
};

export default checkoutFlowOf;

note

We encourage you to have a look at the payment extensions' source code from Front-Commerce to learn about advanced patterns:

Choose the payment workflow wisely​

Implement the server logic​

Handle a sublist of payment methods​

Display the new payment method on the UI with additional information​

Payment workflows specificities​

Async Order​

Server changes​

Theme changes​

Direct Order​

Sub workflow : Direct Order with additional action​

Redirect Before Order​

Server changes​

Theme changes​

Choose the payment workflow wisely

Implement the server logic

Handle a sublist of payment methods

Display the new payment method on the UI with additional information

Payment workflows specificities

Async Order

Server changes

Theme changes

Direct Order

Sub workflow : Direct Order with additional action

Redirect Before Order

Server changes

Theme changes