Tutorial: Payment Settings Service Plugin

Wix service plugins (formerly SPIs and custom extensions) allow you to implement custom logic to change how your site behaves and displays. For example, when you set up a Wix eCommerce site there are a number of settings that apply by default during the payment process. The payment settings service plugin allows you to implement your own payment settings using code. These settings will then apply during the payment process.

With the Payment Settings service plugin you can apply custom payment settings, such as requiring an additional layer of security, to an order during the payment process.

Learn more about on how to implement a service plugin.

Introduction

This tutorial explains how to set up and implement a payment settings service plugin on your site using Velo. We created an example to demonstrate how you can use plugins to apply 3-Domain Security(3DS) when the price of the order is greater than or equal to $50.

The process has 3 steps:

1. Create a new payment settings service plugin on your site.
2. Implement your service plugin with custom code.
3. Deploy the plugin.

Before you begin

To collect payments, a Wix site must connect a payment provider. Once a payment provider is connected you may use the Payment Settings service plugin to enforce additional payment settings to your site's transactions. For example, a site may require additional 3d secure payments (3DS) for certain orders. Note that each payment provider may have specific payment settings they accept with their Wix integration. For example, Tranzila is a payment provider that supports 3DS payments, but not all payment providers offer this feature. We recommend contacting payment providers directly to confirm which payment settings they have implemented as part of their Wix integration.

Currently, the only payment setting available to customize is whether to apply 3DS to an order. If 3DS is required, the customer will have to pass an additional layer of security before completing their payment. For example, they will have to pass a window like this before continuing:

Step 1: Create a new payment settings service plugin

The first step in setting up your new service plugin is to add it to your site. This process creates a new folder in the Service Plugins section of the Velo Sidebar (Wix Editor), or the /src/backend/spi section of the Wix IDE Explorer (Wix Studio), which contains the files for your code.

1. If necessary, add the Wix Stores app to your site.
2. Enable coding:

• Wix Studio: If necessary, in the Code sidebar, click {} and then Start Coding.
• Wix Editor: Enable Velo Dev Mode, and then click the Public & Backend {} tab in the Velo Sidebar.

3. Go to the Service Plugins section:

   • Wix Editor: Scroll down to the Service Plugins panel at the bottom of the sidebar.
   • Wix Studio: Click Packages & Apps.

4. Hover over Service Plugins and click , then click Payment Settings.

5. Follow the prompts to add the plugin and accept any terms and conditions that display.

6. Enter a name for your service plugin and click Add & Edit Code. The name can't contain spaces or special characters. In our example, we named ours require-3ds-50.

7. Wix Studio: Open the Wix IDE, and go to /src/backend/spi/<your-app-plugin-folder>. If your service plugin doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

8. Publish your site.

Step 2: Implement the service plugin

The procedure in the previous section creates a folder in the Service Plugins section of the Velo Sidebar (Wix Editor), or in the Wix IDE's Explorer (Wix Studio), called ecom-payment-settings. Inside this is another folder with the name of the plugin we set up. This folder contains 2 default service plugin plugin files:

• <my-plugin-name>-config.js: The code in this file defines a function that returns an object containing values used to configure your plugin.
• <my-plugin-name>.js: The code in this file defines a function specific to the service plugin, such as getPaymentSettings(). The function is called by Wix to retrieve the data provided by your plugin.

We implement the custom code for your service plugin in these files. In our example, the folder looks like this (Wix Editor):

require-3ds-50-config.js

This file is where we write the code for setting up the plugin's configuration.

The code in this file defines a function named getConfig() that returns an object containing a default configuration for our payment settings. In our example, we set fallbackValueForRequired3dSecure to true so if the call fails it will, by default, return paymentSettings.requires3dSecure set to true which tells the payment provider to require 3DS for the order.

require-3ds-50.js

This file is where we write the code to require 3DS to an order during payment if the price of the order is $50 or greater.

The code in this file defines a function named getPaymentSettings(). This function is called by Wix eCommerce during the payment process to retrieve the specific payment settings to apply to an order. The function accepts the following parameter:

options: An object containing information about the order. For details on what's included in the order, see the service plugin reference.

The getPaymentSettings() function returns a paymentSettings object containing the payment settings to apply to the order. Currently, the only setting included is requires3dSecure.

The code:

Line 1-3: First we import the eCom payment settings module. Then we export the getPaymentSettings() function where we set the custom logic to apply to the order.

Line 6: We extract the subtotal price from the order (options.order.priceSummary.subtotal.amount) and apply parseFloat to convert the string into a floating-point number. We then check if that number is equal or greater than 50. If so, requires3dSecure is set to true, meaning that 3DS is required for this order.

If this logic fails, for example if somehow the amount isn't a number, then requires3dSecure will be set to the value set for fallbackValueForRequires3DSecure in the config.js file.

Optional: Add files to the service plugin

If you don't want to keep all of your code in the main service plugin files, you can add files to the plugin's folder and import functions and objects into the main files.

• Wix Editor:

  • Hover over the service plugin folder's name and click Show More .
  • Select New.js.

• Wix Studio: Create a new file in the plugin's folder in the Wix IDE Explorer.

To import from these files to the main files, use the following syntax:

Optional: Test the service plugin (Wix Editor)

You can test your plugin before publishing your site using functional testing in the Wix Editor like you would with any backend Velo code. Make sure your getPaymentSettings() function's return values are properly formatted. Note that functional testing is not currently supported in Wix Studio.

To test your plugin after deploying, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the plugin

Once your code files are ready, publish your site. Navigate to your site and place an order. If the order is $50 or greater then 3DS should be required to complete the payment process.

Example

We built a sample site where you can see this code in action.

Remove a plugin

You can remove an plugin from your site.

Wix Editor:

1. In the Public & Backend section of the Velo Sidebar, under Service Plugins, hover over the plugin's folder and click Show More .
2. Select Delete.
3. Click Delete.

Wix Studio: Right click on the plugin's folder and select Delete Permanently.

Legal notices

If you connect to a 3rd-party provider using service plugins, you agree to the Wix.com Terms of Use. Wix is not responsible for your use of such a 3rd-party provider, and any liability resulting from such use will be your responsibility.