Onboarding APIs



Integration Notes


Cross-reference Fields  

The system provides an ability to specify values that can be used for cross-referencing of entities between the gateway and a submitter’s system. The fields that can be provided by an integrated external system are listed below:


Entity Field Name Description
Merchant merchantCode Identifier of a merchant assigned by an external system that initiates an onboarding request.

Descriptor Format  

A descriptor is a value used to identify a merchant on merchant/customer statements and receipts. It is assigned to all payment card and direct debit transactions associated with the merchant. The descriptor has a fixed length. However, the length differs for payment card and direct debit transactions:
  • For payment cards, the value of a descriptor consists of 25 characters;
  • For direct debit, the value of a descriptor consists of 26 characters.

Regulations in the United States impose specific requirements on descriptors for direct debit transactions, which differ from the requirements of other countries. In the U.S., a direct debit transaction descriptor consists of two parts: the name of a merchant's company and a descriptor value assigned by the merchant. For example, SuperMerch:DescrValue, where SuperMerch is a name of the merchant’s company and DescrValue is any value assigned by the merchant.

Merchants can assign different descriptors to payment card and direct debit transactions. However, we suggest using the same value for both by combining the name of the merchant's company (9-11 characters) and the customer service phone (10 characters):
merchant’s descriptor (19-21) = merchant’s company name (9-11) + customer service phone number (10). For example, merchant’s descriptor for the merchant SuperMerch with customer service phone number 1234567890, will be combined as follows: SuperMerch1234567890.

Note that using a colon (:) sign within the business.paymentCardDescriptor field is prohibited and only such special characters as a dash (-) and underscore (_) are allowed. Colon can only be used as the field separator in the business.directDebitDescriptor field to separate merchant’s company name and customer service phone values.

When transaction processing is done through a payment facilitator, the name of a payment facilitator gets specified in a descriptor automatically. It is present as a prefix consisting of 3-5 characters separated from the merchant's descriptor by an asterisk (*). The length of the prefix differs for each payment facilitator, so the number of characters that can be present within a merchant’s descriptor is limited. For a merchant’s company name in a descriptor to be calculated properly, please contact the gateway support team to get the payment facilitator’s prefix that is going to be used in the descriptors of the merchants associated with the payment facilitator.

When there is a payment facilitator, the descriptor is created by combining the payment facilitator prefix (3-5 chars), an asterisk, the merchant's company name (11-9 chars, depending on the prefix length) and the customer service phone number (10 chars):
paymentCardDescriptor/directDebitDescriptor (25) = facilitator descriptor (3-5) + * + merchant’s company name (9-11) + customer service phone number (10).
For example, the descriptor for the merchant SuperMerch with customer service phone number 123-456-7890, who processes transactions through payment facilitator with the prefix TEST, is combined as follows: business.paymentCardDescriptor=TEST*SuperMerch1234567890.

Field Management  

Onboarding application provides a series of pages allowing to collect information from a merchant necessary to provision an account. In some cases, merchant will be expected to complete all of the fields. However, sometimes it might be undesirable to allow merchants to modify certain fields or even see the values of these fields.

For such cases, the system allows to hide some fields or make them read-only. This applies to all of the fields that have a prefix (dot in their name, for example, owner.firstName, business.businessName, etc).

To make a field read-only, prefix @@ should be added. In this case, the format will be the following:

fieldName=@@value of the field
For example, owner.firstName=@@John

To hide a field, prefix @! should be added. In this case, the format will be the following:

fieldName=@!value of the field
For example, owner.firstName=@!John

By default, the page will be rendered with a header and a footer. To hide them, you can use isEmbedded field. If you would like certain pages omitted entirely, you can use pageFormat field (see integration notes for more information).

Internal and External IDs  

By means of onboarding API, new merchants can be created within the system. When a merchant is created, it can be attached to a particular portfolio or reseller:
  • If portfolioId is present within the API request, a merchant is created under the specified portfolio without being attached to a particular reseller;
  • If resellerId is present within the API request, a merchant is created under the specified reseller and associated portfolio;
