Payment Extensibility Starter Kit

This guide explains the development setup needed to create a new payment gateway to implement through payment extensibility.

Dev Center Setup

Create a Dev Center Application

An application must be created first to access eCommerce environments.

  1. Log in to Dev Center.
  2. Click Develop > Applications.
  3. Click Create Application.
  4. In the Create application dialogue box, do the following:
    1. In the Name text box, enter a user-friendly name for the application, such as GatewayName Connector.
    2. In the Application ID text box, enter an ID for the application, such as gatewayName_connector.
  5. Kibo eCommerce appends the Application ID to the reverse domain name for your Dev Account. The allowed characters include numbers, letters, and underscore.
  6. Click Save.

Prepare an Endpoint

An endpoint must also be created to integrate with the application.

  1. Prepare a web server that will host your payment gateway application.

  2. Note the URL endpoint of the payment gateway application’s configuration page, such as https://<Domain>/<gatewayNameApp>/configure.

  3. In Dev Center, open the application details page for your payment gateway application.

  4. Click Packages, and then click the Details tab.

  5. Under Configuration URL, add the URL endpoint of the payment gateway application’s configuration page.

Install the Application to a Sandbox

Installing the Dev Center application to a sandbox allows to you properly test configuring the application in a Kibo eCommerce tenant.

  1. In the Application editor, click Install.

  2. Select your application and click OK.

Build the Starter Kit

Kibo eCommerce provides the starter kit as a starting point for a custom integration; therefore, you will need to download the source code, modify it as necessary, and then build and host it on your own web server.

Obtain the source code

Before you can build the starter kit, you'll need to obtain the source code:

  1. Go to https://github.com/Mozu/KiboPaymentAdapterTemplates.
  2. Clone the repository on your local computer.

The starter kit is built on Java. Kibo eCommerce recommends modifying the starter kit source code to suit your purposes using a Java-based IDE, such as the Eclipse IDE for Java Developers.

Gradle Build

Once you have the Kibo eCommerce configuration file configured properly, you can then build the starter kit using Gradle. If you already have Gradle installed on your system you can build the application using the gradle build; however, Kibo eCommerce recommends using the included Gradle Wrapper (gradlew), because it ensures that the correct Gradle version is used to run the install task. Refer to Chapter 5. The Gradle Wrapper in the Gradle documentation for more information about the Gradle Wrapper.

To build the starter kit using the Gradle Wrapper:

  1. From the root folder, run gradlew build. If you don't already have Gradle installed on your system, the Gradle Wrapper automatically installs the correct Gradle version for the starter kit.
  2. Use the WAR file located at: root/build/libs in the following steps.

The included Gradle Wrapper also includes other Gradle tasks that you might find useful. For a complete list of all Gradle tasks, run gradlew tasks.

Deploy WAR File

The Gradle Wrapper builds a WAR file that you can then deploy on your own Java web server. Kibo eCommerce recommends using an Apache Tomcat web server to deploy the WAR file.

This WAR file is located at: root/build/libs.

Refer to the documentation for your selected web server for more information about configuring the web server and deploying the WAR file.

Once you've successfully deployed the WAR file to your web server, you can use the appropriate URLs in the Dev Center Setup section.

Other Configurations

Map eCommerce success/failure codes

The following table describes the success/failure codes for eCommerce:

Code Meaning
Success
  • Returned when eCommerce successfully processes a valid request.

  • Note: Your payment gateway may have multiple success codes that will need to be mapped to eCommerce.

Timeout

Returned when a request times out before eCommerce finishes processing it.

Reject
  • Sent when a valid transaction is processed but gets rejected.

  • For example, when eCommerce successfully processes a credit card payment, but the credit card has insufficient funds to cover the payment.

Unauth Returned when your request does not have valid authorization credentials.
Error Returned if you submit an invalid request to eCommerce.
NotFound Returned when eCommerce cannot find the gateway.

Configure Additional Endpoints

API Endpoint Description
/authorize
  • Accepts GatewayAuthorizationRequest.json and returns GatewayAuthorizeResponse.json.

/authorizeandcapture Accepts CaptureRequest.json and returns GatewayCaptureResponse.json.
/capture Accepts CaptureRequest.json and returns GatewayCaptureResponse.json.
/credit Accepts CaptureRequest.json and returns GatewayCreditResponse.json.
/void Accepts CaptureRequest.json and returns GatewayVoidResponse.json.
/getbalance Retrieves the balance available for the gift card.