for developers and administrators
User Interface Reference
Resources (Directory Structure)
Zip and Country Codes
Supported Providers (Banks & Networks)
UniPay Codes & Code Mappings
Integrated 3rd Party Libraries
Diagrams and Documents
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.
Branding profile is a set of forms, associated with a particular merchant, reseller or portfolio, that allows for configuring of particular branding elements. A branding profile is used to create a unique visual representation for communicating between entities that are familiar with each other. For example, merchants need to see a logo and colors of a reseller they are associated with. The gateway provides the ability to override settings of a default system branding profile. This can be done via the overriding mechanism that allows for creation of a unique branding profile at the corresponding level within the gateway. The branding profile can consist of branding elements set at a particular level only or it can combine these elements with those set at a higher level.
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.
Account is a subunit of a merchant that represents a unit of a business (location, club, store, department). Used to subdivide data and override global processing settings defined at the merchant level.
A set of configuration settings that can be defined at either merchant or account level. Includes settings related to remittance and commissions.
A set of configuration settings that can be defined at either merchant or account level. Includes settings related to transaction processing.
Account profile groups different provider profiles that define processing policy with a corresponding provider.
The text that appears on a customer's billing statement and indicates what company charged the customer's card and why.
There are two common ways through which the acquirers can accommodate descriptor functionality:
— Static descriptor - associated with the merchant ID. This means that one merchant ID corresponds to one descriptor. All transactions processed through a given merchant ID bear the same descriptor.
— Dynamic descriptor - specified at the transaction level, i.e. different transactions with different descriptors can go through one merchant ID. Even though the same merchant ID is used for all transactions, each transaction can have its own descriptor.
A set of days within a month (1-28) when a reconciliation process for a merchant has to be run. The Reconciliation Merchant Statement is generated at this time. Multiple days per cycle can be selected, but only one day will be used to process monthly fees.
Merchant cycle is used in two fee types: demand-cycle and cycle-cycle. See
for more information.
Merchant fee is a fee (processing rates, service fees, etc) associated with a merchant. Defines how deposits and fees should be calculated based on the transactions processed. Fees can be paid to the gateway or a software platform/reseller.
1) Gateway fees:
— Processing fees - fees charged for transaction processing. They are subsequently subdivided into volume fees and per item fees. Volume fees are charged based on total volume (total amount) of transaction processed, while per item fees are charged on per transaction basis (total count). When blended rate pricing model is used, these fees reflect the actual processing fees charged to the merchant; when cost-plus pricing model is used, these fees represent the surcharge, which is applied on top of the processing cost.
— Flat fees - additional charges applied to certain types of transactions, usually either to cover corresponding processing cost (chargebacks, direct debit returns) of these transactions or to cover additional services rendered specifically for these transaction types (decline, recycle).
— Monthly fees - recurring fees charged on a monthly basis to cover various types of service charges, hardware cost and support.
— Annual fees - recurring fees charged on a yearly basis to cover various types of service charges, hardware cost and support.
2) Software platform/reseller fees:
— Charges - fees charged on a regular basis to cover specific types of services, most typically franchising fee. See
for more information.
Fee Type determines the timing on remittance deposits associated with processing. It determines when the funding of transactions happen and then, based on which schedule, processing fees are taken out.
The name of fee type consists of two parts. The first part of the name relates to deposits of a merchant, whereas the second part of the name relates to fees.
Possible fee types are:
— Demand-demand - first part
means that deposit is made fixed numbers of business days (waiting period) after processing happens, and the second part
means that fees are taken out at that particular time (deposit is made net of fees). For example, $100 is processed on Monday with 5% processing fee and two-day waiting period, thus funds are deposited back to the merchant on Wednesday net of fees in the amount of $95. The idea is that deposit and fee are both made two days after the processing where fee (5%) has already been taken out as a result deposit equals $95. The advantage of demand-demand is that PSP/TPP is guaranteed to always be able to collect processing fees.
— Demand-cycle - first part
means that deposit is made fixed numbers of business days (waiting period) after processing happens, and the second part
means that fees are taken out on the specific day of the cycle. For example, $100 is processed on Monday with 5% processing fee, the waiting period is two days and cycle day is the first of the month, thus funds are deposited back to the merchant on Wednesday in the amount of $100, while fees ($5) will be taken out on the first of the subsequent month.The advantage of demand-cycle is that it simplifies the reconciliation process for a merchant because the amount of funds processed equals the amount of funds received. However, it introduces potential risk for PSP/TPP which is an inability to collect processing fees due to Merchant's lack of funds at that particular time.
— Cycle-cycle - both parts of the name imply that Merchant gets funds net of fees on the predefined day of the cycle despite the processing time of a given transaction. It's often used in collections industry so that regardless of when funds are processed, deposits happen on the first and the fifteenth of the month net of fees. For example, assuming 5% processing fee and cycle day is the first of the month regardless of when $100 is processed, $95 will be deposited on the first of the subsequent month.
Pricing model is a way to organize and charge
s to a merchant.
The system supports two fundamental pricing models:
— Blended rate - fees are determined by averaging of processing cost across different interchanges and transaction types. For example, Visa Debit card might cost 0.6% to process and Visa Reward card might cost 2.8%, so the blended rate might be set at 2.7%. Processing cost is not defined as an exact amount and is included in total processing cost in the statements. In the settings, processing cost is set as
— Cost-plus - processing cost is passed along to a merchant with an additional surcharge on desirable transaction types on top of the actual cost. For example, assuming surcharge of 0.5%, Visa Debit transaction qualifying for 0.6% will be charged at 1.1% and Visa Reward transaction qualifying for 2.8% will be charged 3.3%. Processing cost is defined as an exact amount that is paid to a processor and is displayed in the statements along with processing fees for certain transactions. In this case, processing cost should not be set as
Merchant profile is a set of parameters that are used to govern the setup of a merchant with the respect to its accounts, merchant IDs, descriptors and deposit accounts. It includes five parameters, defining of which determines how the merchant/account should be configured.
Accounts - defines whether it is a multi-location/multi-terminal or single-location/single-terminal merchant.
— Single - settings are configured at the merchant level.
— Multiple - settings are configured at the level of each account that is set up.
Underwriting - defines whether a single federal tax ID is going to be used for all locations of the merchant or each location is going to use a separate tax ID.
— Single - the legal entity owning the tax ID is represented by a merchant. Underwriting (background verification) is done at the merchant level.
— Multiple - the legal entity owning the tax ID is represented with an account. Underwriting (background verification) is done at the account level.
Processing - defines whether a single provider profile is going to be used for all locations of a merchant or each location is going to use a separate provider profile.
— Single - one provider profile is used for all accounts under a merchant, i.e. the provider profile is set at the merchant level.
— Multiple - different provider profiles are used for each account under a merchant, i.e. the provider profile is set at the account level.
Remittance - defines the number of deposit accounts to use for remittance.
— Single - remittance settings are configured at the merchant level. All money are funded to a single deposit account regardless of the number of accounts used.
— Multiple - remittance settings are configured at the account level. Money processed by each account is funded separately in separate deposit accounts.
Recurring fees - defines how the monthly fees are charged.
— Per Merchant - monthly fees are only charged once regardless of the number of the accounts under a merchant.
— Per Account - monthly fees are charged per each of the account created under a merchant.
In order to process transactions and do remittance, the following configuration sets are available within the system:
— Processing settings - define how transactions are going to be processed. These settings include configurations of provider profiles as well as various types of settings around the settlement, cut-off time, etc that are going to be used for transaction processing.
— Remittance settings - define how remittance and merchant funding are going to be done. These settings include deposit account information, reserves, merchant fees, etc.
Depending on the business context, both groups of settings can be configured at either merchant or account level.
Merchant statement is a summary of merchant’s activity over a certain period of time. It provides the information about a number of the processed transactions, splits, fees and charges collected and adjustments applied.
Merchant statements can be of two types:
— Deposit statement - a type of merchant statement that accompanies and explains remittances associated with all of the merchant’s transactions processed on a given business day. Deposit statement helps the merchant to understand the deposits in its bank account that result from transaction processing.
— Reconciliation statement - a summary statement that explains merchant’s remittance activity and shows all of the associated processing fees over a defined time period, usually a month. Reconciliation statement helps a merchant to understand what merchant fees are charged and why.
Adjustment is an element of a merchant statement that allows manual adjustments to the current statement balance. It can be used to rectify statement errors that resulted from exceptional business behavior, waive fees or withhold additional fees that do not generally appear on the statement.
Scheduled adjustment is used to manually adjust amounts within the future merchant statements. Scheduled adjustment has a fixed date in the future when it is applied to the newly generated statement.
It can be created for cases when a gateway owner desires to make a planned adjustment to a merchant statement. For example, if a merchant requests an advance, the gateway owner can provide it and create a scheduled adjustment to withdraw it back in two weeks.
If there is no statement generated on the date of the created adjustment, this adjustment will be applied to the next generated statement.
Merchant Tier Structure
From the transaction processing perspective, a business of a merchant can be organized as a single-tier, two-tier and three-tier hierarchy. The configuration of the given merchant in the system is going to depend on the tier structure of the merchant’s business:
— Single tier - an example of a single-tier merchant would be a single-location store with one cashier and one terminal. Another example is a website or an online store, which handles all of the processing in the same way.
— Two tier - an example of a two-tier merchant would be either a single-location store with multiple cashiers and terminals or a multi-location store with a single cashier and terminal in each of them.
— Three tier - an example of a three-tier hierarchy would be a multi-location supermarket with multiple cashiers and terminals in each location.
There are two objects within the system used to represent various tiers of the merchant’s business:
— Merchant - parent entity that groups several accounts together.
— Account - child of a merchant, representing a unit of a business (location, store, department) or a terminal.
In the one-tier scenario, the merchant is going to represent both the business itself and its single terminal (when applicable).
In the two-tier scenario, the merchant/account combination can be the following:
the merchant represents a store/location and the account represents a cashier/terminal
the merchant represents a corporate entity owning the stores and the account represents each of the stores/locations.
In the three-tier scenario, the merchant is going to represent a corporate entity owning the stores and the account is going to represent both stores/locations and terminals within these stores. For example: if there are three stores each having 4 terminals, there will be a total of 12 accounts set up.
The following merchant types are supported within the system:
— Remitter - reserved/system merchant; used to define direct debit settings for fund remittance in cases when an aggregate model is used.
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
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.
Onboarding application is a specific form that allows onboarding of a merchant within the gateway via the onboarding API. The application is designed for external companies to board associated merchants. The application collects all necessary information that is further submitted to a processor that performs onboarding. The response to the onboarding request can be delivered in real-time or via a callback, which is subject to the processor.
To avoid a merchant’s fraud, a processor, through which the merchant is going to perform transactions, needs to know an annual volume and amount of transactions as well as a maximum amount of a single transaction that the merchant is going to process. This information is called
. 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.
As part of the onboarding process, a series of checks is performed. These checks allow a merchant to obtain a MID and/or a merchant account. This process is called
, and without verification, a PSP is not allowed to assign MIDs to its merchants. During verification, the merchant is checked whether there are any issues with the business or its owners, such as bad credit history, previous bankruptcy, law issues, presence on the federal terrorist list of OFAC (Office of Foreign Assets Control), and/or the Visa/MasterCard MATCH list. As a result of verification, a response determining whether the merchant can process transactions and receive money in its account is returned. Underwriting can be performed either by a processor during onboarding or by outside services.
A high-level management executive hired by the company’s owner or board of directors that manages the business operations on a daily basis. For example, chief executive officer (CEO), chief financial officer (CFO), treasurer, president, vice president. Depending on ownership structure type, officer can be one of the business owners.
An individual who owns a company by holding a stake in the business.
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.
Administration is a group of perspectives designed to manage the application by system and software administrators.
Audit perspective is an arrangement of forms and actions used by technical administrators of the system. The purpose of this perspective is to monitor activity on the server. It groups together most common forms that are necessary to analyze different types of activity in the system, to review errors, to detect changes to merchant, reseller, user information, etc.
Monitoring perspective is an arrangement of forms and actions used by non-technical administrators of the system. The purpose of this perspective is to simplify diagnostics of various remittance and processing related issues. It groups together most common forms that are necessary to diagnose various problems that may occur within them.
Setup perspective is an arrangement of forms and actions used by non-technical (business-oriented) administrators of the system to manage setup of various system-wide settings.
System perspective is the arrangement of forms and actions used by technical administrators to manage setup of various system-wide settings (these settings are more software and hardware-related than business-related).
Console is a perspective that is designed to function as a virtual terminal for merchants. The purpose of this perspective is to provide easy access to the information that merchants most commonly require for their business, such as access to transactions, chargebacks, batches, statements, as well as recurring billing functionality (if the recurring module is activated within the system).
Management is a group of perspectives designed to streamline back-office operations. It is generally used by the employees of the payment service provider that maintains the gateway. It provides easy access to functionality for the management of mer
Distributions perspective is an arrangement of available forms and actions that are needed to provide access to the common functionality of distribution recipients such as vendor or holding account.
Fulfillment Perspective is an arrangement of available forms and actions that are needed to set up terminal configurations, work with users' terminal orders, control and modify shipping conditions, set up injection keys and regulate terminal modules available for fulfillment.
Merchant Perspectiveis an arrangement of available forms and actions that are needed to work efficiently with Merchants and Accounts. In this perspective availability of actions changes based on Merchant Selection. User can work either with Merchant or one of its Accounts. For more information see
Merchant Selection is a group of Merchants or Accounts("Submerchants") against which operations can be performed under
. It operates using three modes:
— Multiple - mode that allows user to work with selected Merchants and their Accounts at the same time.
— Merchant"M:" - mode that encompasses actions that can be carried out only with one selected
— Account"A:" - mode that allows user to work only with particular
In addition, modes influence availability of functions on the Merchant Perspective. The full availability is accessible while using Merchant mode.
Portfolio perspective is an arrangement of available forms and actions that are needed for managing information about resellers, merchants, documentation, etc.
Reseller Perspective is an arrangement of available forms and actions that are needed to work efficiently with
Terminal perspective is an arrangement of available forms and actions that are needed for storing of the information, parameters and resources associated with terminals owned by a particular merchant, managing updates (Terminal Management System), and monitoring and saving logs.
User Perspective is an arrangement of available forms and actions that are needed to work efficiently with User records.
Reporting perspective provides access to the reports available within the system.
Reference Field Type
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
type (for example, accountId, terminalId, etc). Each of these entities has two identifiers:
— Internal identifier (represented as
) - numeric value, provided by the gateway; unique within the system.
— External identifier (represented as
) - 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
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
field as it is:
. If an external ID is used should be used in the API calls, it is submitted with an asterisk as a prefix:
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 (
) 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).
After a transaction has been processed via the gateway on behalf of a merchant, it has to receive the money as a result of transaction processing. To have the funds transferred to the merchant, a payment facilitator needs to have the credentials of the merchant's bank account to make a direct deposit. These credentials are called
and usually include the following information:
- Bank Name - name of the bank where the merchant account is open.
- Bank Phone - phone number of the bank where the merchant account is open.
- Holder Name - name of the account holder associated with the merchant's account.
- Account #- number of the merchant's account.
- Routing # - routing number of the bank where the merchant account is open.
Remittance mechanism is necessary to transfer funds from the intermediary 3rd party processor account into deposit accounts belonging to the actual merchants. Because of the processor-dependent funding delays and because of the necessity for reconciliation and auditing procedures as part of the whole process, arbitrary time delays may be introduced in the remittance process (e.g. funds can be remitted back to a merchant one or two days after the 3rd party card processor receives the funds). These time delays can be defined based off different remittance basis, with a starting date as the date of approval response (response date basis) or the date when funds arrive (funding date basis).
Working off of the response date, remittance of funds occurs pre-defined number of days after approval is received from the processor, while working off of the funding date, remittance of funds occurs pre-defined number of days after funds are received from the processor. The pre-defined, fixed number of days is called remittance period.
Depending on remittance basis used, values for direct debit, Credit Card and Amex remittance periods may vary. They may be used to provide additional time for reconciliation and auditing, as well as, to delay or advance certain types of deposits (e.g. delay direct debit or advance Amex) to unify all remittances into a single deposit.
Remittance source is a bank account from which funds for specific types of transactions will be remitted. The notion of remittance source is designed to accommodate scenarios when single merchant processes through multiple processors and each of the processors deposits to a separate bank account. For such cases, when remittance process occurs money has to be pulled from different accounts.
Gateway supports four types of remittance sources (bank accounts that could be used as the source of funds): one for credit and debit card deposits, one for direct debit deposits, one for American Express deposits and one for commission remittances.
Remitter is a specifically configured merchant that performs remittance processes. Remitter's account contains settings of particular bank accounts. Funds are deposited to these bank accounts during the remittance.
are used, several remitter accounts have to be configured: for payment card, direct debit, American Express and commissions transactions.
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
— 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
Permission represents the ability to perform a particular action within the system on the lower level. A user with a particular permission can perform the corresponding action (e.g. view or modify the elements of the system or access different forms and do different actions within these forms). Permissions are associated with the security roles, allowing to control the access level of a particular user. They are also assigned to various elements of the user interface, defining what permissions will be nessesary for a user to have access to the forms and be able to execute the actions on the user interface or within the API.
Privilege represents the ability to access a particular API or gateway user interface. There are seven privileges that can be granted to the users in the gateway.
Privilege granted to human users (by default):
— User Interface – allows a user to access functionality of the user interface.
Privileges that can be granted to service users:
— Processing API - allows a user to access functionality related to transaction processing.
— Management API - allows a user to access functionality related to the settings setup of merchants, portfolios, etc. In addition, along with this privilege, a security role must be set up.
— Billing API - allows a user to access functionality related to reccuring billing.
— Onboarding API - allows a user to access functionality related to the onboarding application. This privilege is available only to the users that have an access to Processing API.
— TMS API - allows a user to access functionality related to the terminal management system: configuration changes, activation of the terminals, parameters setup, etc.
— Detokenization - allows a user to access functionality related to detokenization of the tokenized data present within the system. Although the privilege can be assigned to the service users only, the detokenization process involves both API and the user interface. Therefore, both service and human users are involved in the process.
Security role is a combination of
that are frequently granted to users collectively. Thus, when a user is created a particular role can be assigned instead of a large number of individual permissions.
In the gateway system, there are twelve security roles that belong to four groups (System, Portfolio, Reseller, Merchant, Customer). Security roles are organized hierarchically from
(the highest security level with the largest number of permissions) to
(the least number of permissions). To learn more about permissions based security mechanism, review
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.
A sub-group of transactions that a batch contains. Batch transactions are split into sub-batches by the system to meet the requirements of a particular processor for the following reasons:
— Quantity limitation for the transactions included in one batch. If a batch contains a number of transactions that exceeds the fixed limit, it is divided into several sub-batches. The maximum quantity of the transactions included in one file submitted to the processor is defined in
property of the corresponding Processing Profile. If a sub-batch file contains less transactions than set in the limit, one
is generated. In cases when a sub-batch contains a larger number of transactions, two or more
— The difference in how transactions are processed. For example, a batch may contain both direct debit and payment card transactions. In this case, sub-batches are created for processing to be properly performed within the system.
Currently the Processing Profile
setting allows to split batches by one or more of the following criteria:
by Industry Type;
by Transaction Mode (card present/card not present);
by Terminal Code (only for realtime transaction);
by OperationType ( sale/credit);
by Account Type.
Verification file is a file used for confirmation of totals within an associated batch file. The information is generally used by a bank to confirm the accuracy of a batch file that has to be processed. Verification file is used for processing of both batch and remittance files. Verification file is a part of verification process.
Batch Transaction Cycle
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.
Chargeback case is created as an addition to a chargeback, allowing to make a dispute for the chargeback. A chargeback case allows a merchant:
— to receive additional information about a chargeback from an acquirer;
— to provide an explanation necessary for representment of a transaction.
In cases when a processor does not provide the ability to handle disputing process, chargeback cases are not created automatically. In such cases, a merchant is expected to dispute chargebacks using either processor's specific portal or a hex number provided by a processor.
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.
Fee processor is a separate merchant used for processing of convenience fees. It is used in cases when it is desirable to process a convenience fee separately from the primary transaction, i.e. as a second transaction. Therefore, it contains the settings that are used to process the separate convenience fee transaction.
Direct Debit Return
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).
A bank account holder or its associated financial institution can dispute a merchant’s charge if a transaction was not authorized. In cases when the transaction is proved to be charged incorrectly, the merchant receives an unauthorized return. Unauthorized returns are classified as hard declines and may include one of the following response codes:
— R05 - Unauthorized debit to consumer account using corporate SEC Code.
— R07 - Revoked Authorization.
— R10 - Advised as Unauthorized.
— R29 - Corporate Entry Unauthorized.
— R51 - Item is Ineligible; Notice not Provided; Signature Not Genuine; Item Altered; Amount of Entry not Accurately Obtained.
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
key and decrypted using a
key. It can be used for encryption of fields within real-time API calls and batch files.
PGP is an asymmetric encryption algorithm that uses two keys: public and private. These keys are used for data encryption and decryption: sensitive data is encrypted using a public key and decrypted using a private key. Both keys are generated by the gateway administrator. Once generated, the public key is sent to all merchants that want to encrypt sensitive data with PGP. The corresponding private key is accessible only to the gateway administrators and is stored in a secure place within the server. For additional security, the private key is encrypted with a secret passphrase to ensure it is not compromised.
Within the gateway, PGP is used for encryption of sensitive data in real-time API requests and batch files as follows:
— Sensitive data in
real-time API requests
is encrypted on the merchant's side with a received public key via an external encryption application. After PGP encryption, the data must be URL-encoded and submitted for processing to the gateway. Once received, the information is decrypted using a corresponding private key and then submitted to a processor within a transaction. After the transaction is processed by the processor, the API response is sent back to the merchant without encryption since it does not contain any sensitive data.
— Sensitive data in
batch processing or account update request files
is encrypted on the merchant's side with a received public key via an external encryption application. After PGP encryption, the file is uploaded to the gateway either via the user interface or on the FTP-server directly. Once uploaded, the file is decrypted using a corresponding private key and then submitted to a processor. After the request file is processed by the processor, the response file is sent back to the merchant either with (account update response file) or without (processing response file) encryption.
— Sensitive data in
account update response files
is encrypted on the gateway side before being sent to a merchant because it contains card numbers. For encryption of account update response files, public and private PGP keys generated by the merchant are used. The public key has to be sent to the gateway administrator, and the private key must be stored in a secure place within the merchant's system. When the merchant's public key is received, the gateway administrator uploads it to a folder on the server and adds its name to the merchant's processing settings on the user interface. After that, all batch response files that contain sensitive data are encrypted automatically with the merchant's public key before being sent to the merchant.
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
. 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
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.
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
section of the Remittance Management Guide.
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 subset of personal data that can be used to carry out financial fraud including:
— personalized security credentials and encryption keys;
— raw account data (unencrypted credit card or bank account numbers);
— credit card expiration date and security (CSC/CVV) code;
— EMV tags and track data (as likely contain raw account data).
Sensitive data must be securely protected against unauthorized access. It is not recommended to display this data on the user interfaces (unless masked) and to log it. Sensitive data should only be stored and transmitted encrypted (if storage allowed).
It is strictly prohibited to store and copy sensitive data in paper or digital files (including emails, messages, audio files, and similar).
Raw Account Data
Unencrypted/untokenized credit card and bank account numbers.
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.
Subset of settings within a Provider Profile responsible for connectivity and secure communication with a Provider. These include URLs, login credentials, encryption keys, etc.
A set of settings necessary for the gateway to communicate with a 3rd party service Provider.
Providers, and their respective profiles, are divided into groups by the type of services provided to the gateway: batch processing, real-time processing, tokenization, account updater, chargebacks, 3D Secure, etc. Each group may include one or more service Providers (e.g. among processors you can have FirstData, Elavon, Tsys, etc).
Settings required by each type of profile and each Provider will vary based on the specific protocol used for the integration/communication.
Note that each profile has a corresponding integration within the gateway, which implements the protocol (API or file format) necessary to exchange messages with a particular Provider. The integration relies on the profile for merchant/portfolio specific identifiers (see External settings) and connectivity information (see Connectivity settings).
Provider Profile will generally include 3 groups of settings:
— Internal – settings controlling behavior of the gateway specific functionality, which is available for this type of Providers. For example, type of transactions or cards supported, number of attempts a rebill of a decline could be performed). These settings are never passed to the Provider.
— External - settings required by the Provider to identify the submitter (gateway in our case, as well as specific merchant and/or portfolio within) in their system. Common examples are MID, TID, BI).
— Connectivity – sometimes referred to as Provider Account; subset of settings responsible for connectivity and secure communication with a Provider. These include URLs, login credentials, encryption keys, etc.
The process of transaction processing that involves a transaction submission and returning of an immediate response.
Realtime Transaction Cycle
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.
Channel is an integration processed in gateway from the outside system or by it. Every channel has its particular ID, code and name and can be reviewed in corresponding portfolio.
Commission basis defines the basis amount off of which the commission is paid.
There are three bases possible:
— Total - commissions will be paid off of the total amount of specific
— Residual - commissions will be paid off of the
— Collected - commissions will be paid off of the net of fees collected, which is the total amount of
s collected minus the actual processing cost. It's only applicable for 'blended rate' pricing model (for more information see
A summary of activity for a Reseller for a set time interval that includes all information about the payments received for transaction processing of the merchants, associated with this particular reseller.
Residual is the difference between the fee paid by the
and the buy rate of the
that this Merchant is associated with. For example, if Merchant is charged 5% on the processing fee, the Reseller's buy rate is 3%, the residual is going to be 2% of the total transactions' amount.
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.
Split Payments Mechanism
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:
. 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.
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
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
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.
In the context of tokenization, there can be cases when a merchant needs to retrieve a payment card or bank account number from a token that is stored within the gateway. For example, a merchant, integrated with gateway, wants to make a payment on behalf of its client in a store that is not integrated with gateway and needs a live card number for that. For such cases, gateway provides ability to detokenize a token via detokenization mechanism.
Detokenization is done in two phases:
— detokenization request is submitted via the API call. For this purpose, a service user with a corresponding priviledge assigned is used;
— detokenization response is received via the user interface after a user gets re-authenticated and enters a token that needs to be detokenized. For this purpose, a human user is used.
In the context of tokenization, gateway provides ability to remove unused tokens from the gateway. This can be done via untokenization mechanism.
Untokenization can be done in one of two ways:
— Automatically - tokens are removed automatically after 365 days of inactivity.
— Manually - tokens are removed manually via the untokenization API call.
An action between a cardholder and a
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 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
Parameter that defines how the transaction was initiated.
From this point of view, transactions in the system can be of two types:
— transactions that come from the submitter and their respective responses - sale-auth, sale, credit-auth, refund, decline, blacklist, void;
— transactions that come from the processor – reversal, chargeback, return, notice.
When submitted for processing, a transaction can obtain one of the following states:
— Approval - transaction that has been processed successfully.
— Decline - transaction that got declined.
Note that due to specificity of processing flow of some payment providers,
state may be assigned to the transaction. Delayed decline is a successfully completed transaction subsequently declined by a processor after a certain period of time for a specific reason.
— Blacklist - transaction that has not been processed as the account is in the blacklist due to the previous hard decline.
— Blacklists are introduced to prevent problems induced by the fact that direct debit transactions do not get approved or declined in real-time like credit card transactions. To eliminate waiting for a certain direct debit return, every direct debit transaction is checked against a blacklist before it is submitted to the bank for processing.
— Error - transaction that has not gone through an internal validation of the gateway and has not been sent for further processing. The response code indicates the reason why the transaction was not processed.
— Void - transaction that has been reverted before settlement.
Note that the term
can refer either to transaction state or an operation that reverts the original transaction before it has been settled and cancels the transafer of funds from a customer’s payment card or bank account. No further action can be taken for a voided sale transaction.
The range of states that can be assigned to a transaction may vary depending on the transaction type.
Transactions are classified by their types. The following types are available within the system.
— Sale - operation used to withdraw a specific amount of money from a customer’s payment card or bank account charged by a merchant for the purchase of goods or services.
— Credit - operation used to deposit (return) a specific amount of money to a customer’s payment card or bank account without an original associated transaction.
— Sale-auth - sale transaction that requires an explicit capture in order for the money to be transferred to a merchant. To initiate settlement of sale-auth transactions that were processed with multiple capture processing mode enabled, capture operation is used.
— Sale-info/Credit-info - operation used to supply to the gateway information about a sale/credit transaction that has been processed within an external system. Often used to record the transaction for rewards balance of loyalty cards.
— Refund - operation used to revert settled sale transaction that means a transfer (return) of a specific amount of money associated with a particular transaction from a merchant’s account to a customer’s.
— Chargeback - operation used to reverse a prior outbound transfer of funds from a customer's payment card. A chargeback is initiated by the customer’s bank once the customer has successfully disputed one of the items on the transaction list.
— Reversal - operation used to reverse a payment card chargeback, i.e. money is given back to the merchant or customer.
— Return - direct debit payment that has not been honored by a bank.
— Reject - direct debit payment that has been rejected by a bank due to insufficient funds or errors in payment order.
Transaction types on the gateway user interface depending on the transaction state:
Transaction type/ Transaction state
applicable only for certain processors
Splits and Pulls
For sale transactions:
— Split-in - 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 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/refund/chargeback/return transactions:
— Pull-in - transaction generated in the context of the split payments functionality based on the credit/refund/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 generated in the context of the split payments functionality based on the credit/refund/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.
Splits and pulls on the gateway user interface depending on the transaction state:
Transaction type/ Transaction state
— Notice (notice of change) - direct debit transaction that is returned by a bank and notify that some details of the transaction were corrected.
— Inquiry (balance inquiry) - operation used to verify balance on debit, prepaid or gift cards.
— Verification (account verification) - operation used to verify that an account is active and to perform AVS verification without actual authorization.
— Fee (convenience fee) - operation used to calculate a surcharge to a cardholder to cover the cost of credit card processing.
For gift cards:
— Transfer - operation used to transfer a balance from one gift card to another.
— Activation - operation used to activate a gift card.
— Deactivation - operation used to deactivate an active gift card.
— Reactivation - operation used to reactivate a previously deactivated gift card.
— Create-alias - operation used to create an alias (token) for a gift card.
— Delete-alias - operation used to remove a previously created alias (token) for a gift card.
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
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.
Authorization is the first phase of payment processing. During the authorization process an acquirer contacts the appropriate payment network (Visa, MasterCard, American Express, ets.), then the payment network contacts credit card issuer to make sure the credit card is valid and there's enough available credit for the transaction. If the response is positive, the necessary amount of money is reserved for subsequent settlement and transaction gets approved, otherwise it gets declined.
Blacklist is a list of accounts that were previously processed and came back as irrecoverable (hard) direct debit returns. Irrecoverable direct debit returns include cases when an account is closed or invalid.
Blacklists are introduced to prevent problems induced by the fact that direct debit transactions do not get approved or declined in real-time like credit card transactions. To eliminate waiting for a certain direct debit return, every direct debit transaction is checked against a blacklist before it is submitted to the bank for processing.
Settlement, also referred as Capture, is the second phase of the payment processing, when the previously
amount is withdrawn from the card holder’s account and transferred to merchant’s account.
The general practice is to do this at the end of the business day.
There are two possible settlement mechanisms commonly referred to as terminal capture and host capture:
is used, the information about each transaction to include in settlement has to be supplied at the settlement time (generally through a settlement file).
is used, the underlying processing system (the host) keeps track of all of the transactions and it is usually sufficient to simply send a settlement message without including transaction details.
Processing Cutoff Time
The point of time when the realtime and batch transaction cycles are closed. This parameter is essential when the remittance is done by the gateway. Transactions settled in this time (in case of terminal capture) or by this time (in case of host capture) are
included in the merchant statement on the same day
and deposited to a merchant service provider.
Processing cutoff time must be earlier than settlement cutoff time to ensure that all transactions processed in the gateway during the day are included in one settlement cycle.
Settlement Cutoff Time
The point of time when the settlement cycle is closed.
Transactions processed before the settlement cutoff time are included in the
same day merchant deposit
, while the transactions processed later are included in the
next day deposit
. For example, supposing that the merchant has Next Day funding plan with the payment service provider and the cutoff time is set at 11 PM, all payments processed before 11PM on Monday will be deposited to merchant’s bank account on Tuesday, while payments processed after 11 PM will be included in Wednesday deposit. Read
how to change the settlement cutoff time.
The way in which the settlement is initiated. There are three modes supported:
— Daily – settlement is initiated once a day at a fixed time (automatically). For example, every day at 11 PM.
— Hourly – settlement is initiated multiple times per day within fixed settlement windows (automatically). For example, every 3 hours.
— On demand/manually – settlement is initiated whenever end-of-the-day settlement message is received, i.e. cycle is closed manually via a respective API call or via the user interface. For example, during the customer´s checkout in the supermarket.
Transaction reprocessing is a process of reattempting previously declined transactions. It is performed mostly on soft declines in cases where there is still a chance to collect money (e.g. insufficient funds). Reattempts are not usually done on hard declines (account closed, card stolen, etc). Reattempts can be of two types – rebills and retries.
— Rebill - a reattempt, initiated by an external system or
— Retry - a reattempt, initiated by the gateway.
Verification is a process of confirmation of totals within a particular
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
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.
Recurring billing configuration that unifies the billing cycle and billing profile assigning them to a specific payment.
Billing cycle defines the frequency of billings and the day when a billing occurs.
This term is used in two contexts:
1) As a billing configuration setting, billing cycles allow to group subscriptions and perform revenue analysis based on all subscriptions associated with a particular billing cycle. Based on a billing cycle, invoices are created.
2) As a
parameter, billing cycle defines the frequency of billings. In the gateway, there are 5 types of billing cycles:
— Weekly - billing occurs on a weekly basis.
— Monthly (default)- billing occurs on a monthly basis.
— Quarterly - billing occurs every 3 months.
— Semi-annually - billing occurs every 6 months.
— Annually - billing occurs on a yearly basis.
Set of settings that define which invoices (of what age) will be selected during the recurring billing process for the generation of claims.
The Billing Profile contains the following parameters:
(generated by the system);
- defines a period of time for which the system checks unpaid invoices and creates claims based on them;
Minimum and maximum amounts
- define the amount range within which the system checks unpaid invoices to create claims;
Include CC/Include ACH
checkbox - defines the types of payment options that will be selected for billing;
checkbox - defines if the invoices that are not associated with the customers’ current payment plans (Scheduled Payments) are included in the billing;
- allows to include invoices that have already been declined in the previous billing periods.
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.
Period of time in days that starts from the moment the oldest debt was formed, after which the customer with outstanding (positive) balance becomes the subject to collections (email, penalties, etc.).
To simplify debt management process, customer accounts can be grouped into phases, based on the age of debt. Phases are age buckets used to classify age of the outstanding debt. Each merchant can define age limits for each phase based on their specific business needs, but it is common to use four phases, 30-days-long each.
An individual who purchases a
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.
A record that holds critical data about the customer (a person or an organization) including basic demographic/contact information and activity-related information (such as current balance, letter flags, etc).
Resulting of all customer transactions that represent the actual amount of debt of a customer or a merchant. A positive (outstanding) balance represents the amount due on the customer´s next invoice. A negative balance means that the merchant owes money to the customer (can be the ground for a refund).
A record representing the movement of money on the customer´s account that results either in the increase (revenue transaction) or decrease (asset transaction) in customer’s debt.
Attempt by the billing system to collect a recurring payment against the outstanding (positive) balance on a specific due date. Claims are processed in batch files. The result of the claim transaction is obtained within 3 days upon submission. Thus, within this period of time decline may be returned.
Transaction that represents the decrease in customer’s debt in case of cancellation of purchase, applied discounts, etc.
Transaction surcharged to the account automatically by the system when a specific condition occurs or is met. The fee can be charged to a customer only if this condition is explicitly stated in the agreement between the customer and merchant. In order for the fee to be applied correctly, a policy indicating the principal for fee withholding has to be configured. A user can choose either of the following options for policy configuration:
— Always - used to set fee withholding as a fixed amount on a regular basis (does not depend on the invoice amount).
— When below - used to set the correlation between a fee amount and invoice amount (does depend on the invoice amount). For example, if the invoice amount is less than $30(set as a threshold), then the fee amount is $4, otherwise, the fee amount is $7 (set as a high ticket).
The following fees are available within the system:
— Enrollment fee – is charged when a customer record is created. The fee is charged one-time only.
— Soft decline fee – is charged on soft declines (transactions that were declined with the reason that suggests that further reattempt might be successful).
— Hard decline fee – is charged on hard declines (transactions that were declined with the reason that suggests that further reattempts are futile).
— Retry fee – is charged when previously declined transaction gets approved as a part of automated retry process.
— Chargeback fee – is charged when a chargeback is received.
— Statement fee – is charged for cases when a payment plan is paid by a customer who comes to facility and makes a payment in person.
— Freeze recurring fee – is charged when a payment plan is set on freeze. The fee is charged on recurring basis, replacing the regular payment plan amount.
— Freeze flat fee – is charged when a payment plan is set on freeze. The fee is charged one-time only.
— Return fee – is charged when a return on direct debit payment is received. Once configured, it is applied immediately. It cannot be applied to old returns.
— Late fee – is charged if there is an outstanding balance by a period indicated as a
. The late period is set to indicate a period in days when the fee is applied. For example, if the value of the late period is set as “20”, it means that if after 20 days the invoice remains unpaid, the fee is applied. Once activated, the fee is applied to all unpaid invoices a customer has.
— Document access fee – is charged for accessing documents within a membership portal (for example, electronic libraries documents).
Transaction that represents the outstanding customer balance (increase in debt) to be paid by the customer for a purchased product or a service.
Transfer of funds from the customer to the merchant that covers debts represented by invoices. The result of a payment transaction is obtained in real-time and is final.
Transaction that represents an actual return of the money to a customer that covers the debt of a merchant represented by credit. For example, a refund is made if it was decided to return the amount of negative balance to a customer rather than apply it to other invoices due for payment.
Customer’s payment card or bank account encrypted and stored within the system.
Pricing plan, which determines how often and how much a customer has to pay.
Billing frequency is defined in
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.
Adjustments made to a particular subscription for one of the following reasons:
— Cancellation/Termination - deactivation of the subscription requested by the customer/initiated by the merchant.
— Freeze - suspension of the subscription for a certain period of time.
— Pause - suspension of the subscription for an unspecified period of time.
Date when the subscription adjustment (cancellation, freeze, or pause) takes effect. Effective date must coincide with one of the upcoming billing dates.
Action that cancels (deactivates) the subscription right away or on the specified date (effective date).
To cancel the subscription on a specific date, one of the next billing dates, starting from which the subscription will be canceled, must be specified as the
. Otherwise, the subscription will be canceled immediately.
Pending cancellation subscription (the one that has an effective date in future) can be
before the effective date. In case the subscription has been canceled right away, or the effective date has already passed, the cancellation can not be reverted.
Action that suspends the subscription for a certain period of time (one or more billing periods).
Frozen subscription can be
at any time, and the customer will be billed on the next scheduled billing date.
Action that suspends the subscription right away or on the specified date for an uncertain period of time.
Previously paused subscription can be
at any time, and the customer will be billed on the next scheduled billing date.
Subscription can obtain the following statuses:
— Current - indicates that the payment plan is active.
— Deferred - indicates that no invoice will be generated in the upcoming billing associated with the payment plan.
— Freeze - indicates that the payment plan is terminated. After the predefined number of freeze charges are passed, the payment plan will be reactivated automatically.
— Cancelled - indicates that the payment plan is cancelled.
— Expired - indicates that all payments associated with a payment plan are made; available only for a fixed payment plan.
— Unbilled - indicates that no billing occurred since the payment plan has been created.
— Suspended (deprecated) - indicates that the payment plan is set on hold by the system.
— Paused - indicates that the payment plan is set on hold by the user. A paused payment plan can be unpaused manually only.
There are two types of subscriptions:
— Fixed subscription – a certain payment amount is agreed upon, and the number of payments is limited (fixed) by the agreement/contract. For example, $10 per month for 12 months.
Fixed subscription can be created for a period of time not longer than 3 years.
— Perpetual (often refereed to as pay-as-you-go or unlimited) subscription – payment is going to recur until the plan is explicitly canceled. On the user interface, a number of the scheduled payments always lists 12. Once a payment is done, a new one is added to the lists of upcoming payments. For example, $10 per month until canceled.
Embedded SDK (Software Development Kit)
Software allowing for creating and managing terminal applications.
A service provider that processes terminal orders, installs terminal software and ships terminals to PSP’s merchants.
Keys used to encrypt the data that is input into a terminal (card number, PIN, etc). The keys are uploaded to the terminals during the fulfillment process. To learn more about injection keys, follow this
LLT (Local Loading Tool)
Software used to upload files (including the terminal application) to Ingenico terminals.
The original payment application of Ingenico, which is an equivalent of the
A device used to sign the terminal application that is going to be uploaded to a terminal. A toolkit, which looks similar to the terminal device, comes with a plastic card with a key by which the application is signed. This device is provided by a terminal manufacturer, such as Ingenico.
A terminal OS used by Ingenico terminals for operation.
A terminal payment application UniRead, which is installed on the terminals and allows for processing terminal transactions.
Terminal Management System
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).
Activity and Diagnostics Logs
When there is an issue with a remote terminal, it is necessary to determine the problem. For this to happen, it is required to know what the settings of the terminal are and what steps preceded the malfunction. After that, remote debugging must be performed. To analyze and locate the problem remotely, activity and diagnostics logs are used.
store the information of all the activities of the terminal and record all operations performed by it.
store all characteristics data (memory, number of hard drives, peripherals’ performance, etc.), applications uploaded to the terminal, and data regarding the physical condition of the terminal.
The TMS allows users to review all operations performed by the terminal before the failure occurred.
A process of terminal applications change to a more up-to-date version with fixes and added features is called a terminal update.
When the recovery process is activated, a terminal is rolled back to the most stable version (the last version functioning trouble-free for an extended period of time in the production environment). This version is supposed to facilitate the proper operation of the terminal and potentially download new updates. Typically, it is called a base version. The base version of the application is uploaded to the new (factory) terminals by the fulfillment center. After that, in cases of recovered terminals, new updates can be installed based on this version.
To perform a terminal update, the required files are uploaded to the terminal. For security reasons, and in order to unify and organize the uploading process of these files remotely, files must be uploaded from a single location called a repository. A repository is a vault for files that are uploaded to the terminal during the updates. Terminal update files are downloaded from a local computer and, subsequently, to the repository. From the repository, the files are uploaded to the terminals via TMS API.
There is a need to update terminals that belong to a particular group. This is done to avoid cases where a malfunction occurs on numerous terminals, which, subsequently, may necessitate costly repairs. For example, an update is issued for the update profile used for mobile and desktop terminals. This update is released to fix a bug present in the mobile terminals only. In this particular case, all mobile terminals (a problem group) are segregated into a separate sub-group (a segment) within the update profile. This sub-group of terminals is uploaded with specific versions of the update. Thus, the segment allows for the updating of only those terminals belonging to it.
During the terminal update, it is complicated and inconvenient to integrate the settings of each particular terminal. To optimize this process, the terminals are divided into groups with similar/repeated characteristics. With regard to these characteristics, a corresponding terminal update of the application is uploaded. The update for a particular group of terminals is required for:
terminals of the same model or manufacturer (Ingenico, Verifone);
a specific terminal application version that differs dramatically from the others;
merchants belonging to the same business type but differing dramatically from the others.
To update terminals of the same group, an update profile is used. The profile is a series of settings required for a particular group of terminals. Based on these settings, the terminal application is uploaded to the terminal. The profile defines which version (in what form and with what parameters) is going to be installed on the particular group of terminals. In other words, the update profile allows the user to combine the settings required for a particular group of terminals and manage multiple processes related to the terminal update.
Not all terminals should be updated simultaneously because there is a chance that the latest version of an update may contain bugs or shortcomings, which can negatively impact terminal efficiency. Additional reasons for not updating all terminals at once include various terminals having different versions of updates already installed, some terminals being deactivated for a period of time, or having been in transit. For those reasons, different terminals may have various builds of the application installed. To understand which functionality a particular terminal possesses, it is necessary to track which version is installed on each terminal. To help simplify this process, each application build is assigned its version (code) - update version.
UniPay - Payment Gateway Software
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.