TidyPay Terminology

An affiliate is a company or a person that is represented as a separate entity within the gateway and is a partner of the merchant that promotes its products. The most common examples of affiliates are marketplaces, bloggers, journalists, etc.

Affiliates do not process transactions and can participate only in split transactions. Affiliates must have separate accounts created for them. Because they cannot process transaction other than for split payments, they do not need to have fees and provider profiles configured for them like traditional merchants. Under the context of remittance, the only settings an affiliate needs are deposit settings.

Branding module is the mechanism that allows users to create a unique visual representation of a company in the gateway. The gateway allows branding of the following resource groups:
— Web resources - web pages that can be customized using branding functionality.
— Print resources - documents such as statements and receipts that can be customized using branding functionality.
— Notification resources - email notification templates that can be customized using branding functionality.

Web, print and notification resources can be customized via a branding profile of a particular entity (merchant, reseller or portfolio). By means of the branding profile, users that have access to the entity can communicate with lower entities.

A meta structure defining basis for a Merchant Fee and a Reseller Commission. It encapsulates fee structure, while merchant fees and reseller commissions define specific values to be used within the structure.

Fee Schema is comprised of an ordered list of fee schema detail records, which are subdivided into groups based on their meaning. Each detail has a description and formula associated with it. The formula is defined using statistical variables calculated daily off operations data. The formula serves as the basis for fees and commissions calculation.

Merchant represents a customer (tenant) within the gateway. Serves as a logical grouping of data and configuration settings.

Minimum fees is a mechanism that allows a payment facilitator to pay compensation to a reseller only when the reseller has earned a minimum amount on its merchants. The minimum amount is calculated from the total amount of fees across all merchants associated with the reseller. Which fee types are required to be included in the calculation should be communicated beforehand. The reseller commissions are deducted from the total amount of fees collected from a merchant. If the residual amount is less than the required minimum amount, then the difference is compensated by the reseller from its commissions. To learn more about minimum fees, review Minimum Fees section of the Remittance Management Guide.

The process of obtaining a processor's MID and TID for a merchant and configuring the merchant and its accounts in the gateway. The process can be organized in two ways: via API or the user interface. In both cases, the onboarding application is used.

Perspective is the core element of User Interface. It's a set of forms and actions designed to simplify the work process within a specific business context. A perspective is designed to group together related fuctionality and to allow user to perform different actions in minimum number of clicks. There are several perspectives available.

While working with API, various entities within the system, such as merchants, resellers, etc, need to be referenced. API fields that correspond to the references to these entities are of the Reference type (for example, accountId, terminalId, etc). Each of these entities has two identifiers:
— Internal identifier (represented as ID) - numeric value, provided by the gateway; unique within the system.
— External identifier (represented as code) - alphanumeric value up to 60 characters, provided by an integrated external system for cross-referencing; preferably unique within the scope that makes sense to an integrator.

When an API call with reference to an entity has to be submitted, this entity can be referenced by either internal or external identifier. By default, the system expects an internal identifier to be submitted (e.g. accountId/merchantAccountCode=1234). To let the system know that an external identifier is submitted, its value must be preceded by an asterisk (e.g. accountId/merchantAccountCode=*1234). This is applicable to all fields of Reference type.

For example, an account has an internal ID, generated by the gateway (e.g.5678), and an external ID, provided by an integrated POS system (e.g. pos8765). If an internal ID should be used in the API calls, it is submitted via accountId field as it is: accountId=5678. If an external ID is used should be used in the API calls, it is submitted with an asterisk as a prefix: accountId=*pos8765.

Remittance is the process during which the funds are disbursed back to a merchant.

After all transactions are processed and settled for a given time period, statistics is calculated capturing the processed volume as well as transaction counts by type (e.g. Sale, Credit) and by payment source (e.g. Visa, Amex, direct debit). During the remittance process, a fee structure (Merchant Fee) is applied to the calculated statistics to obtain specific charges that the merchant owes for processing and support services. The resulting fees, as well as any appropriate reserves, are subtracted from the total volume processed and the net amount is remitted to the Merchant as either an direct debit transaction (when done automatically) or as a check (when done manually).

Depending on the specific business needs, remittance may occur on all transactions or only on a subset of transactions (e.g. batch only or real-time only).

