RELATED TO THIS PAGE

ON THIS PAGE

Product Overview

The Oracle CX Commerce integration gives you access to a wide range of features, tailor-made to help you increase sales and approve more orders. Improved fraud management solutions, tokenization, and popular payment acceptance methods mean more happy customers and less risk. 

  • Compatible with OSF: v5.14.0 and below
  • Compatible with OCC Version: v26.03
     

This integration requires:

  • Yarn version: 1.22.4
  • NodeJS version: 18.16.1, pr NVM to manage multiple versions locally

  • Integration Features:
    • REST API
    • Microform 
    • 3DSecure
  • Channels:
    • eComm (CNP)
    • In-App
  • Payment Methods:
    • Visa
    • MasterCard
    • Maestro
    • American Express
    • Apple Pay
    • Google Pay*
    • Discover
    • Diners
    • Visa Click-to-Pay
  • Payment Functions:
    • Authorisation
    • Capture
    • Sale
    • Void
    • Full Refund
    • Partial Refund
    • Full Reversal
    • Follow on Credit
    • Standalone Credit
    • Token Management Services (CIT only)
  • Fraud Management:
    • Decision Manager
    • Device Fingerprint ID
    • Advanced Screening

      *Google Pay transactions via a non-Android device may not invoke the Payer Authentication journey for your customer.
      If you choose to proceed with an individual non-secure transaction, please be aware that you may lose any liability shift protection that would usually be provided by Payer Authentication.

Getting Started

Create an Extension ID

In order to upload an extension into Commerce Cloud, you must generate an ID for the extension and update the same in packages/payment-gateway/ext.json file To create an extension ID:

  • Log into Commerce Cloud.
  • Navigate to Settings->Extensions->Developer tab.
  • Click on Generate ID button.
  • Enter a name for the extension and click Save.
  • Copy and update the generated extension ID

 

Upload Extension

Before uploading the extension, zip all the files within your packages/payment-gateway directory except settings.json. This is the file you upload to Commerce Cloud to make the extension available for use.

Settings -> Extension -> Upload Extension

Select the extension .zip file from your local file system. Once the module is installed, head back to the Oracle Commerce Cloud Admin to configure it.

Cybersource Prerequisites

You will be able to configure this integration to either Test or Production. If you do not yet have a live Cybersource account, or you wish to first test the integration, then creating a sandbox account will not only allow you to start programmatic integration but also provides access to the Merchant Portal.

Generate REST Keys

Before configurating this integration, you are required to generate your REST keys within your Merchant Portal for both (Live) and (Test)

  • Sign into your Merchant Portal (Live) or (Test)
  • Access Payment Configuration -> Key Management
  • Select the 'Generate Key' button in the top right hand corner
  • Select your key type as 'REST - Shared Secret' and Generate Key
  • Copy your Shared Secret Key values and save them securely

 

 

 

 

Enable gateway in OCC Admin

After successful deployment you will need to enable your payment gateway:

  • Go to OCC Admin -> Settings -> Payment Processing
  • Open 'Payment gateways' tab and choose ‘Cyber source Official’ from the list
  • Select 'Payment Gateway Enabled' option
  • Configure gateway settings by providing values (e.g. merchant credentials) for particular channel (Preview, Storefront, Agent)
  • Save Changes
  • Go back to the 'Payment Types' type
  • Select supported credit/debit card types from the list [Possible card types: VISA, MASTERCARD, AMEX, DISCOVER, DINERSCLUB, JCB, CARTESBANCAIRES, MAESTRO, CARNET, CUP]
  • Save Changes

 

Please note: While this integration has been developed by Visa Acceptance Solutions to enable the above payment methods, not all options will necessarily be active or available on your Cybersource account. Please review the Full Feature List at the top of this page to understand which Products and Services are available to you.


Configure Generic Webhooks

You need to setup Generic Payment so that Oracle Commerce knows where to send payment requests.

  • Open OCC Admin and got to Settings -> Web APIs -> Function APIs
  • Configure both Generic Payment Production and Preview webhooks
  • Replace URL (the {env} part) with your specific value
  • Make sure you copy secret key as it will be required for SSE deployment

 

