Introduction

The purpose of this guide is to explain configuration scripts concept and how they can be used to simplify merchant onboarding process.

Intended Audience

This guide will be useful for the PSPs and software platforms that use the gateway onboard mechanism to onboard their merchants.

Overview

Merchants process transactions through the gateway using various software platforms that are integrated with the gateway. To start processing, merchants register within a software platform that onboards them in the gateway via the onboarding mechanism. During the onboarding process, general, processing and billing merchant settings are configured. For example, provider profiles for payment card and direct debit processing, tokenization settings and more are completed.
Merchants are configured depending on the logical group they belong to (e.g. merchants that process transactions through the same software platform and in the same country). A large number of such groups may lead to confusion due to the fact that it is hard to remember which settings are required to be configured for a particular merchant. To avoid that, various configuration scripts are used. These scripts are used during the onboarding process to configure the merchant according to its logical group. For example, a POS platform that works with merchants in different countries may need different configuration sets for each country.

Currently, the following scripts are supported within the system:

Processing configuration script – a script for configuration of provider profiles required for transaction processing.
Provider profile defaults script – a script for configuration of default settings associated with a particular provider profile.

Processing configuration script

A PSP works with various software platforms that bring merchants to the payment gateway. For transaction processing, merchants use configurations that meet the needs of a particular integration or logical group within the software platform. For example, there can be both configurations that allow real-time and batch processing and a configuration allowing real-time processing only. To save time while customizing merchants during the onboarding process, processing configuration scripts with typical configurations can be created beforehand. These scripts allow a PSP to configure provider profiles required for transaction processing. The profiles are configured using default data, specified within the pre-defined provider profile defaults scripts, and required settings (such as MID, TID, etc), received within a response of an onboarding request to a corresponding underlying processor. Therefore, using pre-defined processing configuration script, service provider profiles required for transaction processing can be configured automatically as a part of the onboarding process.

Processing configuration script can be assigned to a merchant in two ways:

via API – by specifying the name of a script via the processingConfigurationScript field of the create API call;
via the user interface – by specifying the name of a script via the Processing Configuration Script field of the Onboarding Application Wizard form on the Merchant perspective.

There can be situations when merchants of the same logical group have different needs. For example, some merchants can process real-time transactions only, while others process both real-time and direct debit transactions. For such cases, creating a new processing script for each merchant is inefficient, so the processing configuration scripts mechanism allows a PSP to disable the configuration of certain profiles configured within the script via a designated filter.
This filter works as follows:
1) For each type of profile, a certain letter value is used. All available values are listed below:

D - direct debit profile;
R - real-time profile;
B - batch profile;
T - tokenization profile;
E – email profile;
A - account updater profile;
E - American Express profile.

2) If during the onboarding process a particular letter is submitted along with the name of a script, a corresponding profile is configured when the merchant is successfully onboarded. For example, if a pre-defined script includes real-time and batch provider profiles, and letter R is submitted along with the script name via the processingConfigurationScript field, then in case of successful onboarding only a real-time provider profile will be configured for the merchant.
3) If no letters are specified along with the script name that is submitted, then all provider profiles initially included in the script are configured for the merchant in case of successful onboarding. For example, if a pre-defined script includes real-time and batch provider profiles and only the script name is submitted via the processingConfigurationScript field, then in case of successful onboarding both real-time and batch provider profiles will be configured for the merchant.

When the filter is used, the script name has to be preceded by one or more letters of the filter with an asterisk as a separator. For example:
processingConfigurationScript=script-name*DRBT where script-name is the name of the script and DRBT is a filter with provider profile types that are required to be configured.

Recommendations
To decide how many and which scripts are needed, such parameters as the logical group a merchant belongs to should be taken into a consideration. Logical groups are created based on the specific needs of these merchants, including their country, processor, associated software platform or client segment of the software platform.

Use Cases
In this section, we will review some of the typical scenarios and variations of processing configuration scripts.

1) A PSP works with two software platforms that deal with merchants from the US and Canada. For this reason, the first platform works with a US processor and the second one with a Canadian processor. However, both platforms perform tokenization through one tokenization appliance. Although the tokenization settings are the same for both platforms, the PSP has to create two separate processing configuration scripts: the first with processing profiles of the processor from the US and the second with processing profiles of the processor from Canada.
2) A PSP works with three software platforms. Through platform #1, which works with fitness clubs, merchants process real-time, direct debit and batch transactions using a particular processor. Through platform #2, which works with restaurants, merchants process only real-time transactions using the same processor as the platform #1. Through platform #3, which works with casinos, merchants also process only real-time transactions, but using a different processor.
For the merchants that process transactions under these software platforms, the PSP is recommended to create two configuration scripts: one with real-time, direct debit and batch provider profiles of the first processor, for example, processorA-name.ps, and the other with a real-time provider profile of the second processor, for example, processorB-name.ps. After being created, these scripts are used as follows: during merchant onboarding, platform #1 submits only the name of the first script (processorA-name.ps), platform #2 submits the name of the first script and a filter that allows configuration of the real-time provider profile only (processorA-name.ps*R), and platform #3 submits only the name of the second script (processorB-name.ps).