Security mechanism is a system of elements allowing to control how users can access the system as well as perform different tasks. User access is defined through three aspects:
— Actions - deals with actions that a user can perform within the system. For example, access different perspectives and forms and perform tasks within these forms. This is controlled by privileges, permissions and access levels.
— Data access - deals with data that a user has access to, for example, data associated with a particular merchant, reseller, etc. This is controlled by data access policy.
— Functions - deals with functions that a user can fulfill within the various business processes implemented in the system. This is controlled by function policy.

Statement is a summary of merchant’s or reseller’s activity, including transaction processed, reserves withheld and fees applied. Statements are divided into two principal groups – merchant statements and reseller statements. Reseller statement is a breakdown and explanation of reseller’s commissions. Merchant statement is a breakdown of merchant's fees and explanation of deposits that are sent to a merchant. Merchant statements can be of two types:
— Deposit statement - a merchant statement that accompanies and explains remittances associated with all of the merchant’s batches processed on a given business day. Basically, deposit statement enables merchant to understand the deposits in their bank account that result from transaction processing.
— Reconciliation statement - a summary statement that explains remittance activity and shows all of the associated processing fees over a defined time period, usually a month. Basically, reconciliation statement helps merchant to understand what merchant fees are charged and why.

A collection of transactions that are processed together. Batch is part of batch processing, which is used in two situations:
— Real-time batches - used for the settlement of pre-authorized transactions.
— File batches - used to process together card-not-present transactions (authorization and settlement) of recurring nature, such as bill payments, subscription payments, etc.

Submission of a collection of transactions associated with a particular merchant account provided in a single batch file.

Chargeback is a financial mechanism allowing a cardholder to dispute over a particular amount of money that has been charged illegitimately or as a result of an error. The card association makes the crucial decision of this case. If the cardholder disputes successfully, the particular amount of money is withdrawn from a merchant's bank account and returned to the cardholder, but this decision can be overruled through an arbitration process. Notwithstanding whether the decision is made in favor of the cardholder or a merchant, chargeback fee is applied.

A merchant's rate of chargebacks affects the transaction processing of the merchant. If it exceeds 1%, the merchant gets on Terminated Merchant File and loses the ability to process transactions.

Convenience fee is a transaction that represents a charge in addition to the original transaction amount for convenient use of a credit card. In most cases, it is a surcharge that is generally kept by a service provider that facilitates the payment (payment gateway, processor, etc). Convenience fee handling can be performed in two ways:
— when merchant funding is handled by the payment gateway or by the system that processes the transaction;
— when funding is not handled by the system that processes the transaction.

Convenience fee can be represented in three ways:
— a fixed amount;
— a percentage of the principal transaction amount;
— a combination of fixed amount and a percentage of the transaction amount.

Unlike payment card transactions, a direct debit transaction cannot be approved in real-time by a bank. The process of obtaining a valid response may take from 1-2 business days to 2 months. If a bank cannot process a particular direct debit transaction, the transaction gets declined. Depending on a reason, the decline can be of two types:
— Soft decline - a transaction request was declined, but a subsequent request may result in approval. For example, a fitness club charges its member on monthly basis, but the bank notifies the merchant about insufficient funds on the member’s bank account.
— Hard decline - a transaction request was permanently declined. For example, a fitness club charges its member on monthly basis, but the bank notifies the merchant that the bank account was closed by the member.

Merchant gets notified about direct debit declines via direct debit return that is a bank-initiated transaction, which communicates a negative outcome of a previous attempt to transfer money using a bank account. In the gateway, direct debit returns are delivered to a merchant in returns files that are generated once per day and contain not only direct debit returns but also chargebacks/reversals and results of the automated retry process (approvals/declines that occurred during a day).

To remain compliant with PCI requirements, sensitive data, such as terminal keys, payment card numbers and bank account numbers, must be encrypted. In the gateway, sensitive data is always encrypted by HTTPs protocol. However, to ensure security, data can be additionally encrypted using one of the encryption algorithms. The following encryption algorithms are supported within the gateway:
— Symmetric encryption algorithm (AES/3DES) - algorithm where one key is used both for encryption and decryption of data. It can be used for PIN, session and P2PE keys.
— Asymmetric encryption algorithm (PGP/RSA) - algorithm where two separate keys are used for encryption and decryption of data. Data is encrypted using a public key and decrypted using a private key. It can be used for encryption of fields within real-time API calls and batch files.

When the hosted payment page (HPP) mechanism is used for transaction processing, all HPP files are located in the folders associated with a merchant/account. The name of the folder corresponds to the ID of the merchant/account. Each folder can be identified in two ways – via the ID of the merchant/account or a code that is generated automatically when the merchant/account is created. This code is a masked value and is called a folder code. It allows for an account ID to not be revealed in the HTML code of a page.

