Use of the cartridge

Last update: August 3, 2023

Rendering Oney features in templates

Because usually, there is a cartridge before int_oney in the cartridge path, the regular includes we made won't work. That's why we describe here the modifications to make in the templates of your custom cartridge.

Homepage Banner

Description

Banners for store homepage are customized with the payment methods enabled. For instance, if I setup 3x 4x and 6x for Spain, then the banner will display these 3 bubbles only. A click on the banner will trigger the terms and condition popin.

Code impact

In the app_custom/cartridge/templates/default/home/homePage.isml file, add the following line after the div with class='container home-product-tiles homepage' :

  <isif condition="${pdict.displayOneyHP}">
      <isinclude template="oney/home/HPBanner" />
  </isif>

Product List Page Banner

Description

Such as the horizontal banner, the vertical banner can be displayed on the product list page and bubbles are dynamically displayed based on the payment methods enabled in the Business Manager. The click in "?" triggers a pedagogic popin.

Code impact

Desktop

In the app\custom/cartridge/templates/default/search/productGrid.isml file, add the following line before the hidden type with class='permalink' :

  <isif condition="${pdict.displayOneyPLP}">
      <div class="only-mobile">
          <isinclude template="oney/search/PLPBanner" />
      </div>
  </isif>

Mobile

In the app\_custom/cartridge/templates/default/search/searchRefineBar.isml file, add the following line after the isloop refinement :

  <isif condition="${pdict.displayOneyHP}">
      <isinclude template="oney/home/HPBanner" />
  </isif>

Pedagogic popin

Description

The structure is the same among all Oney countries. The text is different from a country to another for legal reason. The design may be shared by all countries, its content adapts to country's legislation.

Product Page Simulation

Simulation sentence description

On the product page, customer can identify the 3x 4x Oney payment method. Logos and bubbles are then displayed under the product amount and above "add to basket" buttons.

These sentences are dynamically set with the payment methods chosen in the Business Manager and if the price of the product is within the payment methods amount instalments.

The "?" at the end of the sentence must open the tooltip simulations based on the enabled payment methods.

As an example, "Ou pague em (3x) o (4x)" will display 3x and 4x simulations only.

Simulation tooltip description

Code impact

In the app_custom/cartridge/templates/default/product/components/mainAttributes.isml, add the following line at the end of the file :

  <isinclude template="oney/product/oneyproduct" />

Cart Simulation

Description

On the cart page, Oney logo is also available. Customers can access to enabled simulations by clicking on the "?". By clicking on it, the order total amount is directly simulated based on the payment methods enabled in the Business Manager.

Note: Total cart amount is related to the final price paid by the customer, which must include the item prices, taxes, shipping fees and all other fees charged by the merchant for regular orders.

Code impact

In the app_custom/cartridge/templates/default/cart/cart.isml , add the following line after the <isinclude template="cart/cartTotals" />

  <isinclude template="oney/cart/oneycart" />

Checkout simulations

Description

Among all payment methods activated, the customer can select 3x4x Oney payment method. There are as much 3x 4x Oney payment method as there are activated business transactions.

For instance, if you have activated 3x and 6x only, then the customer will be able to select 3x and 6x payment method. When the customer selects the number of instalments desired, a simulation (including Oney fees) is displayed such as the following information:

• Number of instalments
• Instalment amount
• Fees / commissions
• TAE
• TIN (for Spain only)

Code impact

In the app_custom/cartridge/templates/default/checkout/billing/paymentOptions/paymentOptionsContent.isml, add the following line before the isloop closing tag :

  <isif condition="${paymentOption.hasOwnProperty('oney')}">
      <isinclude template="checkout/billing/paymentOptions/oneyContent" />
  </isif>

And after the isloop closing tag, add the line :

  <isinclude url="${URLUtils.url('Oney-Pedagogique')}" />

In the app_custom/cartridge/templates/default/checkout/billing/paymentOptions/paymentOptionsTabs.isml

Add the following lines at the beginning of the file :

  <isscript>
      var assets = require('*/cartridge/scripts/assets.js');
      assets.addCss('/css/oney.css');
      assets.addJs('/js/oney.js');
  </isscript>

In the loop of paymentOption , add the condition :

  <isif condition="${paymentOption.hasOwnProperty('oney')}">
      <isinclude template="checkout/billing/paymentOptions/oneyTab" />
  </isif>

Modifying custom cartridge / Overriding SFRA

To be able to test or execute the code given in the cartridge, you will need to modify your custom cartridge if you already overrid the files from SFRA, otherwise, you will have to do it.

Validate payment

The validatePayment function from app\storefront\_base/cartridge/scripts/checkout/checkoutHelpers.js calls the PaymentMgr.getApplicablePaymentMethods() to ensure that the payment method selected in the basket is well allowed.

This function takes as parameter a country code linked to the payment method country code, but the data comes from the geolocation of the current customer – so in our case, if we want to test the Spain or Italian payment methods from being in France, it won't work.

There are two ways to solve this problem :

1. Use a VPN to have an IP address coming from these countries
2. Edit the code and replace the countryCode value from the country of the current locale.

Refresh simulations in checkout

It looks like SFRA does not refresh payment methods when changing shipping methods in the one page checkout. This causes problem to Oney cartridge as some payment methods are only available for price ranges, and these minimum or maximum prices can change after choosing another shipping method.

We created a new listener in int_oney/cartridge/oney.js : checkout:beforePayment. This listener should be triggered just before clicking on the "Next : Payment" button.

For this, add the following line

  $('body').trigger('checkout:beforePayment', data);

in SFRA cartridge/client/default/js/checkout/checkout.js or your overriding file this way :

  var shippingFormData = form.serialize();
  
  $('body').trigger('checkout:serializeShipping', {
      form: form,
      data: shippingFormData,
      callback: function (data) {
          shippingFormData = data;
      }
  });
  
  // disable the next:Payment button here
  $('body').trigger('checkout:disableButton', '.next-step-button button');
  $.ajax({
      url: form.attr('action'),
      type: 'post',
      data: shippingFormData,
      success: function (data) {
          // enable the next:Payment button here
          $('body').trigger('checkout:enableButton', '.next-step-button button');
          shippingHelpers.methods.shippingFormResponse(defer, data);
          $('body').trigger('checkout:beforePayment', data);
      },
      error: function (err) {
          // enable the next:Payment button here
          $('body').trigger('checkout:enableButton', '.next-step-button button');
          if (err.responseJSON && err.responseJSON.redirectUrl) {
              window.location.href = err.responseJSON.redirectUrl;
          }
          // Server error submitting form
          defer.reject(err.response.JSON);
      }
  });