Install SSE (server-extension)

Configure production settings in the following file packages/server-extension/config/app.prod.json:

  • cache.service.ttl.secs - Default caching TTL, can be zero value
  • cache.gatewaysettings.ttl.secs - Caching TTL for gateway settings call (see packages/server-extension/src/middlewares/gatewaySettings.ts). You might want to use TTL value '1' while testing SSE so that changes in gateway settings performed in OCC Admin become immediately available to SSE and Payment Widget respectively
  • crypto.service.key - Random key which is used to encrypt data so that it is not tampered in UI
  • partner.developerId - Leave the value as is
  • partner.solutionId - Leave the value as is
  • logging.webhook.http - Enable webhook request/response logging
  • logging.api.error - Enable logging for errors
  • logging.api.access - Enable logging for incoming requests
  • payments.secret.key - Webhook secret key (SHA512)

 

Deploy

Build SSE extension with the following command:

cd packages/occ-sse-gateway

yarn build:prod

 

Deploy SSE by running commands (from project's root):

yarn occ package-app osf-payment-sse

yarn occ upload-app -u ${OCC_ADMIN_HOST} -k ${APPLICATION_KEY} osf-payment-sse

where

- APPLICATION_KEY - Application Key created in Settings -> Web APIs -> Registered Applications

- OCC_ADMIN_HOST - your OCC specific environment, e.g. asbx80c1dev-admin-{env}.oraclecloud.com

 

Install Payment Widget

Copy the contents from cyber source-plugins-oraclecxcommerce/plugins into the plugins directory of your storefront(OSF workspace) code. Copy plugins/actions into your storefront code and export the actions in the index and meta files:

plugins/actions/index.js

plugins/actions/meta.js

Copy plugins/components into your storefront code and export the components in the index and meta files:

plugins/components/index.js

plugins/components/meta.js

Copy plugins/endpoints into your storefront code and export the endpoints in the index and meta files:

plugins/endpoints/index.js

plugins/endpoints/meta.js

Copy plugins/selectors into your storefront code and export the selectors in the index file:

plugins/selectors/index.js

Copy plugins/fetchers into your storefront code and export the fetchers in the hook, index and meta files:

plugins/fetchers/hook.js

plugins/fetchers/index.js

plugins/fetchers/meta.js

Add widget to Checkout Layout

Go to the OCC admin design tab and replace the default checkout-continue-to-review-order- button component with the IsvCheckoutContinueToReviewOrderButton on the checkout- payment page

Go to the OCC admin design tab and replace the default checkout-place-order-button component with the IsvCheckoutPlaceOrderButton on the checkout-review-order page

Layout the IsvPaymentMethod component on the checkout payments container

Remove the CheckoutCreditCard component from the layout and replace it with IsvPaymentMethod

Publish the uploaded and configured widgets: OCC Admin -> Publishing -> Publish

Configure the Extension

Go to OCC Admin -> Settings -> Payment Processing and click on Payment Gateways

Selected Cyber source Official and enable

Enter your Cybersource Merchant ID and REST Key details

Choose supported Payment Methods and click save

Ready to Go Live

When you are ready to go live configure the cartridge using your production Cybersource account details. Please refer to this step for a reminder on where to do this.

Further Information

Need more guidance as you implement a Cybersource‑powered solution?
The Cybersource Developer Center offers resources to help merchants and system integrators build reliable, compliant, and well‑tested integrations.

• Explore Cybersource API documentation for payment processing, tokenization, refunds, and reporting to understand how each capability works within your ISV’s integration.
• Review SDK and code sample libraries to accelerate development and align with recommended implementation patterns.
• Access sandbox environment details to validate transaction flows, verify configuration, and complete end‑to‑end testing.
• Consult integration guides for information on authentication, security controls, risk services, and digital channel support.
• Use the Cybersource Support Center for troubleshooting articles, FAQs, and release updates relevant to your integration path.

These resources are designed to help you deploy and manage your ISV solution efficiently, ensuring a smooth payment experience for your customers.