For more information about the usage of a folder code, review Customization Rules under the Hosted Payment Page section of the Processing Management guide.

Host emulator is an internal emulator of transaction processing used for integration testing with the gateway. It emulates particular responses depending on the incoming parameters. For example, depending on the amount used in a transaction, it can generate approval or decline for a transaction.

Information held on file about a customer that makes it possible to identify this customer as a specific individual/organization.
Personal data may include names, contact information (address, email, phone number), SSN, tax ID, etc. It is recommended to avoid unnecessary copying, replication, and distribution when handling personal data (e.g. logging, backups creation in other environments).
It’s acceptable to store personal data in an unencrypted format. However, it should be transmitted encrypted.

A separate entity within the gateway that represents a group of resellers and merchants, to which a certain common set of rules and configurations can be applied. Most commonly used in the following cases:
— as a container for grouping of merchants and resellers based on some meaningful criteria (by lines of business, by country);
— as a virtual machine that allows providing a white-label payment gateway solution to outside companies (as tenants) using a single gateway deployment (shared database).

The system is designed using processor-agnostic architecture to process and persist information about transactions. In this architectural solution, transactional information is maintained on two levels:
— High level – contains all of the transaction fields that are not processor-specific.
— Low level – contains all of the high-level fields in the processor specific format and processor-specific fields.

Every time a transaction is processed, series of processes get executed to translate the transaction from high level to low level and generate a processor-specific message and to parse the response and transform it back to the high level. The processes go as follows:
— Transformation - the process of translating high-level entities into low-level entities; a transformation from the system’s processor-independent format into the processor-specific format of transactions.
— Generation - the process of generation of a processor-specific message from low-level transactions.
— Upload - the process of uploading a file to the processor in the processor-specific format.
— Download - the process of downloading the result file from the processor in the processor-specific format.
— Parsing - the process of parsing processor-specific message which includes extraction of data used to form low-level processor-specific response entity.
— Backward Transformation - the process of translation of low-level processor-specific entity into a high-level processor-independent response.

This architecture allows support of multiple independent processors with a single API (point of entry).

An external system that provides services to the gateway (transaction processing, tokenization, 3D secure, emailing services, etc) through an exchange of files or API messages. Examples of providers are credit card processors and networks, direct debit bank systems, print houses, bulk email service providers, credit bureaus, etc.

The process of transaction processing that involves a transaction submission and returning of an immediate response.

Submission of a collection of realtime transactions received within a particular period of time, for an associated account. A new RTC is created when all previous cycles close for that account, and a new transaction is received. Realtime transaction cycles are closed with settlement, when pre-authorized transactions are settled and approved for funding.

Represents a recipient of a commission generated by gateway as a result of transaction processing. It can be used to identify sales people, resellers, referrers, etc.

Reserve is a pool of money that is maintained to minimize the risk of financial fraud for 3rd party processors. The system can maintain up to 3 reserves, which are dynamically adjusted every time a remittance process occurs based on the rules below:
— Refund Reserve – the reserve limit is set manually from UI; merchant is allowed to issue refunds against this reserve. A refund amount exceeding the reserve limit will get automatically declined. Trusted merchants can be granted unlimited refund capability. In this case, the reserve has to be disabled.
— Chargeback Reserve – the reserve is calculated automatically based on sliding window measured in days. The size of the window (in days) can be defined for each Merchant. The reserve is set to the percentage that declines represented with respect to the total amount of transactions processed. The reserve is used to cover potential chargebacks. The amount of the reserve is calculated following the above rules. Minimum reserve amount can be defined and will be maintained by the system. The reserve is increased or decreased based on volume, however, the reserve will not be decreased if the Merchant had a negative balance (prior to reserve adjustments) on the last remittance.
— Return Reserve – the reserve is calculated automatically based on sliding window measured in days. The size of the window (in days) can be defined for each Merchant. The reserve is set to the percentage that direct debit represented with respect to the total amount of transactions processed. The reserve is used to cover potential direct debit returns. The amount the reserve is calculated following the above rules. Minimum reserve amount can be defined and will be maintained by the system. The reserve is increased or decreased based on volume, however, the reserve will not be decreased if the Merchant had a negative balance (prior to reserve adjustments) on the last remittance.

