Tutorial: Payment Settings Custom Extension

Wix Custom Extensions allow you to implement custom logic to change how your site behaves and displays using Velo SPIs. 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 custom extension allows you to implement your own payment settings using code. These settings will then apply during the payment process.

Custom extensions are implemented with Velo SPIs. You can manage extended services from your site's dashboard, and they behave just like the ones Wix already supports. Learn more about Custom App Extensions Using SPIs.

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

Introduction

This tutorial explains how to set up and implement a payment settings extension on your site using Velo. We created an example to demonstrate how you can use custom extensions 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 extension on your site.
2. Implement your extension with custom code.
3. Deploy the extension.

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 SPI 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 extension

The first step in setting up your new extension is to add it to your site. This process creates a new folder in the Custom Extensions 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.

1. Go to the Custom Extensions section:

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

2. Hover over Custom Extensions and click , then click Add Payment Settings SPI.

3. Follow the prompts to add the extension and accept any terms and conditions that display.

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

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

6. Publish your site.

Step 2: Implement the extension

The procedure in the previous section creates a folder in the Custom Extensions 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 extension we set up. This folder contains 2 default extension files:

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

We implement the custom code for your extension 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 extension'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 SPI call fails it will, by default, return paymentSettings.requires3dSecure set to true which tells the payment provider to require 3DS for the order.

1
import * as ecomPaymentSettings from 'interfaces-ecommerce-v1-payment-settings-provider';
2

3
export function getConfig() {
4
  return { fallbackValueForRequired3dSecure: true};
5
}

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 SPI 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:

1
import * as ecomPaymentSettings from 'interfaces-ecommerce-v1-payment-settings-provider';
2

3
export const getPaymentSettings = async (options, context) => {
4
    return {
5
        paymentSettings: {
6
            requires3dSecure: parseFloat(options.order.priceSummary.subtotal.amount) >= 50
7
        }
8
    };
9
};

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 extension

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

• Wix Editor:

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

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

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

1
import { functionName } from '.myFileName.js';

Optional: Test the extension (Wix Editor)

You can test your extension 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 extension after deploying, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the extension

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 an extension

You can remove an extension from your site.

Wix Editor:

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

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

Legal notices

If you connect to a 3rd-party provider using SPIs, 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.