Home > Guides

Guide Contents

Onboarding Management Guide v1.3

Added on:  09/21/18     Updated on:  03/21/24
Table of Contents

Introduction


The purpose of this guide is to explain how to use the onboard merchants using the functionality of the gateway's onboarding application.

Intended Audience


This guide will be useful for employees who manage the configuration of onboarding and creation of the merchants in the gateway.

Overview


To start transaction processing, a merchant is required to go through the process of verification/underwriting to obtain a Merchant ID (MID) from a processor through which transactions will be processed. This process is called onboarding. There are three models according to which the processor can organize its Payment Facilitator program:
  • single MID - all sub-merchants get associated with one MID that is obtained as a result of the merchant's onboarding application submission;
  • multiple MID - all sub-merchants get associated with different MIDs that are obtained as a result of the merchant's onboarding application submission;
  • MID pre-allocation - the PSP obtains multiple MIDs at a time and can allocate them among sub-merchants at its own discretion.

Traditionally, onboarding was performed manually on the processor's side. An onboarding application was submitted manually by the merchant (by email, fax, etc.), and further underwriting and MID assignment took a long time. Thus, there was a delay in transaction processing for the merchant. The gateway allows to perform merchant onboarding automatically so that the time period of underwriting and MID assignment is considerably shorter and the merchant can start transaction processing much faster. This can be done via the onboarding application. With the onboarding application, the merchant can be onboarded both via API through the onboarding pages and the user interfaces via the Onboarding Wizard form.

The onboarding process in the gateway includes the following steps:
  1. Onboarding configuration
  2. Merchant's onboarding information submission via the user interface or API
  3. Merchant's verification for scenarios when single MID and MID pre-allocation programs are used
  4. Onboarding result obtaining (documentation is coming soon)

Onboarding Configuration


To onboard merchants through the gateway, make sure that the following components are configured: onboarding profiles, agreements, pricing templates, configuration scripts.

Onboarding Profile (required setting)


The first step required for merchant onboarding to be performed through the gateway is an integration/certification with a processor, through which merchants are going to be onboarded. After this is done, it is necessary to create an endpoint within the system that will contain parameters to connect to the processor and submit data to it. This endpoint is called an onboarding profile.

Onboarding profile - a set of configurations required to connect to a processor used for merchant onboarding. This profile is set at a portfolio’s level. If the gateway has several portfolios for different businesses and countries, it is possible to create several onboarding profiles for different portfolios. If merchants operate through a reseller present as a separate entity in the gateway, it is possible to set one of the available onboarding profiles for the reseller.




Every profile has an identifier - ID. The ID is shown as an encrypted and decrypted value. Both values are available on the user interface, but the encrypted one is used only in API. This is necessary to avoid listing the IDs when submitting an API call.

When onboarding a merchant, it is important that the country code specified in business.countryCode field coincides with the Country field in the corresponding Onboarding Provisioning Profile of the merchant's portfolio. Otherwise, the following error is displayed: V25.




During the merchant onboarding process, your system has to inform the processor of how you are going to handle remittance - through the processor or the gateway. For this purpose, the Remittance Enabled flag is present in the onboarding profile.

Use the Remittance Enabled flag as follows:

  1. Enable this flag if you are going to do remittance through the gateway. If enabled, a merchant will have merchant fees configured during the onboarding process (under the condition of an available pricing template). When a 3rd party service is used for underwriting and remittance is done through the gateway, funds transfer will be deactivated until the merchant successfully completes the underwriting process.
  2. Disable this flag if you are going to do remittance through a processor. If disabled, a merchant will not have merchant fees configured during the onboarding process even if a pricing template is available.

UniPay Cloud

General Information


If you process transactions via the UniPay Cloud integration, make sure you have familiarized yourself with the following terminology:

Base server - main UniPay server used for transaction processing. This server connects to a processor through a configured provider profile and submits transactions received from a satellite server to the processor.

Satellite server - UniPay server that submits transactions to a base server through the UniPay Cloud integration for subsequent submission to the processor that the base server is integrated with.

