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 Account Group
Merchant Account Profile
Merchant Account Code
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 Merchant 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
Merchant 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, a merchant 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.
UniPay 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, functions and data access.
Actions aspect 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 aspect 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 aspect 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 five privileges in the gateway:
User Interface – allows a user to access functionality of the user interface. By default, this privilege is assigned only to human users.
Processing API - allows a user to access functionality related to transaction processing. This privilege can be assigned only to service users.
Management API - allows a user to access functionality related to the settings setup of merchants, portfolios, etc. This privilege can be assigned only to service users. In addition, along with this privilege, a security role needs to be set up.
Billing API - allows a user to access functionality related to reccuring billing. This privilege can be assigned only to service users.
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 only to service users.
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 statements and reconciliation statements.
Deposit statement - a type of 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
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
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 UniPay. 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.
Merchant Account Group
A set of configuration settings that can be defined either on Merchant or Merchant Account level. Unlike Merchant Account Profile, which defines processing settings, includes settings related to remittance and commissions.
Merchant Account Profile
A set of configuration settings that can be defined either on Merchant or Merchant Account level. Unlike Merchant Account Group, which defines remittance and commissions settings, includes settings related to transaction processing.
Merchant 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).
Merchant Account Code
Merchant Account Code is a unique identifier of a
Each Merchant 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 Merchant Accounts, their respective Codes would be 2001, 2002, 2003.
Such approach enables easy ownership identification based on Merchant Account Code. For the purpose of data partitioning, each record in the database that belongs to a Merchant/Merchant Account has a Merchant 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. For more information see
A fee structure (processing rates, service fees, etc) associated with a Merchant. Defines how deposits and fees should be calculated based on transaction processed.
Fees are divided into three major categories: 'processing fees', 'flat fees' and 'monthly 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
; 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 - also subdivided into two groups: monthly and annual. They are usually subscription service fees that are charged to cover various types of service charges, hardware cost and support.
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
, 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
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 more information see
). 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
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 Merchant, because the amount of funds processed equals the amount of funds received. However, it introduces potential risk for PSP/TPP which is 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 predefined day of the cycle (for more information see
) 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' and 'cost-plus'.
'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 merchant account, merchant IDs, descriptors and deposit accounts. It comprises 5 parameters, defining of which will make it possible to determine how the merchant / 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 merchant accounts will be setup. The settings will be configured based on the remaining parameters on the profile.
Tax IDs - defines whether a single federal tax ID will be used for all locations or each tax ID will be used specifically per each of the locations.
Single - the legal entity owning the tax ID is represented with a merchant.
Multiple - the legal entity owning the tax ID is represented with a merchant account.
Descriptors - defines the desired number of soft descriptors to be used all across the accounts.
Single - a single merchant ID (MID) is required for processing.
Multiple - for the majority of the processors, multiple MIDs will be required for processing; one MID per descriptor.
Deposit accounts - 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 merchant accounts used.
Multiple - all the remittance settings are configured on the merchant account level. The money processed to each merchant 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 merchant 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.
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.
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.
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. They are:
• merchant - parent entity, which groups together merchant accounts
• merchant 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 merchant account - a card-terminal, or the merchant is going to represent a corporate entity owning the stores and the merchant 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 merchant 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 merchant 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 Merchant Accounts defined, each of which must have corresponding direct debit settings provided through Merchant Account Profile. The Provider Accounts defined in Merchant Account Profile must point to deposit accounts where funds of corresponding type get deposited after transactions are processed and before remittance process occurs. Same Merchant 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 Account Code):
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
Onboarding application is a specific form that allows onboarding of a merchant within the gateway using provisioning API. Onboarding application is designed for external companies to board associated merchants. The application collects all necessary information that will be further submitted to the processor that performs provisioning. The response to the onboarding request can be delivered in real-time or via callback, which is 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).
The key processes invloved are:
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 UniPay through exchange of files or messages. Examples of providers are credit card networks, ACH 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 UniPay (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 UniPay as a result of transaction processing. It can be used to identify sales people, resellers, referrers, etc.
Channel is an integration processed in UniPay 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.
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:
A split-in transaction - is 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.
A split-out transaction - is 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:
A pull-in transaction - is 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.
A pull-out transaction - is 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.
UniPay 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), UniPaywill 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 UniPay 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 UniPay, wants to make a payment on behalf of its client in a store that is not integrated with UniPay and needs a live card number for that. For such cases, UniPay 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, UniPay 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 merchant 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) ACH returns. Irrecoverable ACH returns include cases when account is closed or invalid.
Blacklists are introduced to prevent problems induced by the fact that ACH transactions do not get approved or declined in real-time like credit card transactions. To eliminate waiting for a certain ACH return, every ACH 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 descriptors and dynamic descriptors.
A static descriptor is 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.
A dynamic descriptor is 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 UniPay.
Transactions are classified by their types. The following types are available within the system:
sale - operation used to withdraw specific amount of money from the supplied credit card or bank account;
sale-auth - operation that represents a sale, which requires an explicit capture operation in order for the money to be transferred;
sale-info - operation used to supply information about a sale transaction, which was processed outside of the gateway. Often used to record the transaction for rewards balance of loyalty cards;
credit - operation used to deposit (return) specific amount of money to the supplied credit card or bank account;
credit-auth - operation that represents a credit, which requires an explicit capture operation in order for the money to be transferred;
credit-info - operation used to supply information about a credit transaction, which was processed outside of the gateway. Often used to record the transaction for rewards balance of loyalty cards;
capture - operation used to initiate settlement of the sale-auth transactions that were processed with multiple capture processing mode enabled;
refund - operation used to credit funds back to the payment account;
void - reverted sale, can be done only before settlement. No further action can be taken for a voided sale transaction;
void (c) - reverted credit, can be done only before settlement. No further action can be taken for a voided credit transaction;
split-in - operation used to deposit a specific amount of money based on instructions, provided in a split transaction.
split-out - operation used to withdraw a specific amount of money based on instructions, provided in a split transaction.
blacklist - sale, which has not been processed as the account is in the blacklist due to the previous hard decline;
blacklist (c) - credit, which has not been processed as the account is in the blacklist due to the previous hard decline;
return - represents direct debit payment that is not honored by a bank;
reject - represents direct debit payment that is rejected by the bank due to insufficient funds or errors in payment order;
decline - represents card sale transaction that got declined;
decline (c) - represents card credit transaction that got declined;
chargeback - operation of reversal of a prior outbound transfer of funds from a customer's bank account or credit card;
reversal - operation where credit card chargeback is reversed - money is given back to the merchant or customer;
error - represents a transaction that did not go through an internal validation of the gateway and was not sent for further processing. The response code indicates the reason why transaction was not processed.
inquiry (balance inquiry) - operation used to verify balance on debit, prepaid or gift cards;
verification (account verification) - operation used to verify that the account is active and perform AVS verification without actual authorization;
fee (convenience fee) - operation used to calculate a surcharge to the card holder to cover the cost of the credit card processing;
transfer - operation used to transfer a balance from one card to another;
notice (notice of change) - represents direct debit transaction that is returned by the customer's bank as a notification that some details of the transaction were corrected.
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 for a gift card. Similar to token, alias can be used instead of card number for further processing;
delete-alias - operation used to remove an alias 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 phone call to the bank – gateway owner makes a call to provide file totals;
via 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 of the deactivation of a payment plan. There are three types of adjustment reasons:
Cancellation - deactivation of the payment plan requested by the customer;
- suspention 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 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;
late fee – is charged if there is an outstanding balance by a period indicated as
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 UniPay 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. They are the following:
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 cancelled. 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 cancelled.
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 cancelled. For example, 6 months for $20 and then $30 until cancelled.
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.