Installing the Oney cartridge

Last update: August 3, 2023

Uploading the cartridge

First thing to do, is to upload the cartridge into to your sandbox.

To add a cartridge to your Commerce Cloud website, please refer to the official commerce cloud documentation below:

Add existing cartridges to your storefront

Registering the cartridge

Once the cartridge is uploaded, you must add it to your cartridge path, please refer to the official commerce cloud documentation below:

Configuring the SFRA cartridge path

The name of our cartridge is : int_oney

Importing the site-template

Metadata

To add the new fields to Commerce Cloud which are specific to Oney, you must import the description of our metadata through the Site Import process.

To do this, please refer to the following Commerce Cloud documentation:

Site import export

Summary of steps:

  1. Go to: Administration / Site Development / Import & Export
  2. In the Import & Export Files section
    a. Click on Upload link
    b. Navigate to the file system-objecttype-extensions.xml (in the oney-data/meta folder) and click on Upload
    c. The page will refresh and the system-objecttype-extensions.xml will appear in the list above
    d. Go back
  3. In the Meta Data section
    a. Click on Import link
    b. Select the file previously uploaded and click on Next
    c. Click on Refresh on the top of the page
    d. Click on Import button
  4. Scroll down to the Status section
  5. Observe the status returned by the Meta Data Import (system-objecttype-extensions.xml) process
  6. Click on Refresh if needed, the status must be to Success

Once you're done importing, the new attributes that are specific to Oney should appear in the system :

  • Order
    • isOney : Flag to indicate if the order was placed with Oney
    • oneyStatus : Stores the status returned by the payment API (see Oney Payment document to list the different status)
  • PaymentMethod
    • isOney : Flag to indicate whether the payment method is linked to Oney
    • oneyIsFree :Flag to indicate if the payment method is free
    • oneyBusinessTransactionCode : Stores the internal Oney Business Transaction Code
    • oneyNumberOfInstallments : Stores the number of installments of the current payment method
  • ShippingMethod
    • oneyIsRelay : Flag to indicate whether the shipping method is a relay (difference has to be made for the payment API)
  • SitePreferences
    • oneyConfiguration : JSON object containing all the configuration set by country
    • oneyCategoryCode : Stores the category code of the products sold on the website

Services & Jobs

Services are required to ensure the cartridge works properly. They allow to communicate with Oney marketing and payment APIs.

Jobs are required to generate payment methods based on the marketing API, and check payment status before the shipping of the goods.

Summary steps to import :

  1. Go to Administration / Operations / Import & Export
  2. Click on Upload link
  3. Navigate to each services.xml and jobs.xml (in the oney-data folder) and upload them
  4. In the Jobs section
    a. Click on Import link
    b. Select jobs.xml and click on Next
    c. Click on Refresh on the top of the page
    d. Click on Next button
    e. Select Replace as Import Mode then Import

Now, you should observe the following :

  1. In the Services section
    a. Click on Import link
    b. Select services.xml and click on Next
    c. Click on Refresh on the top of the page
    d. Click on Next button
    e. Select Merge as Import Mode then Import

Now, you should observe the following :

Oney.preprod service should be used for testing purposes, and oney.prod for production instance only.

Generating the payment methods

Before executing the job that will generate payment methods, you need to configure the SitePreference oneyConfiguration as it contains the different API keys.

To fulfill the preference, go to Merchant Tools / Site Preferences / Custom Preferences and select Oney group.

Now you need to build a JSON object with the API keys given by Oney, based on the following format :

{
  "countryCode": {
    "marketingAPIKey": "",
    "merchantGUID": "",
    "paymentAPIKey": "",
    "pspGUID": "",
    "countryCode": "",
    "displayBannerHP": true,
    "displayBannerPLP": true
  }
}

Where :

  • countryCode
    • ISO2 format, country code of the locales used on the website
    • For example, if you use es_ES locale, countryCode value will be ES
  • marketingAPIKey
    • Key used as X-Oney-Authorization value when using Oney's marketing API
  • merchantGUID
    • Key used as merchant_guid value when using Oney's marketing & payment API
  • paymentAPIKey
    • Key used as X-Oney-Authorization value when using payment API
  • pspGUID
    • Key used as psp_guid value when using payment API
  • countryCode
    • 2 characters country code, not ISO2, given by Oney
    • For example, for ES countryCode, value will be SP
    • For example, for IT countryCode, value will be IT
  • displayBannerHP
    • boolean value to display or not the banner on Homepage
  • displayBannerPLP
    • boolean value to display or not the banner on Product List Page

When the JSON is completed, you will be able to launch the ONEY.ImportOneyPayment job

Click on the Run Now button. This action has to be done at the beginning of your project. It will import new payment methods based on the result of the marketing API, all new methods will set Enabled status to false.

Check the execution status in the Schedule and History panel, it should be OK.

Then, you can check if the payment methods have been well imported, go to Merchant Tools / Ordering / Payment Methods.

When looking at the details at one the new payment methods, you will see the following :

You must not edit anything here, as everything is generated from the job, and some bad behavior could happen if so.

Pay attention to only enable one payment method by value at the time : eg, enable 3XF and not 3XP in the same time.

Remark :

Payment methods will be displayed in front based on the Sort Order attribute with the value generated during the import, you can change the sort value by clicking on « Sort Order ».

Shipping Methods

A custom attribute has been added for shipping methods : oneyIsRelay.

It is a boolean attribute allowing Oney Payment API to identify wether the shipping method is a relay or not. To contribute the value, go to Merchant Tools / Ordering / Shipping Methods / your_payment_method