SalesForce – Fundamentals

The HiPay cartridge, available on the Salesforce Commerce Cloud (SCC) LINK Marketplace, allows merchants to offer HiPay Enterprise as a payment solution on their Salesforce Commerce Cloud storefronts.

The cartridge provides several options for entering payment information (credit card or debit card information) during the checkout process:

      • through a hosted page, external to the Salesforce Commerce Cloud platform,
      • or directly on merchants’ Salesforce Commerce Cloud storefronts, through API module calls.

Additionally, a full range of other payment methods are supported.

To enable a Salesforce Commerce Cloud store to use HiPay’s payment services, the developer has to install the cartridge and integrate it to the online store following the instructions provided in this document. For the integration to work properly, merchants should first contact HiPay and fill in an account request on https://hipay.com/.

The integration package contains the following elements:

      • a cartridge called int_hipay_controllers – which is the core integration cartridge
      • a cartridge called bm_hipay_controllers – which is an extension for the cartridge within Salesforce Commerce Cloud Business Manager
      • site-template folder with metadata

The integration is based on the SiteGenesis demo store provided by Salesforce Commerce Cloud. The cartridge is compatible with SiteGenesis 103.1.11 and might require updates and reviews for future versions and releases of SiteGenesis.

Fonctional Overview

Business Manager extension for HiPay

The features of the HiPay cartridge can be configured from Business Manager. On the BM page, merchants can set up the connection to HiPay. To create it, they have to enter their credentials.

Multiple payment methods

The cartridge allows customers to check out with a wide variety of payment methods.

Hosted pages

The cartridge supports the hosted payment page approach of entering payment information directly on pages that are hosted and provided by HiPay. During checkout, merchants’ customers will therefore be redirected to the HiPay hosted payment pages, usually when they are asked to enter payment details. On these pages, customers can select the payment method of their choice (the offering depends on the merchant’s selection). Hosted payment pages can be styled to reflect the merchant’s storefront look-and-feel.

 

iFrame integration

The cartridge enables merchants to use the HiPay payment solution via an iFrame integrated in their own Salesforce Commerce Cloud implementation.

Direct payment API

The cartridge offers customers the possibility to fill in payment information directly on the websites of merchants, who have to be PCI-DSS compliant. Transactions will be validated through the module called HiPay Enterprise API.

The cartridge provides several options for entering payment information (credit card or debit card information) during the checkout process: through a hosted page, external to the Salesforce Commerce Cloud platform, or directly on the merchants’ Salesforce Commerce Cloud storefront, through API module calls.

Additionally, a full range of other payment methods are supported.

Security features

3-D Secure

The cartridge supports 3-D Secure rules and activation if the card being used has been enrolled. The 3-D Secure authentication process will redirect merchants’ customers to a special page hosted by the issuing card company. The cartridge enables the redirection to that page.

After the authentication process, the cartridge ensures that the result is transferred back to Salesforce Commerce Cloud so that the right message is displayed on the frontend and that the order status is set accordingly. Merchants can configure specific rules for the use of 3-D Secure. These rules can be edited or deleted in the configuration parameter “rules 3d secure”.

Device fingerprint

The cartridge supports device fingerprint information by sourcing the dynamically generated JavaScript from HiPay Enterprise. The JavaScript determines the available information and creates or generates a so-called black box. To use this functionality, custom configurations are needed. These custom configurations are not part of the development as they require individual implementation for each customer.

Signature verification

A signature verification mechanism is available for checking the content of requests and redirections between merchants’ sites and HiPay’s pages. In the first place, merchants have to set a secret password or phrase in HiPay’s back office. The secret password or phrase will be used to generate a unique string that will be hashed with an SHA algorithm.

Automatic cancellation

Pending orders are automatically cancelled if not completed within 30 minutes.

Payment configuration

The cartridge supports the “Authorization” and “Direct capture” modes. Please read the Capture documentation in order to have a better understanding of the capture.

Use cases

Short description of the HiPay payment system

HiPay can generally receive payments in two ways: 

    1. via the HiPay Entreprise Payment API (PCI-DSS compliance needed). A result is returned right away. This can only be used for credit cards.
    2. via the “redirect model”, through which a form containing certain fields is posted to HiPay and the customer is redirected to the HiPay Hosted Payment Page (HPP).

After completing the payment, the customer is redirected to the store’s resultURL, which can be configured and contains the result of the payment (successful or declined).

The redirect model can also be implemented in an iFrame solution, where merchants’ customers are redirected to the HiPay pages, in a frame that is inserted in the merchants’ page. This  approach gives customers the feeling that they do not leave the merchants’ site.

Compared to the API, the redirect model offers much more payment methods as well as other functionalities. 

Payment results should be sent asynchronously to a “notification URL” on the merchant (SCC) site. Payments can change status over time (Authorized, Refunded, Cancelled…) on HiPay’s side; statuses are automatically updated on Salesforce Commerce Cloud’s side by sending these notifications. HiPay Enterprise sends notifications to Salesforce Commerce Cloud for each event that occurred/transaction that changed. In order to handle all the notifications, notes are added to the order.

In both cases, the “two-phase ordering” approach is used, through which the order is first created but only “placed” after a payment has been authorized (which is now standard practice in SiteGenesis). If the payment cannot be authorized, the order fails. 

Registered and unregistered customers will be able to follow the standard SiteGenesis flow with the following changes: 

HiPay redirect (hosted payment pages, iFrame integration and multiple payment methods) and HiPay Professional Payment API will be the only payment options.

