Monext SFRA cartridges

---

Table of Content

• Monext SFRA cartridges
  • Table of Content
• Overview
• Features
  • Hosted payment page (HPP)
  • Widget
  • Manual order operations
  • Additional order handling
• Prerequisites
• Configuration
  • New Site preference attributes
  • New custom attributes of order level
  • New payment method and payment processor
  • New service configuration
• Installation
  • Import folders
    • Instance imports
    • Site imports
  • Preferences settings
  • Cartridge int_monext
  • Cartridge int_monext_overrides - can be added to path or used as reference for the required changes
  • Cartridge bm_monext
• Additional resources for developers
• License
• Contact and support

Overview

This repository contains Salesforce Commerce Cloud integration cartridge for Monext API. It is intended for the SFRA version of the platform.

Features

Hosted payment page (HPP)

After configuration, using this payment method in checkout will notify the user that upon order confirmation they'll be taken to a payment page hosted by Monext to enter their payment information.

After interacting the HPP user will be taken to either thank you page or error or back to cart depending on the payment outcome.

Widget

When configured a widget will be shown on order confirmation page after user confirms the order.

After interacting the widget user will be taken to either thank you page or error or back to cart depending on the payment outcome.

Manual order operations

In Customer Service Center (CSC), on an order details page a new page is added under 'Manage Orders' (found in the 'More...' dropdown at the top-right).

On that page, the user can see the captured, cancelled and refunded summaries and can trigger manual captures, cancellations and refunds.

This basic implementation can be extended with additional code to cover different business needs.

Additional order handling

The actual business cases for processing an order vary greatly with each project. Some basis is created to facilitate simple order flows and payments - explained below. It should be noted that it is expected that in most cases order handling and/or transaction operations will not be handled entirely in SFCC, but in specialised order management/fulfillment platforms.

A custom job step custom.monextHandleOrders is implemented. It accepts two parameters - query for the orders and array of allowed actions.

It can be used to automate certain processes depending on the business cases. It can be set to run on schedule or manually.

Example 1: Capture amount for shipped orders. In that case the query for orders could be:

(status=3 OR status=4) AND shippingStatus=2 AND paymentStatus=0

NEW/OPEN orders, that are shipped and not paid.

Actions object, should allow only capture:

{"shouldTryFailOrder":"false","shouldTryPlaceOrder":"false","shouldTryRefundPayment":"false","shouldTryCapturePayment":"true","shouldTryCancelPayment":"false","shouldTryCancelOrder":"false","shouldSetOrderAsPaid":"false"}

Example 2: Refund a certain amount for cancelled orders. In that case the query for orders could be:

status=6 AND paymentStatus=2

Cancelled orders, that are paid.

Actions object, should allow only refund:

 {"shouldTryFailOrder":"false","shouldTryPlaceOrder":"false","shouldTryRefundPayment":"true","shouldTryCapturePayment":"false","shouldTryCancelPayment":"false","shouldTryCancelOrder":"false","shouldSetOrderAsPaid":"false"}

Example 3: Cancel transactions that are only authorized but the order is cancelled before capture. In that case the query for orders could be:

status=6 AND paymentStatus=0 AND custom.monextIsAuthorizedOnlyTransactionCancelled!=true

Cancelled orders, that are paid.

Actions object, should allow only refund:

 {"shouldTryFailOrder":"false","shouldTryPlaceOrder":"false","shouldTryRefundPayment":"false","shouldTryCapturePayment":"false","shouldTryCancelPayment":"true","shouldTryCancelOrder":"false","shouldSetOrderAsPaid":"false"}

The conditions for each action are added in the code of the cartridge in int_monext\cartridge\scripts\monext\monextFlowRules.js. You can override this file with different rules for each action.

Prerequisites

1. Having your Monext API key ready. You can copy it (incl. 'Basic ') from the Monext backoffice.

2. Having your Monext "Point Of Sales" identifier.