For example, a sliding window is set to the period of 30 days, the total amount of transactions processed within this month is $10 000 and $1000 of them were declined (10% of the total amount), the reserves rate will be 10% correspondingly. When a new batch is processed, the total volume of successfully processed transactions (declined transactions are not included into reserves calculation) is $9000. According to 10% reserves rate, applied to these funds, $900 will be withheld into reserves. If for this batch the reserves amount is higher than the corresponding amount for a previous batch, then the difference is withdrawn from a merchant to reserves and in case this amount is lower, the difference is returned to a merchant from reserves. In case the pre-defined minimum reserves amount is higher than the amount of 10%, the minimum amount will be withheld into reserves. This calculation schema is applied to all types of reserves, maintained by the system.

Reversal is a financial mechanism used to notify a merchant that a disputed chargeback has been temporarily ruled in merchant's favor. The decision can be further appealed by cardholder and resulted in subsequant orbitration process.

In the context of marketplaces, a merchant needs to split a transaction amount between itself and several recipients. In the gateway, this process is realized through the split payments mechanism that implies distribution of the transaction amount between the merchant and its affiliates according to particular split rules, for real-time and batch transactions. These rules can be specified within a transaction either as embedded or a predefined split schema. Transactions with split payments can be created based on the items and may either include items or not.

The split payments mechanism involves two phases: transaction processing and remittance. During the transaction processing, a real-time or batch transaction is made. The amount of the transaction is distributed between the recipients based on the split rules. All the amounts intended for the recipients are recorded and split-in/split-out transactions are generated.

During the remittance phase, the funds are transferred to the recipients. The process is based on the balance tracking mechanism that keeps a record of merchants’ and affiliates’ debts and is activated only after the system calculates the amount processed by the merchant. The merchant who has processed the transaction is the one who is responsible for all the calculations with the gateway - fees, commissions, refunds, chargebacks, etc. This merchant is referred to as the merchant of record.

In the real world, a charge collected by the company interacting with groups of merchants. For example, a corporate office and its franchisees paying for the ability to run a ready-to-use business model.

In the gateway, a mechanism allowing to submit a list of charges within a charge file for a subsequent withholding as a result of remittance. Charges are typically withheld as a deduction, but can be withheld as a withdrawal as well, by the entity that has submitted the charges. A charge withheld from the merchant gets included to the merchant statement and can be reviewed in the “Сharges” section. The information about the charge that has been collected on behalf of the reseller gets included to the reseller statement along with its commissions and can be reviewed in the “Сharges” section. To learn more about merchant charges, review Merchant Charges section of the Remittance Management Guide.

When it is needed to distribute the transaction amount between several recipients, split rules are used.

Split rules are the rules that control how funds should be distributed between recipients. When the rules are embedded, they are available only for real-time API transactions and are specified by a submitter in real-time while making a transaction. When the rules are set as a predefined split schema, they are available for both real-time and batch transactions and should be created in advance of use.

A predefined split schema is a split rules template that sets the scenario for funds distribution between the transaction participants. The template can only be created via the API and is primarily used in situations when the same split rules are repeatedly used or batch processing is required.

In the gateway, each split schema has a particular identifier that can be either internal or external. The internal identifier is a unique value that is assigned by the system and submitted via the split schema id field in API or the user interface. The external identifier is an identifier submitted via a split schema code, a code that is assigned by a submitter within the system. To learn more about the differences between internal and external identifiers and the ways of submission, review Reference Field Type term.

After a transaction was split, to keep record of the flow of split payments between merchants and affiliates, additional transaction types are used.

For sale transactions:
— Split-in transaction - a transaction generated in the context of the split payments functionality based on a sale transaction, which creates a record that an affiliate has received the commissions as a part of the original sale transaction processed by a merchant. On the user interface, a split-in transaction is always displayed with “+” symbol.
— Split-out transaction - a transaction generated in the context of the split payments functionality based on a sale transaction, which creates a record that a merchant, that processed the original transaction, has transferred the commissions to an affiliate. On the user interface, a split-out transaction is always displayed with “-” symbol.

For credit/chargeback/return transactions:
— Pull-in transaction - a transaction generated in the context of the split payments functionality based on the credit/chargeback/return of the original transaction and creates a record that the merchant has received the commissions, previously charged via split-in, from the affiliate.
— Pull-out transaction - a transaction generated in the context of the split payments functionality based on the credit/chargeback/return of the original transaction and creates a record that the affiliate has transferred the commissions, previously charged via split-out, to the merchant.