In addition, new accounts can be created within the system as well. When an account is created, it can be attached to a new or existing merchant:
  • If merchantId is present within the API request, an account is created under the specified merchant, and assigned merchantId is a subsequent number for the last account present within the system. For example, if merchantId is specified as 2000 and the last account under this merchant is 2001, then the code of the newly created account will be set as 2002.
  • If merchantId is not present within the API request, then a merchant and account are both created, and the account gets attached to the newly created merchant. For example, if the last merchant within the system is 2000, then merchant 3000 will be created and the code of the new account will be set as 3001.

If during the process of merchant creation portfolioId or resellerId are not explicitly specified, the following set of rules will be applied:
  • It is sufficient to specify reseller ID only. In this case, portfolio ID will be derived from the portfolio of the reseller that is specified.
  • If a reseller is not specified, but a portfolio is specified explicitly, the system is going to assume that the merchant should be created under the portfolio without any attachment to a reseller.
  • If a user has access to only one reseller or only one portfolio, even if a parameter is not specified, that reseller or that portfolio will be assumed and selected by default.
  • If a user has access to multiple portfolios and multiple resellers, either reseller ID or portfolio ID must be explicitly specified to explain the system, under which reseller and portfolio a merchant should be created.

Is Embedded Field  

Onboarding application can be used in two modes – standalone and embedded. When used as standalone, both header and footer will be present on every page. When used as embedded, only forms content will be visible, while header and footer will be suppressed.To control which mode is applied, isEmbedded field is used.

By default, the onboarding application is shown as a standalone page - isEmbedded=0. However, if it is desirable to embed the application using frame or iframe, and therefore header and footer are not needed, then isEmbedded parameter can be set to 1. This will indicate that the content will be embedded in the page with the existing header and footer, and therefore no additional header and footer will be generated. To avoid scrollbars within a frame, its size should be 700px x 900px.

Multiple Owner Field Names  

In the onboarding process a merchant provides information about the owners of a business. Owner-related fields are required when using API. However, the requirements on the number of owners, information about which should be provided, vary depending on the governmental regulations and business needs.

1) To comply with the US federal regulations, the following information must be provided during the onboarding process: information about every business owner with a stake of 25% or more (10% or above for high-risk businesses) and the controlling officer if present.
To submit this information to the gateway, fields with a prefix owner.X are used (where X is a value from 1 to 6 depending on the number of the owners). The owner.X fields are only used for merchant onboarding.
For example, a business is run by three owners with shares represented as 50%/30%/20%. All three owners have to be registered along with the onboarded merchant. The information about each owner is to be submitted using the following fields:
  • owner.1. fields - for the one that owns the 50% stake;
  • owner.2. fields - for the one that owns the 30% stake;
  • owner.3. fields - for the one that owns the 20% stake.

2) Other countries do not require the provision of information about all owners that have a stake in a business. When onboarding merchants outside of the US, we recommend using the owner.1 fields to submit information about any of the owners to comply with the general logic.

Legacy Field Names

We strongly encourage you to migrate from the previous API version to the new one. In case you are still using the older version, below is how the system is going to interpret legacy field names. The old field names will be supported until October, 30th, 2019.



Deprecated Field Name New Field Name
owner.firstName officer.firstName
owner.lastName officer.lastName
owner.street1 officer.street1
owner.street2 officer.street2
owner.city officer.city
owner.state officer.state
owner.zipCode officer.zipCode
owner.countryCode officer.countryCode
owner.birthDate officer.birthDate
owner.socialSecurity officer.socialSecurity
owner.phone officer.phone
owner.email officer.email

Officer Field Names  

Before learning about the officer-related fields, make sure that you have familiarized yourself with the concept of owners.