3. (optional) Having a list ot payment method IDs to be shown to the user. Found in Monext backoffice.

Configuration

New Site preference attributes

This cartridge add the following "Site preferences" attributes:

• Point of sale
• Capture method
• API key
• Environment
• Mode
• Payment Method IDs

New custom attributes of order level

To store the Monext session ID:

New payment method and payment processor

New service configuration

• name: monext

No credentials are in the service configuration. Everything is set in site preferences.

Installation

Import folders

Instance imports

Import instance template from folder instance_template to

1. Add service,

   or create a service profile, credentials and service. Service has to be monext.

2. Add custom attribute of type string monextSessionID to Order system object,

   or crete the attribute, check the meta file for exact configuration.

3. Add attributes and group for sitePreferences object:

   1. monext_pointOfSaleReference
   2. monext_capture
   3. monext_ApiKey
   4. monext_environment
   5. monext_mode
   6. monext_paymentMethodIDs

   Or create the attributes from the list, check the meta file for exact configuration.

Site imports

In the folder site_template, rename the subfolder in sites named RefArchGlobal to match the site name and import the site template to (Repeat for each separate site):

1. Add payment processor and method with name MONEXT,

   or create them for the site.

Preferences settings

Configure the preferences:

1. monext_pointOfSaleReference (refer to Prerequisites)
2. monext_capture - Must be one of AUTOMATIC / MANUAL.
3. monext_ApiKey - API key as copied from Monext. Basic auth string containing user (matches Merchant ID) and password, joined with : and base64 encoded can be coped directly from the API key (refer to Prerequisites).
4. monext_environment - Production or Test.
5. monext_mode - HPP or Widget.
6. monext_paymentMethodIDs - Add the methods to be displayed to the user. Ids available in Monext backoffice. Can be empty, then all methods are displayed.

Cartridge int_monext

1. Copy int_monext cartridge to current project.
2. Add int_monext to the start of the cartridge path for the site.

Cartridge int_monext_overrides - can be added to path or used as reference for the required changes

1. (if used) Copy int_monext_overrides cartridge to current project.

2. (if used) Add int_monext_overrides to the start of the cartridge path for the site.

3. Update or override cartridges\app_storefront_base\cartridge\templates\default\checkout\billing\paymentOptions\paymentOptionsContent.isml:

   

4. Update or override cartridges\app_storefront_base\cartridge\templates\default\checkout\billing\paymentOptions\paymentOptionsTabs.isml:

   

5. Update or override cartridges\app_storefront_base\cartridge\templates\default\checkout\billing\paymentOptions\paymentOptionsSummary.isml:

   

6. (only for HPP mode) Override cartridges\app_storefront_base\cartridge\controllers\CheckoutServices.js to allow interruption of order placement flow until HPP calls back. A new endpoint will handle the callback:

   

7. Update or override cartridges\app_storefront_base\cartridge\models\payment.js:

8. (only for HPP mode) File cartridges\app_storefront_base\cartridge\scripts\checkout\checkoutHelpers.js was overridden to allow HPP URL to be communicated to the confirmation flow:

9. (only for Widget mode) Update or override cartridges\app_storefront_base\cartridge\templates\default\checkout\checkout.isml to add a Cancel button under the widget

10. (only for Widget mode) Update or override cartridges\app_storefront_base\cartridge\templates\default\common\layout\checkout.isml

11. Update frontend code cartridges\int_monext_overrides\cartridge\client\default\js\checkout\checkout.js - file provided in the cartridge for reference. Actual change to be done depending on the frontend compiation approach

Cartridge bm_monext

1. Upload bm_monext on instance.
2. Add bm_monet and int_monext to business manager cartridge path.

Additional resources for developers

• Monext API documentation
• SFCC

License

This cartridge's source code is completely free and released under the terms of the MIT license.

Contact and support

If you want to contact us, the best way is through this page on our website and send us your question(s).

We guarantee that we answer as soon as we can!

If you need support you can also directly check our FAQ section and contact us on the support page.