Salesforce Commerce Cloud
1. Introduction
Our Salesforce Commerce Cloud plug-in comes with regular updates and full integration support, guaranteeing a versatile out-of-the-box solution to accept online payments easily:
- Supports both Hosted Checkout Page and Hosted Tokenization Page integration mode
- Offers the following payment methods on our platform:
Alipay
American Express
Apple Pay
Bancontact
Bizum
Carte Bancaire
Cpay
Diners Club
iDEAL
Illicado
Intersolve
JCB
Multibanco
OneyBrandedGiftCard
PayPal
Maestro
MasterCard
Visa
WeChatPay
- Manages multiple stores
- Accepts payment operations (Refunds, authorisations, captures etc.) directly from your Salesforce Commerce Cloud Business Manager
Check out our documentation to learn how to link your store with our platform to profit from all these features!
- Entrust a system administrator with the installation and the configuration of the plugin
- Accordingly, the target audience of this documentation are system administrators with a profound knowledge of Salesforce Commerce Cloud / Demandware
2. Create account
To process transactions with this plugin, you need an account on our platform.
This plugin works with both our test and live environment. A test account is a great way to get familiar with both the plugin and our platform. Once you want to go live, create a production account or contact us!
3. Install plugin
The first step to use the plugin is the installation process. Before you proceed, make sure your infrastructure meets these system requirements:
Item | Description |
---|---|
Plugin package | |
Direct credentials |
|
Salesforce Commerce Cloud |
Compatibility with Salesforce Commerce Cloud version Storefront Reference Architecture (SFRA)
|
PCI compliancy |
SAQ A (14) |
Once done, follow these steps:
- Install cartridge
You can use the cartridge with Storefront Reference Architecture (SFRA). Install the cartridge to your project root directory at the same level as storefront-reference-architecture. Have a look at this folder structure example:my-project/ |-- link_ingenico_ogone/ | |-- cartridges/ | | |-- bm_ingenico_ogone/ | | |-- int_ingenico_ogone/ | |-- documentation/ | |-- metadata/ |-- storefront-reference-architecture | |-- cartridges/ | | |-- app_storefront_base/ | | |-- modules/
If you have renamed the storefront-reference-architecture folder, make sure to update the base path in package.json - Install Node modules
From the cartridge’s root directory, install Node modules using your command line:npm install
- Build code
From the cartridge’s root directory, compile the client-side assets using your command line:npm run build
- Upload code
Upload int_ingenico_ogone and bm_ingenico_ogone using Commerce Cloud UX Studio or
sgmf-scripts command line utils. - Import metadata
To add new configuration items, import the predefined metadata by following these steps:- Open the /metadata/site_import/sites/ folder
- Rename the yourSiteId folder to the ID of your site in the Business Manager
- Zip the site_import folder
- In the Business Manager, go to Administration > Site Development > Site Import & Export and import the zipped file
After the import, attributes named ingenicoOgone[attributeName] are added to Administration > Site Development >:
System Object Types > Site Preferences > Attribute Definitions
System Object Types > Order > Attribute Definitions
System Object Types > OrderPaymentInstrument > Attribute Definitions
System Object Types > CustomerPaymentInstrument > Attribute Definitions
Custom Object Types
The service ingenico.https.direct.yourSiteId is added to Administration > Operations > Services
4. Configure plugin
After the installation, you need to configure the plugin to link your store to our platform.
Login to the Business Manager. Set the following values in the menus and confirm by clicking "Apply" or "Save":
Set Cartridge paths
To embed an external module and link it with the Business manager, follow these steps:
-
- Go to Administration > Sites > Manage Sites > [yourSite] > Settings. Enter the following in "Cartridges":
int_ingenico_ogone:app_storefront_bass
- Go to Administration > Sites > Manage Sites > [yourSite] > Settings. Enter the following in "Cartridges":
The image above shows where to add the value in the Settings menu
-
- Go to Administration > Sites > Manage Sites > Manage the Business Manager site > Settings. Enter the following in front of any other existing cartridges:
bm_ingenico_ogone:int_ingenico_ogone:bm_app_storefront_base:bm_custom_plugin
- Go to Administration > Sites > Manage Sites > Manage the Business Manager site > Settings. Enter the following in front of any other existing cartridges:
The image above shows where to add the value in the Settings menu
Define Business Manager permissions
Manage the access rights of the module to ensure correct interaction with your Business manager and storefronts:
-
- Go to Administration > Organization > Roles & Permissions. Click on the role you want to update in the table. Go to Business Manager Modules
- In the "Select context" pop-up, select all storefront sites that will use Ingenico-Ogone Payments Cartridge
The image above shows where to flag the storefront sites in the Business Manager Modules
Configure credentials for Test/Live environment
To target our test/live environment and make sure that your requests are legitimate, you need to configure URL endpoints and an API key/secret pair linked to a specific PSPID.
- Go to Administration > Operations > Services. Open the “Credentials” tab
- Click on the ingenico.https.direct.yourSiteId.TEST in column “Name” in the table to configure either test/live. Perform the action for both environments
The image above shows where to select the name representing the test/live environment
- Enter the following in the table:
Property | Description/Actions |
---|---|
Name | Replace yourSiteId with the actual ID for your site |
URL | The test or live endpoint on our platform. Copy them from our dedicated guide. |
User | Enter the API key of your test or live PSPID. Read our dedicated guide to learn how to generate one |
Password | Enter the API secret of your test or live PSPID. Read our dedicated guide to learn how to generate one |
- Open the Services Tab. Click on ingenico.https.direct.yourSiteId and enter the following in the table:
Property | Description/Actions |
---|---|
Name | Replace yourSiteId with the actual ID for your site |
Communication Log | On test environments, the communication log could be enabled for debugging purposes |
Credentials | Check the updated service credentials are selected. |
Perform the action for both environments.
- Read our dedicated guides about API endpoints and authentication to get a thorough understanding about the test/live environment and API key/API secret
- We strongly recommend configuring a separate name for both our test and live environment. This will allow you to manually switch from one environment to the other easily
- Make sure not to mix up credential from test with live and vice versa
Set up Merchant ID, Data Locale and Operation code
Every transaction is channeled via a test/live PSPID on our platform. You also need to define whether our platform processes transactions in authorisation or direct sale mode. If your customers’ native language is different than English, you also need to define the language of the payment pages via the locale.
- Go to Merchant tools > Site Preferences > Custom Preferences. Click on “INGENICO_OGONE” in column “ID” for setting up your general configuration to connect your store to our platform. Perform the actions as stated in the table:
The image above shows where to select the ID to be configured
- Enter the following data on the site:
Property | Description/Actions |
---|---|
Merchant ID | Enter the PSPID on our platform you want to use for transaction processing |
Date Locale | Optional – only relevant if your storefront site uses a different locale than English You must set the Date pattern in an unused English locale. ie.: en_EN , en_CA Used to generate a signature to authenticate requests sent to our platform. One of the headers used to generate this signature is the date, which needs to be in a specific format The locale also defines the language of the payment pages To set up the locale, follow these steps:
Make sure to use only locales that are available on our platform. Find a full overview for both Hosted Checkout Page and Hosted Tokenization Page here |
Operation code |
Define whether to process the transactions as authorisation mode or as direct sale. Select one of the following options:
If you authorise payments only, make sure that you capture them later. Only then will the transaction reach StatusCode=9, for which you receive funds
|
Configure payment methods and integration modesWe categorise payment methods in two different clusters
- Card payments
- Alternative payment methods
You can process card payments either via Hosted Tokenization Page or Hosted Checkout Page, whereas the alternative payment methods are available only via Hosted Checkout Page
Follow these steps to make your choice:
- Go to Merchant tools > Ordering > Payment methods. Click on either “INGENICO_OGONE_CARD”/”INGENICO_OGONE_REDIRECT” in column “ID”. Make sure to select YES for enabled. Perform the actions as stated in the table:
ID value | Description/Actions |
---|---|
INGENICO_OGONE_CARD | Covers all card-based payment methods You can offer these to your customers in two ways:
Bancontact is available only on Hosted Checkout Page in QR code mode |
INGENICO_OGONE_REDIRECT |
Covers all alternative payment methods (digital wallets, mobile payment methods, gift cards etc.) Upon selection of the brand, the plugin redirects your customers to our Hosted Checkout Page or to the third-party provider for entering the payment credentials Only option ”(2) Hosted Checkout Page” is available for these payment methods. |
- Have a look at all available payment methods our platform has to offer
- The plugin uses a specific API call in real-time to ensure your customers can choose any active payment method in your account. If you want to add more payment methods to your account, contact us
- Go to Merchant tools > Site Preferences > Custom preferences. Click on either of them in column “ID” to configure and customise them
The image above shows where to select the “INGENICO_OGONE_CREDIT”/ ”INGENICO_OGONE_REDIRECT” to be configured
ID value | Description/Actions |
---|---|
INGENICO_OGONE_CARD |
Settings for the Hosted Tokenization Page
If you select Hosted Checkout Page for integration mode, upload the payment page template in Ingenico_Ogone_Redirect |
INGENICO_OGONE_REDIRECT |
Settings for the Hosted Checkout Page
|
Configure webhooks
The plugin uses webhooks to get the current status of your transactions from our platform. This way your store database is always up to date.
- Configure a WebhooksKey, WebhooksKeySecret and Endpoint URLs in your PSPID as described in our dedicated guide. Make sure to use the following formula for your endpoint URLs:
https://{domain}/on/demandware.store/Sites-{yourSiteId}-Site/{locale}/IngenicoOgone-Webhooks - Go to Merchant tools > Site Preferences > Custom preferences. Click on “INGENICO_OGONE_WEBHOOKS” in column “ID”. Perform the actions as stated in the table:
The image above shows where to select the “INGENICO_OGONE_WEBHOOKS” to be configured
ID value | Description/Actions |
---|---|
Webhooks Key ID |
Enter the webhooks Key ID of your test or live PSPID from the previous step |
Webhooks Key Secret | Enter the Webhooks Key Secret of your test or live PSPID from the previous step |
- Go to Administration > Operations > Jobs. Click on “IngenicoProcessWebhooks” in the list. Go to Job Step to set the scope to your site. Configure the schedule for the job based on your needs
Depending on your business volume for near real-time transaction processing, we recommend setting the job schedule between 1 and 5 minutes. The default value for job schedules is 5 minutes
Find a thorough overview on possible webhook events in our dedicated documentation
Test connection
Once you have completed all the steps, verify the configuration by establishing a test connection between the plugin and our platform:
- Go to Merchant Tools > Ordering > Ingenico-Ogone Transactions. Click on the “Test API connection” button. Check that the appearing dialogue box states “Connection to the Ingenico-Ogone API succeeded”
The image above shows where to find the “Test API connection” button in the Business Manager
The image above shows where to find the “Test API connection” button in the Business Manager
5. Manage payments
We have designed the plugin to follow-up on your orders automatically and autonomously, freeing you from the administration involved. Learn here how to use our plugin effectively to make your business thrive!
Follow-up on orders Check payment status / Process unconfirmed orders
To make sure
- your platform registers successful payments (StatusCode=5 or 9 and Status=”PAYMENT_CREATED”) as such and not as unfinished (because of a failed redirection of your customers to the Salesforce Commerce Cloud website
- authorised transactions are finalised by a capture (If you choose Operation Code: Authorisation during the initial order)
the plugin implements the “Check payment status job”. Follow these steps to make them work:
- Modify property cancelUnconfirmedOrderAfterHours to the desired amount of hours after which the plugin cancels an order in a pending status
- Check out how to capture authorisations automatically or manually
Capture authorisation automatically
If you choose to authorise transactions only during the initial order, our plugin will capture them for you at a later point. You can define the intervals and the timing for the captures based on your business requirements.
Go to Administration > Jobs > IngenicoCaptureAuthorizedPayments > Schedule and History. Perform the actions as stated in the table for the respective capture mode:
Capture mode | Description/Actions |
---|---|
Capture authorisations several times a day |
|
Capture payments at the end of the day |
|
Perform maintenance operations
Captures, refunds and cancellations of authorisations are standard processes (also known as maintenance operations) in your everyday business logic. Learn here how to perform these operations in the Business manager:
Go to Merchant Tools > Ordering > Ingenico-Ogone Transactions. Look up the transaction in question and click on “Details” in column “Category”. The dialogue box shows the possible actions you can perform on a transaction. Perform the action as stated in the table to perform the respective maintenance operations
The image above shows how to reach the menu to perform maintenance operations
Maintenance operations | Description/Actions |
---|---|
Capture |
Capture authorised transactions (StatusCode=5 / Status=PENDING_CAPTURE) to effectively receive the funds for the order
If you want our plugin to capture transactions automatically, follow these instructions |
The image above shows where to fill in the amount to capture and the “Capture” button
Maintenance operations | Description/Actions |
---|---|
Refunds |
Reimburse your customers for captured transactions (StatusCode=9 / Status=COMPLETED)
|
The image above shows where to fill in the amount to refund and the “Refund” button
Maintenance operations | Description/Actions |
---|---|
Cancellations |
Cancel authorised transactions (StatusCode=5 / Status=PENDING_CAPTURE)
|
The image above shows where to find the “Refund” button
Perform test transactions
Use our platform’s test environment to make sure your plugin works as intended. We offer test data sets on both our dedicated test cases page and in the “Testing” tab for individual payment methods.