Use case

PSP A and PSP B process transactions via UniPay. PSP B is certified for transaction processing through processor Z. To skip the certification process with processor Z, PSP A uses the UniPay Cloud integration with PSP B, and processes transactions through processor Z, but on behalf of PSP B.

Cloud code - an alphabetic value used to identify the merchants created on a base server through a satellite server. This identifier is set at the system level and gets transmitted to the base server.



Code - an alphabetic and numerical value used to identify merchants created on a base server through a satellite server. This identifier is assigned to all merchants on the base server. The code has the following format: [cloud code][satellite’s merchant ID].

Use case

PSP A is a satellite of PSP B. The server of PSP A has a cloud code F. In its system, PSP A creates a merchant, which is going to process transactions through UniPay Cloud. This merchant is automatically assigned with an ID 2000. Simultaneously, the merchant is created in the system of PSP B. This merchant is automatically assigned with an ID 5000 and a code F2000. Thus, the merchant doesn’t have to remember and use the ID from the external system. It can submit transactions using the ID that it has received from its software platform during the onboarding process.

UniPay Cloud Onboarding Profile


A set of the fields within the UniPay Cloud onboarding profile differs from the profile of other providers as it includes certain identifiers used to connect a base and satellite servers. All IDs present in the UniPay Cloud profile are taken from the base server. These IDs are the following:

  • merchant ID - ID of a merchant that is going to be used for transaction processing on a base server. This ID is used only when creating accounts. If it is not indicated in the profile, the merchant ID value is taken from an API request, when submitted.
  • reseller ID - ID of a reseller that is going to be used for transaction processing on a base server. If it is not indicated in the profile, when submitted via the API, the reseller ID value is computed using the general rules of the IDs submission in the onboarding API.
  • portfolio ID - ID of a portfolio that is going to be used for transaction processing on a base server. If it is not indicated in the profile, when submitted via the API, the portfolio ID value is computed using the general rules of the IDs submission in the onboarding API.
  • pricing template ID - ID of a pricing template on a base server, which is used for configuration of the fees for the merchants on a satellite server. If it is not indicated in the profile, the pricing template ID value is taken from an API request, when submitted.

Agreements (required setting)



After a merchant has filled out the onboarding information, it has to learn and confirm the mutual obligations established by the PSP. All terms and conditions are listed in an agreement.

Agreement - a document that consists of the conditions for use of the gateway that an onboarded merchant must comply with.

The mechanism of the configuration and use of the agreements is as follows:

1. You can create an agreement at both the portfolio and reseller levels. If the agreement is created at the portfolio level, it is available for all merchants under this portfolio. If the agreement is created at the reseller level, it overrides the agreement of the portfolio and is available for all merchants under this reseller.




2. You can create up to 999 agreements, but only one can be used for merchant onboarding.
3. When creating an agreement, you can set an effective date when it will take effect. The agreement can only be modified before this date.



4. Starting with an effective date, an agreement is marked as used. After that, the agreement can’t be modified or deleted.
5. After a merchant is onboarded, you can review an agreement associated with its onboarding application on the user interface.



Pricing Templates (optional setting)



If a PSP is also a payment facilitator, it does remittance by itself via the gateway. This means that during the onboarding process, a merchant needs to configure settings required for funds transfer. One of these settings are merchant fees. As a rule, an agreement on the amount of fees collected by the payment facilitator is the same for a group of merchants. For this reason, it makes little sense to set up fees for every merchant separately. The usage of templates is more convenient.

Pricing template - a set of identical fee settings for merchants that are onboarded or created in the gateway.

The mechanism for the configuration and use of the pricing templates is as follows:

1. A template is created at the portfolio level. You can create up to 99 templates.


Note that when a pricing template is created, it gets a unique sequence number (template code) of the following structure: XXXnn, where XXX is a Portfolio code, and nn is a sequence number of the template. For example, the pricing template codes for Portolio 901 will be in the range between 90101 and 90199.

2. A template is assigned to the merchant during the process of onboarding or creation.
3. The process of a template configuration is identical to the process of a fees configuration. The difference is that you can assign a template code from an integrated system.



