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
Reference Field Type
Direct Debit Return
Funds Distribution Recipients
Merchant Tier Structure
F. Backward Transformation
Split Payments Mechanism
Payment Plan Types
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.
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 - numeric value, provided by the gateway; unique within the system.
— External identifier - 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).
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. As a rule, there are four remitter accounts – for CC, 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 controled by
— Data access - deals with data that a user has access to, for example, data associated with particular merchant, reseller, etc. This is controlled by
data access policy
— Functions - deals with functions that a user can fulfil within the various business processes implemented in the system. This is controlled by
Permission represents a user’s ability to perform a particular action within the system on the lower level. A user can 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 a user’s ability to access a part of the system that shares an API or user interface. Now, there are seven privileges in the gateway:
— User Interface – allows a user to access functionality of the user interface. By default, this privilege is assigned to the human users only.
— Processing API - allows a user to access functionality related to transaction processing. This privilege can be assigned to the service users only.
— Management API - allows a user to access functionality related to the settings setup of merchants, portfolios, etc. This privilege can be assigned to the service users only. 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. This privilege can be assigned to the service users only.
— Onboarding API - allows a user to access functionality related to the onboarding application. This privilege can be assigned to the service users only and 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. This privilege can be assigned to the service users only.
— 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 level of user access that regulates forms and actions that are available to a user.
Security role is a combination of
. In the gateway system, there are twelve security roles that can be shown as a hierarchy - from
(which is the highest security level with the biggest number of permissions) to
(which has 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.
Batch is a collection of transactions that are processed together. Batch processing is used in two situations:
Realtime batches - are used for settlements of pre-authorized transactions.
File batches are used to process together card not present transactions (authorization and settlement) of recurring nature such as bill payments, subscription payments, etc.
Sub-batch is a sub-group of transactions that a batch contains. Batch transactions can be divided in sub-batches for the following reasons:
— Quantity limitation for the transactions included into one batch. If a batch contains number of transactions that exceeds the fixed limit, it is divided into several sub-batches.
— The difference in how transactions are processed. For example, a batch may contain both direct debit and CC transactions. In this case, sub-batches are created for processing to be properly performed within the system.
— Difference in transactions life cycles. Blacklisted or denied transactions can be combined into respective sub-batches.
Verification file - a file used for confirmation of totals within an associated batch file. The information is generally used by the bank to confirm accuracy of the batch file that has to be processed. Verification file is used for both daily batch transaction processing and remittance files. Verification file is a part of verification process.
Chargeback is a financial mechanism allowing a cardholder dispute over particular amount of money that have been charged illegitimately or as a result of an error. The crucial decision of this case makes card association. If cardholder disputes successfully, particular amount of money is withdrawn from Merchant's bank account and returned to cardholder. But this decision can be overruled through an arbitration process. Notwithstanding whether the decision is made in favour of cardholder or Merchant, chargeback fee is applied. The important issue relates to Merchant's chargeback rate. If it exceeds 1%, 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 this 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 those cases when a processor does not provide any form of API or file to handle disputing process, chargeback cases will not be automatically created. In most of such cases, a merchant is expected to dispute chargebacks using either processor's specific portal or a hex number provided by a processor.
Transaction that represents a charge in addition to the original transaction amount for a convenience usage service for credit card payments, which in most cases is a surcharge, that generally is kept by the service provider that facilitates the payment (payment gateway, processor, etc). Convenience fee handling can be performed through two approaches: when merchant funding is handled by the payment gateway or by the system that processes the transaction; and 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 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 convenience fee separately from the primary transaction, as a second transaction. Therefore, it contains the settings that are used to process the separate convenience fee transaction.
Direct Debit Return
Unlike processing of 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 up to 2 months. If a bank cannot process a particular direct debit transaction, the transaction gets declined. Depending on a reason, 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 notified 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 notified the merchant that the bank account was closed by the member.
Merchant gets notified about direct debit declines via direct debit
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 amerchantin 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 incorrectly charged, merchant is notified about that with an unauthorized return. Unauthorized returns are classified as hard declines and may have 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.
The frequency of fee collection. Fees can be volume-based and time-based. Volume-based ones are charged per item, while time-based ones are collected at certain times.
A meta structure defining basis for a Merchant Fee and a Reseller Commission. It encapsulates fee structure (while Merchant Fee 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. Formula is defined using statistical variables calculated daily off operations data. The formula serves as the basis for Fee and Commissions calculation.
Funds distribution module handles payments between a sender of a payment and one or more recipients of the payment.
Funds Distribution Recipients
The current logic allows to distribute funds between the following recipients: holding account, vendor, reseller, merchant balance, convenience fee balance.
— Holding account represents a bank account which is owned by merchant, but is used to store a certain part of money, e.g. collected taxes.
— Vendor. Concepts of reseller and vendor are similar in the sense that they both represent 3rd-parties and receive some part of the payment. However, vendors are used in the marketplace scenario, where merchants have several vendors, such as suppliers of merchandise, that need to receive a certain percentage of the payment. The system supports 5 different fixed rates, which allows to select up to 5 different vendor levels (I-V), each vendor level is connected to a different rate.
— Resellers also represent 3rd-parties, but they are using other scenarios, such as when a software company that a merchant uses has to receive a certain percentage for usage of its software. For example, POS software company or rent payment management company might be getting a flat fee of each transaction.
Vendors and holding accounts are created on Distributions perspective (Management => Distributions), while merchant and convenience fee balances are already present in the system and may be connected to any merchant.
Internal emulator of transaction processing used for integration testing with the gateway. Host emulator emulates particular responses depending on the incoming parameters. For example, depending on the amount in the transaction, it can generate approval or decline for this transaction.
Represents a customer (tenant) within gateway. Serves as a logical grouping of data and configuration settings. All of the processing is done on the merchant level.
A subunit of Merchant. Can represent location, store, club or department. Used to subdivide data (on reports) and override global processing settings defined on Merchant level.
A set of configuration settings that can be defined either on Merchant or Account level. Unlike Account Profile, which defines processing settings, includes settings related to remittance and commissions.
A set of configuration settings that can be defined either on Merchant or Account level. Unlike Account Group, which defines remittance and commissions settings, includes settings related to transaction processing.
Account Profile groups in itself different Provider Profiles that define processing policy with a corresponding provider.
Merchant Code is a unique identifier of a
. The value is a multiple of 1000 staring from 2000 (1000 is reserved for system use).
Account Code is a unique identifier of an
Each Account attributed to a
gets a Code with value between 1 and 999, which is combined with the merchant code. Thus, if a Merchant is assigned code 2000 and the Merchant has 3 Accounts, their respective Codes would be 2001, 2002, 2003.
Such approach enables easy ownership identification based on Account Code. For the purpose of data partitioning, each record in the database that belongs to a Merchant/Account has an Account Code field within itself.
ID is a system generated value used internally to track references between objects. ID is read-only. Code is an assignable value that is used by the external client’s system to identify the given object. If code is not specified, its value is defaulted to ID. The code may only be specified at the moment of an object’s creation and cannot be changed. The code must be unique within the scope of a merchant.
A set of days within a month (1-28) when a reconciliation process for a Merchant has to run. 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.
A fee structure (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 further 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. The charges are withheld from a merchant as a deduction, but applicable to the merchants who use both deduction and withdrawal approach to take out fees. The charges are transferred via a batch file - a Charge file, which contains a list of charges associated with merchants. Once a charge is withheld and a reseller statement is generated, a Сharge Payments file is returned containing a reference to the charge associated with the payment, as well as the amount that was withheld from the merchant. The charge is withdrawn from the merchant based on the merchant statement and transferred to the reseller based on the reseller statement.
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 "demand" means that deposit is made fixed numbers of business days (waiting period) after processing happens, and the second part "demand" 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 "demand" means that deposit is made fixed numbers of business days (waiting period) after processing happens, and the second part "cycle" 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
The system supports two fundamental pricing models:
— Blended rate - fees are determined by averaging 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 the
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 - a set of parameters that are used to govern the setup of the merchant with the respect to its account, merchant IDs, descriptors and deposit accounts. It comprises 5 parameters, defining of which will make it possible to determine how the merchant/account should be configured.
Accounts - defines whether it is a multi-location / multi-terminal or single-location / single-terminal merchant.
— Single - everything is configured at the merchant level. Other parameters in the profile are ignored.
— Multiple - multiple accounts will be setup. The settings will be configured based on the remaining parameters on the profile.
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 separate tax ID.
— Single - the legal entity owning the tax ID is represented with a merchant. Underwriting (background verification) is done at a merchant level.
— Multiple - the legal entity owning the tax ID is represented with an account. Underwriting (background verification) is done at an account level.
Processing - defines whether a single provider profile is going to be used for all locations of the merchant or each location is going to use 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 every 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 - all the remittance settings are configured on the merchant level. All of the money is funded to a single deposit account regardless of the number of accounts used.
— Multiple - all the remittance settings are configured on the account level. The money processed to each account is funded separately in a separate deposit account.
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 setups under a merchant.
In order to process transactions and remit a set of various types of configurations is maintained with the system.
All of the settings within the system are divided into two groups:
— Processing settings - define how a transaction is going to be processed. These settings include configurations of provider profiles used to process transactions as well as various types of settings around settlement, cut-off times, etc.
— Remittance settings - define how remittance processing is going to happen and how funding of the merchant is going to occur. These settings include deposit account information (where the money should go) reserves, merchant fees, etc.
Depending on the business context, both groups of settings (processing & remittance) can be maintained on either merchant or account level. This is done to accommodate various types of business needs.
A summary of activity for a merchant for a set time interval. Includes transaction submissions, deposits, reserves, processing and monthly fees.
Adjustment is an element of
that allows manual adjustments to the current statement balance. They can be used to rectify statements errors that resulted from exceptional business behaviour, waive fees or withhold additional fees that do not generally appear on the statement.
Scheduled adjustment allows manual adjustment to the future
s. 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 requires an advance, 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 a single card-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 card-terminals or a multi-location store with a single card-terminal in each of them.
— Three tier - an example of a three-tier hierarchy would be a multi-location supermarket with multiple card-terminals in each of the locations.
There are two objects within the system used to represent various tiers of the merchant’s business:
— Merchant - parent entity, which groups together accounts.
— Account – child of merchant, representing a unit of business (location, store, department) or a terminal.
In the one-tier scenario, the merchant is going to represent the both the business itself and its single terminal (when applicable).
In the two-tier scenario, the merchant is either going to represent a store/location and the account - a card-terminal, or the merchant is going to represent a corporate entity owning the stores and the account - 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 setup.
There are 3 types of merchants currently maintained within the system:
— Billing - processors of credit card and direct debit transactions; may or may not use recurring billing and collections.
— Collections - a 3rd party collections company providing services to other merchants within the system.
— Remitter - reserved/system merchant; used to define direct debit settings for fund remittance in cases when aggregate model is used.
Remitter must have 4 Accounts defined, each of which must have corresponding direct debit settings provided through Account Profile. The Provider Accounts defined in Account Profile must point to deposit accounts where funds of corresponding type get deposited after transactions are processed and before remittance process occurs. Same Account Profile or Provider Account can be used more than once (e.g. when all funds are deposited into the same account).
The accounts must be defined as follows (based on 4 digit Merchant ID):
— xxx1 - account settings for direct debit remittance source.
— xxx2 - account settings for Bank Card remittance source.
— xxx3 - account settings for Amex remittance source.
— xxx4 - account settings for Commissions source.
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.
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.
Onboarding application is a specific form that allows onboarding of a merchant within the gateway using onboarding API. The application is designed for external companies to board associated merchants. The application collects all necessary information that is further submitted to the processor that performs onboarding. The response to the onboarding request can be delivered in real-time or via a callback, which is the subject to a specific processor.
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.
This architecture allows support of multiple independent processors with a single API (point of entry).
Transformation is the process of translating high-level entities into low level entities, it’s a transformation from the system’s processor-independent format into processor-specific format of transactions.
Generation is the process of generation of a processor-specific message from low-level transactions.
Upload is the process of uploading of a file to the processor in the processor-specific format.
Download is the process of downloading the result file from the processor in the processor-specific format.
Parsing is the process of parsing processor-specific message which includes extraction of data used to form low-level processor-specific response entity.
F. Backward Transformation
Backward Transformation is the process of translation of low-level processor-specific entity into high-level processor-independent response.
An external system (often a gateway) that provides services for gateway through an exchange of files or messages. Examples of providers are credit card networks, direct debit banks, print houses, bulk email services, credit bureaus.
Connections settings (protocol, url, user name/password, public keys for SSL or PGP, etc) that should be used to communicate with a Provider
Account settings within Provider's system. Includes two types of values:
— Internal - values needed for the process management and setup by gateway (profile name, cut off time, rebill count, etc).
— External - values required by the Provider to identify the submitter in their system (MID, BIN, some other identifier).
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.
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.
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.
Settlement, also referred as Capture, is the second phase of the payment processing, when the previously authorized 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:
— When terminal 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).
— When host capture 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.
Settlement process can to be organized in one of three ways:
— Daily – once a day at a fixed time.
— Hourly – multiple times per day within fixed settlement windows.
— On demand/manually – 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.
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.
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 payment card or bank account.
— Sale-auth - sale transaction that requires an explicit capture in order for money to be transferred to a merchant.
— Sale-info - operation used to supply information about a sale transaction processed outside of the gateway. Often used to record the transaction for rewards balance of loyalty cards.
— Credit - operation used to deposit (return) a specific amount of money to a payment card or bank account.
— Credit-auth - credit transaction that requires an explicit capture in order for money to be transferred to a merchant.
— Credit-info - operation used to supply information about a credit transaction processed outside of the gateway. Often used to record the transaction for rewards balance of loyalty cards.
— Capture - operation used to initiate settlement of sale-auth transactions that were processed with multiple capture processing mode enabled.
— Refund - operation used to deposit (return) a specific amount of money associated with a particular transaction.
— Void - sale transaction that has been reverted. Can be done only before settlement. No further action can be taken for a voided sale transaction.
— Void (c) - credit transaction that has been reverted. Can be done only before settlement. No further action can be taken for a voided credit transaction.
— Void (i) - split-in/pull-in transaction that has been reverted. Can be done only before settlement. No further action can be taken for a voided split-in/pull-in transaction.
— Void (o) - split-out/pull-out transaction that has been reverted. Can be done only before settlement. No further action can be taken for a voided split-out/pull-out transaction.
— Split-in - operation used to deposit a specific amount of money provided in a split transaction. Applicable for sale transactions only.
— Split-out - operation used to withdraw a specific amount of money provided in a split transaction. Applicable for sale transactions only.
— Pull-in - operation used to deposit a specific amount of money based on the instructions specified in the original sale transaction that was split. Applicable for credit/chargeback/return transactions only.
— Pull-out - operation used to withdraw a specific amount of money based on the instructions specified in the original sale transaction that was split. Applicable for credit/chargeback/return transactions only.
— Blacklist - sale that has not been processed as the account is in the blacklist due to the previous hard decline.
— Blacklist (c) - credit that has not been processed as the account is in the blacklist due to the previous hard decline.
— 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.
— Decline - sale transaction that got declined.
— Decline (c) - credit transaction that got declined.
— Chargeback - operation used to reverse a prior outbound transfer of funds from a customer's bank account or payment card.
— Reversal - operation used to reverse a payment card chargeback, i.e. money is given back to the merchant or customer.
— Error - a 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.
— 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 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.
— 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.
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.
Adjustment reason is used as a reason for the deactivation of a payment plan. There are three types of adjustment reasons:
— Cancellation - deactivation of the payment plan requested by the customer.
- suspension of the payment plan for a certain period of time.
— Termination - deactivation of the payment plan initiated by the merchant.
Billing unifies billing cycle and billing profile assigning them to a specific payment.
Transaction that decreases a customer’s debt. The records related to asset transactions include information about physical payments, customer funds and all respective changes. Asset transaction is represented by two objects - Payment and Refund.
Transaction of funds that are transferred from customer to the merchant to cover debts represented by invoices.
Transaction that is an actual return of the money to the customer in case of revenue transactions error. Refund covers debts represented by credit.
Transaction that increases a customer’s debt. The records related to revenue transactions include information about customer's debts and all respective changes. Revenue transaction is represented by three objects - Invoice, Credit and Fee.
Transaction that represents discounts or some specific charges applied to the customer.
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 customer’s debt for merchant’s services.
Billing cycle defines the frequency of billings and the day when a billing occurs. Based on a billing cycle, invoices are created.
In the gateway, there are two basic types of billing cycle:
— Monthly - billing occurs on monthly basis.
— Weekly - billing occurs on weekly basis.
To set a billing cycle different from the basic ones,
API field is used. This field regulates how often billing should occur based on the selected basic type of billing cycle - monthly or weekly.
— to configure a biweekly billing cycle, the value of the recurrence field should be set as 2 and submitted along with the billingCycleCode field including the code of the original
cycle that a new billing cycle is attached to;
— to configure a quarterly billing cycle, the value of the recurrence field should be set as 3 and submitted along with the billingCycleCode field including the code of the original
cycle that a new billing cycle is attached to.
Billing profile defines which invoices (of what age) should be included into the payment while creation. Based on billing profile, payments can be created with optional settings.
To simplify debt management process, 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.
Represents a person or an organization within gateway Suite. Stores basic demographic/contact information, as well as various activity related information (such as current balance, letter flags, etc).
Freeze is the suspension of a billing schedule one or more billing periods.
Payment Plan Types
Payment plan (also referred to as payment schedule) can be of different types:
— Fixed (term) payment plan – 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.
Unlimited (pay-as-you-go)/Perpetual payment plan – 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.
— Hybrid (rollover or open-ended) payment plan – initially consists of a fixed (defined) number of payments, however, after the initial fixed number of payments, the billing continues to recur (the plan becomes unlimited) until it is explicitly canceled. For example, 6 months for $20 and then $30 until canceled.
Payment plan 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.
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.
Skip Tracing (or Skip Trace) - is the process of obtaining the updated contact information about a person based on their existing contact information for further debt collection.
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.