1. Developing Open Storefront Framework Applications for Oracle Commerce
  2. Build Payment Integrations
  3. Understand payment integrations

Understand payment integrations

You can use tools that Commerce provides to create custom integrations with payment gateways.

Oracle Commerce provides a framework for building custom integrations with payment gateways. The framework supports integrating with a variety of different payment types, including:

  • credit cards
  • gift cards
  • invoices and purchase orders
  • cash
  • store credit
  • loyalty points

A key aspect of these integrations is the use of payment webhooks. When a shopper places an order, the POST /ccstore/v1/orders/current/submit endpoint triggers a call by a webhook. The webhook sends a request to a specified URL and includes the payment-related data it received from the endpoint. The target system processes the payment data and then sends a response that indicates success or failure and other information about the transaction.

Except for loyalty points, the payment types listed above are all supported through the Generic Payment webhook. Loyalty point payments are supported through the Custom Currency webhook.

In addition to supporting integrations that can handle one or more of these payment types directly, the Generic Payment webhook can also be used for implementations in which Commerce delegates the payment handling to an external web payment system such as Amazon Payments and PayPal.

Creating a custom payment integration involves a number of steps. These include:

  • Creating a gateway extension to configure access to the gateway. The extension defines configuration options that merchants can set on the Payment Gateways tab of the Payment Processing page in the administration interface.
  • Developing storefront checkout pages that work with the integration. You may need to customize your payment widgets to supply specific information to the payment or order endpoints.
  • Configuring the Generic Payment webhook to send payment data to the gateway.

Depending on the gateway and payment providers, there may be additional steps involved in creating an integration. You need to configure settings on the gateway itself, and if your integration handles credit cards, you must ensure it is PCI-compliant. Also, you will typically need to create a custom payment integration service for routing transaction data from the Generic Payment webhook to the gateway and mapping the webhook data properties to fields used by the gateway.

One way to create a payment integration service is to write a server-side extension (SSE) that functions as a translation and routing layer. For example, the sample Worldpay integration available on the Cloud Customer Connect site is designed to work like this:

  1. When a shopper or agent submits or modifies an order, a payment transaction is initiated (an authorization, void, or refund, depending on what the shopper or agent is trying to do).
  2. The Generic Payment webhook sends a POST request to a REST endpoint that a server-side extension implements.
  3. The server-side extension’s JavaScript code transforms the JSON from the Generic Payment webhook into the XML format that Worldpay supports, and sends it to Worldpay.
  4. Worldpay processes the transaction, and sends an XML response to the server-side extension.
  5. The server-side extension’s JavaScript code transforms the XML response to the JSON format that Commerce supports, and sends the JSON to the Commerce server as the Generic Payment webhook response.
  6. The Commerce server returns the results of the transaction to the storefront.