If HiPay redirect is enabled: 

      • no entering of credit card details on the checkout page is possible when the customer selects this payment method (as this is done on the HiPay hosted payment pages)
      • possibility to choose one of the predefined payment methods on the checkout page with further redirection to HiPay hosted payment pages, if Directory Lookup is enabled and the customer has selected HiPay’s payment method
      • a redirect to the HiPay hosted payment pages after clicking the “SUBMIT ORDER” button on the Order Confirmation page
      • a return to the SCC Order Summary page after successful payment authorization 
      • a return to the SCC Order Confirmation page, if the customer cancelled the payment on the HiPay hosted payment pages
      • a return to the SCC Order Confirmation page with an error message displayed, if the payment was refused 

If HiPay API payments are enabled:  – credit card details are entered and stored in merchants’ SCC store – for the other payment methods, merchants can still redirect customers to the HiPay hosted payment pages, but can disable credit cards via the configuration of their skin Examples of test scenarios

      • All test scenarios involve successful and declined payments.
      • Test scenarios should be done with every available payment method.
      • The used currency should be EUR; only credit cards are enabled for USD.
      • If for a payment method on a hosted page, there is an emulation page, the system should be tested for all options (e.g.: Cancel, Exception, Decline).
      • When making a payment, a Salesforce Commerce Cloud Order object changes its status as follows:

        • CREATED – the iFrame or Hosted page has been shown; the basket has been cleared; the order may stay in this status if the process did not complete properly (bug) or if the user abandons the iFrame or the Hosted page and does not complete the payment.

        • NEW – the order in the iFrame or Hosted page has been accepted – the order has changed its status.

        • OPEN – the order has been viewed in SCC Business Manager after being in status NEW.

        • FAILED – all cases of Cancel and Decline.

HiPay Hosted Page

This use case describes the main steps in which a registered/guest customer successfully creates an order as well as the order with the HiPay Hosted Page.

      • Go to Merchant Tools > Site Preferences > Custom Preferences > HiPay Settings.
      • For HiPay Operation Mode, select hosted (Hosted Page) and click on Apply.

        • A registered customer navigates on the site, adds an item to the cart and proceeds to the cart page.
        • The customer clicks on the Checkout button and fills in the required shipping information.
        • The customer clicks on the Continue button, fills in the required billing information and selects HiPay Hosted as the payment method.
        • The customer clicks on the Continue button, proceeds to the Payment page and clicks on the Place order button.
        • A HiPay hosted page is opened and the customer enters the card details.
        • After successful payment, the customer is redirected to the Summary page and the order confirmation message is successfully loaded.
        • The customer can verify the Order Summary information.
        • The merchant can verify the Order status in SCC BM.
        • The merchant can verify the information in the HiPay Enterprise account.

Please note that a similar flow can be done for guest checkout.

HiPay Hosted Page with 3-D Secure

This use case describes the main steps in which a registered/guest customer successfully creates an order as well as the order with the HiPay Hosted Page with 3-D Secure.

      • Go to Merchant Tools > Site Preferences > Custom Preferences > HiPay Settings.
      • For HiPay Operation Mode, select hosted (Hosted Page) and click on Apply.
      • For 3-D Secure, select 1 (3-D Secure authentication if available) and click on Apply.

        1. A registered customer navigates on the site, adds an item to the cart and proceeds to the cart page.
        2. The customer clicks on the Checkout button and fills in the required shipping information.
        3. The customer clicks on the Continue button, fills in the required billing information and selects HiPay Hosted as the payment method.
        4. The customer clicks on the Continue button, proceeds to the Payment page and clicks on the Place order button.
        5. A HiPay hosted page is opened and the customer enters the 3-D Secure card details.
        6. The customer is redirected to their bank’s site and enters the 3-D Secure code.
        7. After successful identification, the customer clicks on Back to Payment.
        8. After successful payment, the customer is redirected to the Summary page and the order confirmation message is successfully loaded.
        9. The customer can verify the Order Summary information.
        10. The merchant can verify the Order status in SCC BM.
        11. The merchant can verify the information in the HiPay Enterprise account.

Please note that a similar flow can be done for guest checkout.

HiPay API Integration

This use case describes the main steps in which a registered/guest customer successfully creates an order as well as the order with the HiPay API Integration.

      • Go to Merchant Tools > Site Preferences > Custom Preferences > HiPay Settings.
      • For HiPay Operation Mode, select api (API) and click on Apply.
        1. A registered customer navigates on the site, adds an item to the cart and proceeds to the cart page.
        2. The customer clicks on the Checkout button and fills in the required shipping information.
        3. The customer clicks on the Continue button, fills in the required billing information and selects iDEAL as the payment method.
        4. The customer selects the desired issuing bank and clicks on the Place order button.
        5. The customer is redirected to the iDEAL vendor’s site.
        6. The customer enters the payment details.
        7. After successful payment, the customer is redirected to the Summary page and the order confirmation message is successfully loaded.
        8. The customer can verify the Order Summary information.
        9. The merchant can verify the Order status in SCC BM – on the Order screen, open the Payment tab to verify the payment information.
        10. The merchant can verify the information in the HiPay Enterprise account.

Please note that a similar flow can be done for guest checkout.

Compatibility

The HiPay integration cartridge is compatible with Salesforce Commerce Cloud version 101.1.6.

Payment data privacy

If only the redirect method is used, all payment data are entered on the HiPay hosted pages by the customer and no credit card data will be stored in Salesforce Commerce Cloud (except the brand of the card being used).

Examples:

      • HiPay Product Name: hosted
      • HiPay Payment Product List: bcmc,cb,maestro,mastercard,visa,american-express

      • HiPay Payment Category List: credit-card,debit-card

      • HiPay Product Name: dexia-directnet

      • HiPay Payment Product List: dexia-directnet

      • HiPay Payment Category List: realtime-banking