4. In the API request for merchant onboarding, you can submit both an ID and a code for a template. If you submit the ID, use the encrypted value to avoid the listing of the ID’s.



5. If multiple pricing templates are configured for a portfolio, but no identifier is specified in the onboarding API request, the merchant onboarding will not go through.
6. See the Remittance guide for more information.


Configuration Scripts (optional setting)


During the onboarding process, the gateway not only receives the merchant’s identities from a processor but also configures it in the system. A merchant’s configuration can be performed both manually and automatically via the configuration scripts.

Configuration scripts - a set of scripts for the configuration of the provider profiles used for transaction processing by a merchant with the identities of a processor.

Currently, the following scripts are supported within the system:
  • Provider profile defaults script – a script for the configuration of default settings associated with a particular provider profile.
  • Processing configuration script – a script for the configuration of provider profiles required for transaction processing.

Review this guide to learn more about the configuration scripts.


Onboarding Information Submission


Skills

Be sure that you have familiarized yourself with the following concepts:

When having merchants onboarded through the gateway, the information is submitted in one of two ways - via the user interface, or the API. In both cases, the onboarding application is used.

Onboarding application – a set of the UI/API onboarding pages used for passing information about a merchant to a processor for onboarding in the processor’s system. During the onboarding process, information about the merchant, its owners, and the business is passed. Simultaneously with the merchant’s onboarding on the processor’s side, a merchant record with the corresponding settings is created in the gateway. Once the processor's approval is received, the merchant is ready to process transactions and have the money deposited to its account as a result of remittance.

Onboarding pages - forms used for entering information about a merchant for subsequent onboarding through the onboarding application via the user interface or API. Below, you can find a description of the pages and associated sections with the names on the UI and API, separated by a slash (/) symbol if the names are not the same. Note that the set of the onboarding pages and associated sections may differ for merchants, accounts, and affiliates. For this reason, we introduced the following abbreviations to mark the availability of the pages/sections for these entities:

  • M - means that a page/section is available for a merchant.
  • A - means that a page/section is available for an account. In most cases, the information that has to be provided during the onboarding process of the account is affected by the settings of the merchant’s profile.
  • F - means that a page/section is available for an affiliate.

Profiles (M, A)


The process of a merchant’s onboarding starts with assigning a portfolio and provider profile under which the merchant is going to be onboarded. The number of the portfolios and provider profiles available to a user is controlled by the data access policy. The policy implies that the user sees only those portfolios and associated profiles, that they have been granted access to. All profiles in the list come with an encrypted profile ID.

General Information


This page is available only on the user interface. It contains the technical information about a merchant for its configuring in the gateway.

Detail (M, A, F)


After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:
  • tax ID is populated in the business information of the merchant (Merchant perspective => Details => Underwriting => Business).
  • ID and Code are populated in the general details of the merchant (Merchant perspective => Details => General).

The section consists of the following fields:




UI Field Name API Field Name Usage External Doc Link Description
Tax ID business.taxId Optional Tax ID associated with a merchant. You’re not allowed to register identical tax IDs. For this reason, if you’re onboarding the merchant via the user interface, you can verify if its tax ID already exists in the gateway.
Portfolio ID portfolioId Conditional API integration note Identifier of a portfolio associated with a merchant. The selection of the portfolio and a processor is the first step of the onboarding process. For this reason, there is no ability to change the portfolio when you are entering information at this step. The field is read-only on the user interface.
ID merchantId Optional API integration note Gateway generated identifier associated with a merchant. The value of this field is generated automatically by the gateway. For this reason, you can’t enter it manually. The field is read-only.
Code merchantCode Optional API integration note Identifier associated with a merchant supplied by a submitter. If you process transactions through the UniPay cloud integration, make sure you are familiar with the code assignment principles described in the general information about UniPay Cloud.

  • Tax ID/business.taxId - tax ID associated with a merchant. You’re not allowed to register identical tax IDs. For this reason, if you’re onboarding the merchant via the user interface, you can verify if its tax ID already exists in the gateway.


  • Portfolio ID/portfolioId - ID of a portfolio associated with a merchant. The selection of the portfolio and a processor is the first step of the onboarding process. For this reason, there is no ability to change the portfolio when you are entering information at this step. The field is read-only. Submission rules via API are explained here.
  • ID/merchantId - gateway generated identifier associated with a merchant. The value of this field is generated automatically by the gateway. For this reason, you can’t enter it manually. The field is read-only. Submission rules via API are explained here.
  • Code/merchantCode - identifier associated with a merchant supplied by a submitter. If you process transactions through the UniPay cloud integration, make sure you are familiar with the code assignment principles described in the general information about UniPay Cloud. Submission rules via API are explained here.


