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. |
| Terminal | terminalCode | Identifier of the terminal supplied by a submitter. |
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:
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.
- 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).
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 during the process of merchant creation portfolioId or resellerId are not explicitly specified, the following set of rules will be applied:
- 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;
- 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.
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:
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.
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 (for example, a CEO whose responsibility is to run a business). 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:
Note: After the application has been submitted, the information about the controlling officer can be modified via adjust API request. Officer-related information should be resubmitted in the same field group as used in the original create request:
In the table below you can see, in which fields business owner and officer-related information is submitted depending on the ownership structure type:
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 (for example, a CEO whose responsibility is to run a business). 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, and Charitable trust program, 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.
Note: After the application has been submitted, the information about the controlling officer can be modified via adjust API request. Officer-related information should be resubmitted in the same field group as used in the original create request:
- in officer. fields - if officer info was initially submitted in officer-related fields,
- in owner.1 fields - if the officer info was initially submitted in owner-related fields.
In the table below you can see, in which fields business owner and officer-related information is submitted depending on the ownership structure type:
| Ownership structure type | Officer and owner are the same person | Field group for officer info submission | Field group for owner info submission | Officer’s stake in business (submitted in owner.X.stakePercentage field) (%) |
|---|---|---|---|---|
| Limited lability company, Nonprofit corporation, Government agency, Partnership, Public corporation, Private corporation |
no | officer. | owner.X. | x |
| yes | owner.X. (officer=owner.1.) | owner.X. | > 0 | |
| Sole Proprietorship | yes | n/a | owner.1. | owner.1.stakePercentage=100 |
Onboarding Response
Callback and realtime 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 a 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:
Onboarding response codes
If an error occurred during the onboarding application submission, one of the gateway system error codes is returned in the response.
In other cases, one of the specific onboarding response codes defining the onboarding application status is assigned.
The exception are situations when the application failed with multiple errors. In this case, in provider response code field, the code of first of multiple errors is returned with the following provider response message "Multiple issues occurred within the application submission process". In the gateway the S99 (Internal error) is returned. The cause of each of the multiple errors is available on the Onboarding Wizard form.
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 a 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).
Onboarding response codes
If an error occurred during the onboarding application submission, one of the gateway system error codes is returned in the response.
In other cases, one of the specific onboarding response codes defining the onboarding application status is assigned.
The exception are situations when the application failed with multiple errors. In this case, in provider response code field, the code of first of multiple errors is returned with the following provider response message "Multiple issues occurred within the application submission process". In the gateway the S99 (Internal error) is returned. The cause of each of the multiple errors is available on the Onboarding Wizard form.
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:
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.
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
You can set up terminals that are going to be used for transaction processing as part of the onboarding process in either of the two ways:
1) During the merchant onboarding, 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 989 terminals for each of the following industries can be configured:
If the onboarding application has been approved by the processor, TIDs are returned in create API response in terminalSetup field in the following format: [terminal type][Provider TID]. For example, R001, S002.
2) After the merchant has been successfully onboarded, terminals can be configured via separate add-terminal API call.
1) During the merchant onboarding, 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 989 terminals for each of the following industries can be configured:
- R - retail;
- S - restaurant.
- 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.
If the onboarding application has been approved by the processor, TIDs are returned in create API response in terminalSetup field in the following format: [terminal type][Provider TID]. For example, R001, S002.
2) After the merchant has been successfully onboarded, terminals can be configured via separate add-terminal API call.
Data Format
The following fields are considered as containing sensitive data: officer.birthDate, officer.socialSecurity, officer.driverLicense, owner.X.birthDate, owner.X.socialSecurity, owner.X.driverLicense, business.taxId, deposit.routingNumber, deposit.accountNumber.
All sensitive fields will be encrypted with a registered RSA public key.
Therefore it is required to generate a key pair and provide your public key before using the API request.
All sensitive fields will be encrypted with a registered RSA public key.
Therefore it is required to generate a key pair and provide your public key before using the API request.
Fee Control Parameters
There are two parameters available to control fee assessment behavior:
remittanceStartDate is crucial for determining the starting date from which processed transactions are included in a merchant's funding, with the current date as the default if unspecified. This is particularly useful for excluding certain transactions, like test transactions, before a specific date.
recurringFeesBeginDate specifically governs the initiation of recurring fees on transactions. If there's a grace period where you wish to exempt transactions from recurring fees, you set this date accordingly. However, the start date for these recurring fees cannot be earlier than remittanceStartDate and must be within three months of it, ensuring fees apply only within a defined timeframe.
remittanceStartDate is crucial for determining the starting date from which processed transactions are included in a merchant's funding, with the current date as the default if unspecified. This is particularly useful for excluding certain transactions, like test transactions, before a specific date.
recurringFeesBeginDate specifically governs the initiation of recurring fees on transactions. If there's a grace period where you wish to exempt transactions from recurring fees, you set this date accordingly. However, the start date for these recurring fees cannot be earlier than remittanceStartDate and must be within three months of it, ensuring fees apply only within a defined timeframe.
Recurring Fees Begin Date
recurringFeesBeginDate specifically governs the initiation of recurring fees on transactions. If there's a grace period where you wish to exempt transactions from recurring fees, you set this date accordingly. However, the start date for these recurring fees cannot be earlier than "remittanceStartDate" and must be within three months of it, ensuring fees apply only within a defined timeframe.
Bank Code
Deposit information can be conveyed through the respective fields - deposit.bankName and deposit.routingNumber. However, in countries where the number of banks is limited, there is an option to register all banks within the system and transmit only the bankCode under which the bank is registered in the system, instead of using these fields. In such a case, the values for deposit.bankName and deposit.routingNumber will be retrieved from the internal table containing the list of banks.
Copyright ©
TidyPay. All Rights Reserved.
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.