As a merchant’s business may be not run by a business owner, a concept of a controlling officer exists. This is a person who performs an administrative role in running a company. The requirement to provide information about the controlling officer is present only for the USA.
To submit the information about a controlling officer of the business to the gateway, fields with a prefix officer are used. This person can also be a business owner. In this case, the information about the owned stake must be submitted within the
owner.X.stakePercentage field. The officer-related fields are used both for merchant and account onboarding.

Officer-related fields in the API are conditional. The conditions under which they are submitted in this or that way depend on such factors as a country of a merchant’s business (officer is required in the US only), whether or not a controlling officer and a business owner are the same person, or what ownership structure type the business holds.

1) In cases when an officer is not a business owner, the information about the controlling officer is required to be submitted in the officer-related fields. Thus, the officer-related fields are required.
2) In cases when a business owner is an officer, the information about the controlling officer is required to be submitted in the owner-related fields. Thus, the officer-related fields are optional.

Depending on an ownership structure type, there are also some limitations on who can function as an officer:

  • For Sole proprietorship, an officer and an owner are the same person with the stake percentage of 100%. According to the paragraph 2 described above, when using API, the owner-related fields are used and the owner.X.stakePercentage field value must be equal to 100.
  • For Limited liability partnership, Nonprofit corporation, Charitable solicitations program, Corporation and Government agency, an officer and a business owner can be either one person or not. According to the paragraphs 1 and 2 described above, you can use either officer-related or owner-related fields.
  • For General partnership, Limited partnership, Limited liability company, Charitable trust program and International organization, an officer is expected to be one of the owners. According to the paragraph 2 described above, when using API, the owner.X.stakePercentage field value must be greater than 0.

Onboarding Response  

The system supports two ways of how an onboarding response is received – via callback or in real-time.

Callback URL is used for cases when either a processor does not support real-time responses or pending status, such as “In review”, is possible. To enable callback for a particular onboarding API request (create API call), notifyURL field is used. If definite URL is specified within the notifyURL field, the result of the onboarding process is delivered to this URL.

In case if an immediate response is supported by a processor, onboarding results are delivered to a return URL indicated in the API request. To control how the response is received in realtime, returnURLpolicy field is used. The following values are possible:
  • page (default) – when onboarding process is complete, a confirmation page is rendered with returnURL link;
  • redirect - when onboarding process is complete, the customer is automatically redirected to returnURL (bypassing confirmation page).

Page Management  

For cases when it is needed to hide some information within the onboarding application, the system allows to hide not only separate fields, but also entire pages. To control which pages should be available within the onboarding application, pageFormat field is used. The field is structured as a mask.

The following values are available for the pages within the onboarding application:
  • O – owner information (information associated with the primary owner of a business)
  • B – business information (information associated with the merchant’s business, such as DBA name, tax ID, MCC etc)
  • D – deposit information (information associated with the merchant’s deposit account)
  • A – agreement (terms and conditions of merchant agreement)
  • H - sub-header (sub-header presence within the pages of the onboarding application)

If all pages should be available for a merchant, the value of pageFormat field should be always submitted as OBDAH. If some pages should be hidden, a respective value should be omitted in the request. For example, if deposit information should be skipped, the value of pageFormat will be the following:

pageFormat=OBAH

Note that agreement page cannot be omitted as this is a mandatory step in business relationships. Also, the order of letters is not important.

Terminal Setup  

During the merchant onboarding, you can set up terminals that are going to be used for transaction processing. Terminals can be configured via the terminalSetup field, which allows to specify a type (industry for which the terminal is going to be used) and quantity of the terminals that are going to be set for the merchant. Currently, up to 99 terminals for each of the following industries can be configured:
  • R - retail;
  • S - restaurant.
Format of the terminalSetup field value is the following: [terminal type][number of terminals]. For example:
  • if three terminals for the retail industry should be configured for the merchant, the field has to be submitted as terminalSetup=R3.
  • if two terminals for the retail industry and three terminals for the restaurant industry should be configured, the field has to be submitted as terminalSetup=R2S3.