Settings (M)

After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:
  • all information from this section is populated in the general details of the merchant (Merchant perspective => Details => General).

The section consists of the following fields:


UI Field Name API Field Name Usage External Doc Link Description
Merchant profile merchantProfile Optional (submits a default value if not specified – SSSSM) Merchant Configuration Guide The configuration structure of a merchant and its accounts
Reseller resellerId Conditional API integration note A reseller under which a merchant is created.


  • Merchant profile/merchantProfile - the configuration structure of a merchant and its accounts.
  • Reseller/resellerId - a reseller under which a merchant is created.


Merchant (M)

An onboarding application has four basic states - approved, in review, declined, and error. When a negative result is received (decline and error), a merchant record is not created in the gateway. If a positive result is received (approval or in review), a merchant is always created when approved and depending on the settings when being reviewed by a processor used for onboarding. For some business scenarios, the issues for why the merchant is being reviewed can be resolved later, while the merchant is created in the gateway when its application is under review. This is called the instant onboarding effect. In this way, the system that submits the onboarding request can configure the merchant from the first attempt, skipping the creation of a complicated status verification mechanism. However, some systems prefer to work with an actual onboarding status, and create the merchant record in the gateway only after it’s approved by the processor. To control under which status the merchant is created in the gateway, the merchant creation policy is used.

  • On Approval Only - a merchant is created only under the condition that its onboarding application has been Approved by a processor used for onboarding.
  • On Approval and Review - a merchant is created under the condition of either the Approval or In Review response are received from the processor. If the merchant is created in the In Review status, it will be inactive in the gateway until an approval is received. After being approved, the merchant automatically becomes active.

Business Information


This page is available on the user interface and in API. It contains the business formation about a merchant for configuring it in the gateway and onboarding in the processor’s system to receive its identities.

Business Details (M, F)

After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:

  • all fields from this section, except Customer Service Phone, are populated in the business information of the merchant (Merchant perspective => Details => Underwriting => Business).
  • Customer Service Phone is a part of the merchant’s descriptor and is populated in the provider profile information (Merchant perspective => Details => Profiles => Processing Information).

The section consists of the following fields:





UI Field Name API Field Name Usage External Doc Link Description
Business Name (DBA) business.businessName Required Name of a merchant, under which it does business.
Legal Business Name business.legalName Required Name of a merchant, under which it is registered.
Business Type business.ownershipStructureType Required API integration note Type of the business ownership.
Tax ID business.taxId Required Tax ID associated with a merchant.
Web Site business.webSite Optional Web site of a merchant. The following regular expressions are allowed for this field:
^[0-9A-Za-z-\\\\#/_@!<>~%&=:;>.\\u0020\\.\\+\\)\\(\\*\\^\\$\\?]*$;
Business Description business.description Optional Additional notes associated with a merchant. The field is limited to 255 characters for a merchant and to 2,000 characters for an account.
Contact Phone Number business.contactPhone Optional A phone number to reach out to a merchant. The following regular expressions are allowed for this field: ^[0-9]*$;
Contact Email Address business.email Required Email to reach out to a merchant.
Customer Service Phone business.descriptorPhone Required API integration note Merchant’s phone to provide customer service. The value forms the merchant’s descriptor. The following regular expressions are allowed for this field: ^[0-9]*$;


  • Business Name (DBA)/business.businessName* - name of a merchant, under which it does business.
  • Legal Business Name/business.legalName* - name of a merchant, under which it is registered.
  • Business Type/business.ownershipStructureType * - types of the business ownership.
  • Tax ID/business.taxId* - tax ID associated with a merchant.
  • Web Site/business.webSite - web site of a merchant. The following regular expressions are allowed for this field: ^[0-9A-Za-z-\\\\#/_@!<>~%&=:;|.\\u0020\\.\\+\\)\\(\\*\\^\\$\\?]*$;
  • Business Description/business.description - additional notes associated with a merchant. The field is limited to 255 characters for a merchant and to 2,000 characters for an account.
  • Contact Phone Number/business.contactPhone - a phone number to reach out to a merchant. The following regular expressions are allowed for this field: ^[0-9]*$;
  • Contact Email Address/business.email* - email to reach out to a merchant.
  • Customer Service Phone/business.descriptorPhone* - merchant’s phone to provide customer service. The value forms the merchant’s descriptor. The following regular expressions are allowed for this field: ^[0-9]*$;


Address Information (M, A, F)


After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:

  • all fields from this section are populated in the business information of the merchant (Merchant perspective => Details => Underwriting => Business).
  • all fields from this section are populated in the general information of the merchant (Merchant perspective => Details => General).

The section consists of the following fields:
UI Field Name API Field Name Usage Description
Street business.street1 Required Street associated with a merchant’s legal address.
City business.city Required City associated with a merchant’s legal address.
State business.state Required Country and state associated with a merchant’s legal address.
Zip Code business.zipCode Required Zip code associated with a merchant’s legal address.


  • Street/business.street1* - street associated with a merchant’s legal address.
  • City/business.city* - city associated with a merchant’s legal address.
  • State/business.state* - country and state associated with a merchant’s legal address.
  • Zip Code/business.zipCode* - zip code associated with a merchant’s legal address.

Additional Business Detail (M)


After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:

  • all fields from this section, except Currency, are populated in the business information of the merchant (Merchant perspective => Details => Underwriting => Business).
  • Currency is populated in the remittance settings of the merchant (Merchant perspective => Details => Funding => Settings).

The section consists of the following fields:







UI Field Name API Field Name Usage External Doc Link Description
Business Registration State business.registrationState Optional API integration note A country and a state where a merchant is registered. The country is required to be the same as stated in the legal address. The state can differ.
Year Business Started business.registrationYear Optional API integration note Year when a merchant started to operate as a business.
Work Hours business.workHours Optional API integration note Hours when a merchant provides services to its customers.
Time Zone business.timeZoneCode Optional API integration note Time zone, in which a merchant operates.
MCC business.merchantCategoryCode Required API integration note Merchant category code of a merchant.
Currency business.currencyCode Optional API integration note Currency, in which funds will be transferred to its account as a result of remittance.


  • Business Registration State/business.registrationState - a country and a state where a merchant is registered. The country is required to be the same as stated in the legal address. The state can differ.
  • Year Business Started/business.registrationYear - year when a merchant started to operate as a business.
  • Work Hours/business.workHours - hours when a merchant provides services to its customers.
  • Time Zone/business.timeZoneCode - time zone, in which a merchant operates.
  • MCC/business.merchantCategoryCode* - merchant category code of a merchant.
  • Currency/business.currencyCode - currency, in which funds will be transferred to its account as a result of remittance.

Estimates/Processing Parameters (M, A)


To avoid a merchant’s fraud, a processor, through which the merchant is going to perform transactions, needs to know an estimated annual volume and amount of transactions as well as a maximum amount of a single transaction. This page is available on the user interface and in API. It contains the information about an estimated income of the merchant from processing payment card and direct debit transactions. Estimates are indicated in dollars for the year period.

After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following places on the user interface:

  • all fields from this section are populated in the business information of the merchant (Merchant perspective => Details => Underwriting => Business).
  • Maximum Transaction Amount is populated in the provider profile information (Merchant perspective => Details => Profiles => Processing information).

The section consists of the following fields:
UI Field Name API Field Name Usage Description
Transaction Volume estimates.annualDirectDebitVolume
estimates.annualCardsVolume
Required Total transaction amount that a merchant expects to process over a year. If the merchant is going to process only card transactions, the value for direct debit must be indicated as 0.
Average Transaction Amount estimates.avgDirectDebitTransactionAmount
estimates.avgCardsTransactionAmount
Required Average transaction amount of a single transaction that a merchant expects to process over a year. If the merchant is going to process only card transactions, the value for direct debit must be indicated as 0.
Maximum Transaction Amount estimates.maxTransactionAmount Required Maximum amount of a transaction a merchant expects to process. To avoid fraud, some processors require that a submitted transaction amount wouldn’t exceed an amount indicated as an estimate during onboarding. If the merchant submitted a transaction of a bigger value, these transactions are declined by the processor for both realtime and batch transactions. If a batch transaction is declined due to a bigger amount, the entire batch file gets rejected. For this reason, the gateway validates the amounts of the submitted transactions for both realtime and batch. If present, these transactions are not submitted further to the processor. For realtime transactions, an exception is returned. For batch transactions, a file is rejected with a reason being indicated in a validation file.


  • Transaction Volume/estimates.annualDirectDebitVolume/estimates.annualCardsVolume* - total transaction amount that a merchant expects to process over a year. If the merchant is going to process only card transactions, the value for direct debit must be indicated as 0.
  • Average Transaction Amount/estimates.avgDirectDebitTransactionAmount/уstimates.avgCardsTransactionAmount* - average transaction amount of a single transaction that a merchant expects to process over a year. If the merchant is going to process only card transactions, the value for direct debit must be indicated as 0.
  • Maximum Transaction Amount/estimates.maxTransactionAmount* - maximum amount of a transaction a merchant expects to process. To avoid fraud, some processors require that a submitted transaction amount wouldn’t exceed an amount indicated as an estimate during onboarding. If the merchant submitted a transaction of a bigger value, these transactions are declined by the processor for both realtime and batch transactions. If a batch transaction is declined due to a bigger amount, the entire batch file gets rejected. For this reason, the gateway validates the amounts of the submitted transactions for both realtime and batch. If present, these transactions are not submitted further to the processor. For realtime transactions, an exception is returned. For batch transactions, a file is rejected with a reason being indicated in a validation file.

Settings


This page is partially available on the user interface and in API. Thus, all sections are present on the user interface as well as the Deposit/Banking Details and the Descriptors/Customer Payment Card and Bank Statement sections are present in API.

It contains the information about the merchant’s settings for transaction processing.

Deposit/Banking Details (M, A, F)

After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following place on the user interface:

  • all fields from this section are populated in the deposit information of the merchant (Merchant perspective => Details => Funding => Deposit).

The section consists of the following fields:
UI Field Name API Field Name Usage Description
Bank Name deposit.bankName Optional Name of the bank where the merchant’s account for transferring funds as a result of transaction processing is.
Account Holder Name deposit.holderName Required Name, under which the merchant’s account is registered.
Account Type deposit.accountType Optional Type of the merchant’s account. Can be either savings or checking.
Routing Number deposit.routingNumber Required Routing number associated with the merchant's account.
Maximum Transaction Amount deposit.accountNumber Required Number associated with the merchant's account.


  • Bank Name/deposit.bankName - name of the bank where the merchant’s account for transferring funds as a result of transaction processing is.
  • Account Holder Name/deposit.holderName* - name, under which the merchant’s account is registered.
  • Account Type/|deposit.accountType - type of the merchant’s account. Can be either savings or checking.
  • Routing Number/deposit.routingNumber* - routing number associated with the merchant's account.
  • Account Numberdeposit.accountNumber* - number associated with the merchant's account.

Merchant Fees (M, A)


After a merchant’s onboarding application has been approved, you can find the merchant’s fess configured based on the pricing policy selected at this step. The fees will be available on the Fees form (Merchant persp => Remittance => Fees).

The section consists of the following field:

  • Pricing Policy - reference to a pricing template that is going to be applied to the merchant.

Profile List (M, A)


After a merchant’s onboarding application has been approved, you can find the merchant’s provider profiles configured based on the configuration selected at this step. The provider profiles will be available on the Profiles form (Merchant persp => Detail => Profiles).
The section consists of the following field:

  • Configuration - reference to configuration that is going to be applied to the merchant => ссылка на секцию гайда про configurations

Descriptors/Customer Payment Card and Bank Statement (M, A)


After a merchant’s onboarding application has been approved, you can find some of the field values from this section at the following place on the user interface:

  • all fields from this section are populated in the provider profile information of the merchant (Merchant persp => Detail => Profiles => Processing Information).

The section consists of the following fields:




UI Field Name API Field Name Usage External Doc Link Description
Card Descriptor business.paymentCardDescriptor Optional Descriptor, which is going to be shown in the customer’s statement when for the transactions made with a payment card.
Direct Debit Descriptor business.directDebitDescriptor Optional API integration note Descriptor, which is going to be shown in the customer’s statement when for the transactions made via direct debit. The descriptor consists of a merchant’s name (the Merchant field) and its customer service phone (the Item field).
Customer Service Phone business.descriptorPhone Required Phone, which a merchant uses for providing customer service. The field is filled out automatically from the business information and can’t be modified here.


  • Card Descriptor/business.paymentCardDescriptor - descriptor, which is going to be shown in the customer’s statement when for the transactions made with a payment card.
  • Direct Debit Descriptor/business.directDebitDescriptor - descriptor, which is going to be shown in the customer’s statement when for the transactions made via direct debit. The descriptor consists of a merchant’s name (the Merchant field) and its customer service phone (the Item field).
  • Customer Service Phone/business.descriptorPhone* - phone, which a merchant uses for providing customer service. The field is filled out automatically from the business information and can’t be modified here.

To learn about merchant descriptor, review this API integration note.

Terms & Agreements (M, A)


This page is available only in API. It contains a cooperation agreement between a merchant and the gateway.

After a merchant’s onboarding application has been approved, you can find the information from this section at the following places on the user interface:

  • an agreement, under which a merchant was onboarded, is shown in its application at the reseller and portfolio level (Reseller/Portfolio persp => Onboarding => Applications)
  • when onboarding of a merchant is done via the user interface, its agreement is available on the result page after the application was submitted to the processor.

Terminals


Terminal ID Registration


In order to process card-present transactions, a merchant has to set up one or more terminals within the gateway and obtain TID(s) from a processor along with the Merchant ID. Terminals can be configured automatically via onboarding API instead of manual provisioning of terminals via FMS module.

As part of the onboarding process, a merchant can configure its terminals within the gateway and processor´s system in either of the two ways:

1) During merchant onboarding (along with MID registration).

If it is known in advance that a merchant will need POS terminals to process payments, a required number of terminals can be set up during the merchant's onboarding using terminalSetup field present in the create API request. To learn more about the usage of the terminalSetup field, review this integration note.


2) For onboarded merchants (after MID registration).