Processing Configuration Functions

During the onboarding process, a particular set of provider profiles required for further transaction processing is configured for a new merchant. Using the processing configuration script, you can control how this process is executed. The following functions are used to create processing configuration scripts in the gateway. There are four predefined functions that called on specific points in the application while it is being created. Their signature is indicated up in each of their headers. No parameters are passed.

Recommendations
Some provider profiles can be configured at the portfolio level. If merchants mostly use service provider settings configured for an associated portfolio -- for example, tokenization appliance settings -- then such provider profiles are not required to be configured at the merchant level and are not required to be included in the processing configuration script.

String[] getProfileList()

Called after an onboarding request is submitted to the gateway. See the diagram for more information.
Returns a list of provider profile names that can be configured for the merchant during the onboarding. During the merchant's onboarding, you can choose which profiles from this list are configured via the user interface (Onboarding Wizard form) or the API (the filter is described in the section above).

For example, if you need a configuration for real-time, batch, direct debit and chargeback processing via the Vantiv Lowell processor as well as the StrongAuth tokenization profile and the smtp email profile, the function should look as follows:

 
function getProfileList(){
    return ["ach/vantiv-lowell:US", "cards-batch/vantiv-lowell:US","cards-realtime/vantiv-lowell:US", 
            "tokenization/strongauth", "email/smtp"];
}

When a live merchant is configured, real-time, direct debit and tokenization profiles are selected most often.

void adjustData(data, filter)

Called when an onboarding request is prepared by the gateway to be subsequently submitted to a processor. See the diagram for more information.
Allows modification of data specific to a processor before sending an onboarding request to the processor. This function is called just before the onboarding information is sent to the processor.
Includes the following parameters:

data - OnboardingApplication object that stores detailed merchant information and allows to configure additional data within the provider profile.
filter - a mask that controls which of the available profiles are configured for the merchant as a result of successful onboarding request.

For example, if you want to enable AmexOptBlue option (setting that cannot be configured manually via the API) while configuring Vantiv Lowell provider profile, the function should look as follows:

 
function adjustData(data, filter){
    data.onboardingBusinessInfo.isAmexOptBlueAcquired = true;
}

where:

data.onboardingBusinessInfo.isAmexOptBlueAcquired = true; indicates that Amex OptBlue option is enabled.

void configureProfiles(data,identities, filter)

Called when the gateway received the onboarding response that was generated by a processor. See the diagram for more information.
Allows configuration of merchant provider profiles in case of a successful onboarding request.
Includes the following parameters:

data - OnboardingApplication object that stores detailed merchant information and allows to configure additional data within the provider profile.
identities - OnboardingResult object that stores all values received from a processor that are required for profiles creation (e.g. MIDs). Depending on the processor, up to four values can be received (identity0, identity1, identity2 and identity3). For most processors, only identity1 is received, which is the MID of a merchant in a processor's system. In identity3 an ID of the terminal in the processor's system is usually returned.
filter - a mask that controls which of the available profiles are configured for a merchant as a result of a successful onboarding request.

For this function, you must include all the profiles specified in getProfileList(), as well as the corresponding filters that allow the system to recognize which of the profiles should be configured for a merchant.
For example, if you want to create a real-time profile for the Vantiv Lowell processor that includes a MID received as a result of the onboarding request, the function should look as follows:

 
function configureProfiles(data,identities, filter){
    var merchantId = identities.processorIdentity1;
 
    if (api.contains(filter,'D')){
      var profile= api.create("ach/vantiv-lowell:US"); 
      profile.merchantId = merchantId;
      api.save(profile);
    }
 
    if (api.contains(filter,'R')){
      var profile = api.create("cards-realtime/vantiv-lowell:US"); 
      profile.merchantId = merchantId;
      api.save(profile);
    }
 
   if (api.contains(filter,'B')){
      var profile = api.create("cards-batch/vantiv-lowell:US"); 
      profile.merchantId = merchantId;
      api.save(profile);
    }
 
    if (api.contains(filter,'C')){
      var profile = api.create("chargeback/vantiv-lowell:US"); 
      profile.merchantId = merchantId;
      api.save(profile);
    }
 
    if (api.contains(filter,'T')) api.createAndSave("tokenization/strongauth"); 
 
    if (api.contains(filter,'E')) api.createAndSave("email/smtp");
 
}

Library Functions

The library functions - api function - reference on the api object, which is predetermined in advance.