These transactions are always generated in pairs. They exist as records in the system and do not influence the settlement process that occurs on the processor side. In other words, the processor processes only the information submitted within the original transaction with no splits.

Submitter is a software platform, integrated with the gateway via API. For the integration of submitter within the gateway, service user is used. To learn more about service users, see Security Management Guide.

Gateway provides a simple and convenient tokenization mechanism for merchants that deal with recurring payments and want to avoid storage of customer’s payment information (credit card and bank account numbers) within their own system. When a merchant uses any given credit card or bank account for the first time (as part of sale-auth, sale, credit-auth or credit operation), gateway will generate a unique identification number (token) associated with this payment information. If in the future, the merchant wants to issue another operation (e.g. another sale) on the same credit card or bank account, it is sufficient to pass to gateway just the value of the previously generated token and omit all of the account information fields.

An action between a cardholder and a merchant that results in activity in the cardholder's account and/or merchant's balance (for example, sale, credit, chargeback, etc) or non-financial transaction which is a record that registers the transaction that was processed by the internal system or other information that does not have financial implications (for example, activation/deactivation/transfer for gift cards, account verification, etc).

Each transaction can be characterized by its type, status, state, and origin.
By type, transactions are divided into two major groups: financial and non-financial. Financial transactions, in contrast to non-financial, imply a transfer of funds that affect customer’s and merchant’s balances.
When submitted for processing, a transaction obtains one of the following statuses: pending, processed, canceled, in rebill (submitted for retry). Depending on the gateway’s and processor’s response, a transaction can be in one of the following states: approved, declined, blacklisted, voided, error.

Transaction processing is a process, by means of which electronic payments are executed. Transaction processing mechanism involves two principal phases: processing and funding. During the processing phase transactions are processed and funds are authorized through gateways, processors and card associations. During the funding process the actual money transfer is happening and funds are deposited into the bank account belonging to the owner of the account, on behalf of which transactions are authorized. The funding process itself can occur in two ways:
— funds are transferred directly to the merchant;
— funds are transferred into an intermediary account usually belonging to a 3rd party processor that functions as an agent on behalf of the merchant.

Regardless the type of funding process involved, the Remittance process is necessary to complete the funding cycle. When the 3rd party card processor is involved in the funding cycle, Transaction Aggregation Mechanism is necessarily employed to manage flow of funds.

The use of aggregation can either be explicit or implicit. In the explicit use of aggregation mechanism, a single deposit account of a 3rd party processor is used to receive all deposits across all of the merchants that process through it. In the implicit use of aggregation mechanism, each deposit will go into a specially designated deposit account associated with a merchant, but all of these accounts will be created as subaccounts of a single sweeping account under the name of the 3rd party processor.

Verification is a process of confirmation of totals within a particular batch file. It is submitted to processing to a third party such as bank or processor.

Verification information can be submitted in three ways:
— via a phone call to the bank – gateway owner makes a call to provide file totals;
— via an email notification sent to the bank – gateway sends an email with file totals that is automatically generated by the gateway;
— via a file generated and uploaded to the bank – gateway generates a verification file and uploads it to the bank’s SFTP.

Wire is an operation of transferring funds between accounts. In the real world, a wire is an electronic money transfer from one account to another. In the gateway, it is a manual transfer of funds from a payment facilitator to a merchant's account.

A set of configuration settings that should be set up in the gateway before starting to use the recurring billing module.

Mechanism that allows to track the customers having a positive balance, notify them about their debts, monitor the process of debt recovering and reporting their debts to a collections bureau agency.

An individual who purchases a subscription to a merchant’s goods/services and pays for them either through the gateway or through an external system (for example, a terminal not integrated with the gateway), in cash/by check.

Pricing plan, which determines how often and how much a customer has to pay.
Billing frequency is defined in billing cycle parameter.

Payment that must be performed in the future but is not included in the current payment plan of a customer. For example, it can be represented as unscheduled dues.

Customer’s subscription to a specific pricing plan that represents a commitment to pay a specified amount of money regularly to receive a product or service.

Since a significant number of terminals are located remotely, there is a need for both remote and centralized terminal management. For this purpose, the Terminal Management System (TMS) is used. The TMS is a module within the gateway that allows a user to control and manage processes in a terminal. Examples include (but are not limited to), initializing parameters, recording logs, and updating general configurations such as EMV configurations, encryption keys (not all keys can be updated) and terminal software (operating system and payment application).

A process of terminal applications change to a more up-to-date version with fixes and added features is called a terminal update.