If there is a need to change the number of terminals after the merchant has been successfully onboarded, a separate add-terminal API call is used. Add-terminal API request allows to add the required number of terminals, but only one at a time, at any moment after the merchant's onboarding application has been approved by the processor.

Terminal Statuses


Upon the submission of the terminal record creation request to the processor (either via terminalSetup field in create API request or via add-terminal API request), you can verify the current terminal status on the user interface. All terminals registered within the onboarding process are displayed on the following forms in the gateway:


The terminal is displayed in ONBOARDING status until the response is returned by the processor. If the terminal has been registered successfully, the processor returns terminal ID in either terminalSetup field (create API response) or terminalId field (add-terminal API response), and the terminal obtains UNASSIGNED status on the user interface.
UNASSIGNED - indicates that the terminal record has been created within the gateway and processor’s system.
After the merchant's terminal has been registered at the processor's side, it has to go through the standard terminal order process as it needs to be fulfilled and delivered to the merchant. Until then, the terminal record can be used by the merchant as a virtual terminal.

If the terminal registration failed, terminal ID is not returned by the processor, and the terminal is displayed on the user interface in DISCARDED status.

Activation and Deactivation of Terminals


When a physical device is delivered to the merchant, it must be activated (consult section 6) Terminal connection and activation for details).