Configuration scripts consist of a set of library functions. Each of the library functions works as a hook. These hooks are invoked by the core logic in the process of merchant onboarding to customize their provider profiles. When creating a script, any standard JavaScript function of ECMAScript 5.1 can be used.
Additionally, for scripts creation, auxiliary functions of the internal API written specifically to simplify the implementation of configuration scripts are used. Access to the API is granted through a global variable api which can be called via any function. The following functions are available via the api variable:

Boolean contains(String value, char key)
Verifies the presence of the key symbol in the value string. Most often used to verify whether a particular character is present in the filter. Returns true if the value has been found, otherwise false.
ProviderProfile create(String defaultScriptName)
Creates a provider profile based on a script named defaultScriptName. Used when it is necessary to customize a profile before saving it to the database. Returns the newly-created profile. Note: the profile returned by the function is not saved automatically in the database. To save it, save() function must be called.
void save(Object object)
Saves the object providerProfile in the database.
void createAndSave(String defaultScriptName)
Creates a provider profile based on a script named defaultScriptName and saves this profile to the database. Used when it is necessary to create a profile based on the default data (for example, tokenization and email profiles).
void createFtpFolders()
Creates FTP folders for batch processing (uploading and downloading files via FTP) when configuring batch provider profiles for a merchant. Merchant's FTP folder is created under the folder of either a portfolio or reseller associated with the merchant that is being oboarded. Along with the FTP folder, the following sub-folders are created: inbox (required) - a folder for uploading files to be processed; outbox (required) - a folder that contains processing results; invault - a folder for uploading files for tokenization prior to processing; data - a folder for data export files exchange. See integration notes for more information.
String truncate(String value, int length)
Truncate a String to the given length with no warnings value - String to be truncated length - Maximum string length

Each integration includes its own set of library functions and their program implementation.

Provider profile defaults script

Payment platform integrates with various processors and banks through the payment gateway. To process transactions through them, a provider profile with corresponding settings should be created for each merchant. Some of the provider settings, such as connectivity parameters, are the same for all merchants associated with one payment platform. To avoid configuring these settings manually for each merchant, the provider profile defaults script is used. This script contains pre-defined configurations with default provider profile settings that are used while onboarding new merchants.

In most cases, default provider profile settings are the values that a processor/service provider assigns to the gateway as a payment platform. Among these settings are connection URLs, usernames, passwords and identifiers of the gateway as a third-party processor (TPP). These values are set at a portfolio level via the Profiles form under the Configurations button. Specified values will be used automatically in provider profiles assigned to the merchant after successful onboarding via the gateway.

Recommendations
The rule of thumb: if a setting value changes from merchant to merchant, it cannot be configured in the defaults. For example, a merchant ID or username should not be specified in the script when these values are specific for a particular merchant.

Use Cases
A PSP works with merchants from the USA and Canada that process transactions through different service providers. For each service provider associated with one country, the values of such provider profile defaults as username, password, host and port for connectivity are the same for all merchants that process transactions through them. However, a service provider profile has to be configured differently for processing in other countries. For this reason, the default settings of a service provider have to be configured manually for each country while onboarding a new merchant.
To avoid that, the PSP creates individual provider profile defaults scripts for processing in the USA and Canada. When a new merchant is onboarded, the user will select one of the pre-defined scripts on the user interface or via API.

If a provider processes requests in several countries, then you need to create one profile for each country. The suffix field is added at the end of the profile name, through the divider ":" It is recommended to set the two-digit country symbol in the suffix field to distinguish between profiles of the same provider. For example, if the profile is used for USA and Canada, then the names will be cards-batch/vantiv-lowell:US and cards-batch/vantiv-lowell:CA, respectively. Please note that in scripts you need to use the full name of the profile, taking into account the suffix.

Provider Profile Defaults Functions

The default provider profile settings are filled out in the form on the user interface -- on the defaults tab of the Profiles form (Portfolio perspective -> Configuration button -> Profiles). This form is an exact copy of the standard provider profile form and allows for entering all required values of the provider profile. These values are used as constants when creating the profiles during the onboarding process. To change the constant value of the profile before sending the onboarding request to the processor, the create() function is used.

void create (ProviderProfile profile)

Allows for making changes to the provider profile settings after all constant values have been assigned.
For example, if an inactive provider profile has to be created, or it is necessary to create a non-standard path to an FTP folder with the response files from a processor the function should look as follows:

 
create(){
    profile.isActive = false;
    profile.responsePath = profile.userName+"/in";
}

In this example, the profile parameter is used to access all values within the profile, where:

profile.isActive = false; means that the profile is created in the inactive state;
profile.response = profile.userName+"/in"; means that a path to an FTP folder is created based on a username that is used in the processor's system.

Guide Contents

Configuration Scripts Management Guide v1.1