Payment Extensibility

Payment Extensibility is a feature that allows you to add new gateways to use in a tenant by creating an application in the Kibo Dev Center, configuring that application as a gateway adapter, and then installing that application in your tenant.

If you want to create your own tax integration (such as if you want to use a tax service other than Avalara), you can use an API Extension or an application capability. Reach out to your SI partner or to Kibo's professional services and enablement team if you need assistance with this or with the extensibility application installation.

Uses

Add Your Preferred Payment Gateway Through Kibo Dev Center

You want to use a payment gateway that is not currently supported. You create an app in the Kibo Dev Center, configure it as a payment gateway, and install that app to your tenant. Note that multiple instances of a gateway on the same site can be set up with different credentials.

Enable Third-Party Payments and Digital Wallets

Note that both third-party gateways (e.g., PayPal and Pay With Amazon) and digital wallets (e.g., Apple Pay and Visa Checkout) are extensible, but have important distinctions. Digital wallets store card information that they send to an external gateway for processing. Third-party gateways can function as a wallet but can also process the payment details themselves. For instance, PayPal can store card information and either process a payment or send it to Cybersource. These configurations can be tied together in the Payment Types settings menu.

Set Up a Payment Gateway Connector

It is recommended to contact your Kibo enablement team to discuss your gateway needs before starting to create a new gateway. You will follow the below process:

Create an app in the Kibo Dev Center
Configure your app as a gateway adapter
Test the adapter
Submit your app for certification
Install your gateway adapter app
Enable the gateway in your tenant

Create an App in the Kibo Dev Center

You will need to create an app in the Kibo Dev Center to complete this process, which includes implementing custom endpoints that can be called from your storefront theme.

For detailed instructions on forking the template and setting up the app, see the Payment Extensibility Starter Kit. Kibo can assist you and provide more information as needed.

Configure Your App as a Gateway Adapter

For further information on how to configure an Apple Pay gateway, see the Apple Pay Configuration guide.

To configure your existing application as a payment gateway adapter:

In the Kibo Dev Center, under the Developer Accounts list, select your developer account.
Select Develop > Applications.
Enter your application's name in the search bar.
Under the Actions column for your app, select the settings icon.
Select Edit.
On the left hand side, select Packages > Capabilities.
Select Add Capability.
Select Payment Gateway Adapter from the drop down menu.
Select Ok. This displays the Configure Payment Gateway Adapter screen.
If you are creating a payment gateway that processes gift cards, you must add the supportsGiftcard and schemaVersion fields to your gateway configuration after the administrationUi section as in the following example:
```
"administrationUi": [
//administration UI configs
],
"supportsGiftcard" : true,
"schemaVersion" : "1.0"
}
```
The supportsGiftcard field must be set to true, and the schemaVersion field must be set to 1.0.
On the Configure Payment Gateway Adapter screen, enter your Payment Gateway endpoint URL.
This field is used for payment gateway testing only. It indicates the endpoint for the payment gateway processor.
In the Gateway Configuration field, a template is displayed for you to enter configurations for your payment gateway in JSON format.
Depending on what kind on payments your connector can process, you need to set the following configuration.
- Set paymentType field (supportedCards.paymentType) to one of the below values based on payment type.
  - CreditCards – "CC'
  - DigitalWallets – "DW"
  - ThirdPartyPayments – "3P"
- Also populate the features collection with at least one of the valid values from below:
  - "CreditCards"
  - "DigitalWallets"
  - "ThirdPartyPayments"
  - Here's an example:
```
"features":[
  "CreditCards",
  "DigitalWallets"
],      
```
- When setting administration UI fields for connector, use the xtypefield to configure the type of field you want to display in the admin.
  - "textfield"
  - "password"
  - "dropdown"
  - "radio"
  - "email"
  - "date"
  - "checkbox"
  - "number"
Select the countries whose payments you want this payment gateway to process.

Test the Adapter

When complete, give the Kibo team access to your repo with the new gateway. Kibo will then set up a hosted development version of the gateway for you to test and sign off on.

Submit Your App for Certification

If you are deploying this app to a production tenant, it must be certified. Certification ensures that your payment gateway app is PCI compliant, secure, and that it does not retain or leak any PCI data.

Once you have tested the adapter, provide Kibo with the Application ID and Development account of the gateway application. Kibo Engineering will review the adapter and perform a PCI audit. This process usually takes about four weeks.

Although the Dev Center includes a submission button at More > Submit for Certification, you do NOT have to perform this action if you have worked with Kibo enablement to set up and test the adapter.

Install Your Gateway Adapter App

When certified, the application can be installed on a production tenant. To install a gateway adapter from Dev Center:

In the Dev Center Console, select Develop > Applications.
Search for your Application.
Under the Actions column, select the settings icon.
Select Edit.
Select Install.
Select your sandbox from the list.
Select OK.

Enable the Gateway in Your Tenant

Once you've successfully created and installed your payment gateway adapter in your tenant, you need to enable that payment gateway in your tenant's admin UI.

To enable your payment gateway:

In the Admin UI, go to System > Settings > Payment Gateways.
Select Create New Payment Gateway.
In the Payment Gateway drop-down menu, select your app to enable it as a payment gateway.

Recall that gateways are always implemented on the tenant level. If there are multiple sites that need to use the same gateway, it must be set up for each site individually.

The Create Payment Gateway page with Apple Pay being configured

Edit an Existing Gateway

Once a gateway has been created, you can always go back and edit it by clicking on it in the Payment Gateways menu.

Configure Payment Types for Gateways

Go to the Payment Types settings menu of the site to configure payments types and processes relevant to the new gateways, particularly for third-party payments and gift cards. This is where "third party accounts" and "processing gateways" are defined, with the former being where the card information comes from and the latter being the service processing the payment. The processing gateway may be an optional field, depending on whether the account is acting as digital wallet or third party payment.

If you are using Kount or Decision Manager for fraud management, then an update to the fraud cartridge will be required so that it can recognize the new payment type. This update must be performed by Kibo. Submit a Kibo Support ticket with information about the payment type whenever you implement a new third party gateway that will send payments to Kount or Decision Manager.

This is also where you can specify when to capture the payment: on either order placement or shipment.

The Third Party Payments page with Apple Pay and Pay With Amazon selected

Once configured, these payment options will display to customers as an option for checkout:

Example of payment option buttons on the storefront cart

View enabled gift cards and specify when they should be redeemed further down the page.

Close-up of the Gift Cards section in the payment configurations

For more information about setting payment types, see the Payment Types guide.

How to Process Payments

Users can process payments using the Kibo interface, though OMS-only implementations may not have the full suite of payment functionality as eCommerce such as managing customer store credit. For information on payment processing:

For instructions on processing payments using the Admin UI, refer to the Payment Processing guide.
For instructions on processing gift card payments, refer to the Gift Card Processing guide.
For information about the statuses that payments go through and the actions that can be performed on them, refer to the Payment States guide.