It should be noted that certain providers within the Interac system require additional validation of the terminal by serial number. Provided that the terminal ID was obtained via onboarding API, it is done automatically by the gateway.

When the merchant enters and submits terminal activation code (TMS activate-terminal API request), it triggers the submission of update-terminal onboarding API request. For this purpose, unicharge.onboarding.process-applications job is used. The update-terminal onboarding API request is forwarded to the processor only if this feature is supported, otherwise, the terminal is activated only within the gateway.

If the physical terminal won’t be in use any more for some reason or has to be returned/exchanged, it must be deactivated. For this purpose, you have to change the status of the terminal record from Active to Inactive in one of the following ways:
  • manually via the user interface;
  • via update-terminal API request if this feature is supported by the processor (the value of the status field should be set to Inactive).

See this guide for more information about the terminal further configuration and monitoring of its activity.

Merchant Verification


As part of the onboarding process, a series of checks is performed. These checks allow a merchant to obtain a MID and the associated process is called Merchant Verification. A payment facilitator can have an agreement with a processor to work according to the MID pre-allocation program. This means that the payment facilitator obtains MIDs right away, and distributes them among merchants by itself. In this case, the payment facilitator must perform underwriting by itself. Verification can be done either by a processor during onboarding or by the outside services.

When a payment facilitator assigns a MID to a merchant, it can activate transaction processing right after the MID is assigned. Thus, the onboarding process occurs more quickly. When an outside service is used for underwriting, the payment facilitator submits the merchant’s information for risk analysis. The processes of verification and onboarding are being carried out concurrently. Meaning, these processes occur simultaneously, and do not depend on one another. Until the verification is successfully completed, the merchant is unable to receive money into its account. For this reason, merchant remittance is put on hold until the risk analysis is complete.

At this time, the gateway supports verification via Agreement Express.

The mechanism of performing verification through an outside service is as follows:
1) To start using the service, you need an account at the service’s side. To have one created, address the issue with the service and follow its instructions. When working with Agreement Express, every account is connected to its risk scorecard, which includes verification rules for performing verification through Agreement Express.

2) To activate the service in the gateway, you have to enable this feature in the onboarding profile, through which you are going to onboard merchants. You can access the onboarding profile via the Portfolio perspective=>Profiles=>Onboarding=>[your provider]:


3) On the user interface, configure a verification profile using the credentials received during the account/risk scorecard registration. You can access the verification profile on the Portfolio perspective=>Details=>General=>Verification tab=>New:




4) If the verification request was submitted to the service, merchant information is under review. You can check whether the verification request was sent on the user interface.



5) To obtain verification results, sign in to your account. Further actions depend on the verification result:
  • if a positive verification response has been received before the merchant is onboarded at the processor’s side, no action is required from you.
  • if the merchant is under review by a processor but the verification result is negative, reject the merchant’s application via the user interface. Further behavior of the gateway depends on how the merchant creation policy is set up:
    • if the merchant creation policy is set as On Approval Only (which means that a merchant record is created only for approved onboarding applications), no merchant is created after the onboarding application is rejected;
    • if the merchant creation policy is set as On Approval and Review (which means that a merchant record is created for both approved and in review onboarding applications), a merchant is deactivated after the onboarding application is rejected;



  • if the merchant is already onboarded at the processor’s side but the verification result has not yet been received, the merchant’s remittance is put on hold automatically by the gateway. Further actions depend on the verification result:
    • if the approved application of the merchant went through the verification successfully, remove the hold from the merchant’s remittance for further processing and money depositing;



  • if the approved application of the merchant failed to go through the verification, reject the merchant’s application via the user interface. If the application is rejected, the merchant gets deactivated in the gateway.