Entities & Hierarchy

In the Silverflow ecosystem, the hierarchy among different accounts is structured as follows:

An Agent represents the top-level entity in the Silverflow hierarchy. It is a legal entity that engages in a commercial relationship with Silverflow and utilizes the Silverflow API for processing card transactions. Once a signed contract is established, the client receives an Agent entity along with an activation token from Silverflow. Activation of the agent results in the issuance of the Master API key to the client, which can be further utilized to generate additional API keys. The agent holds the master API key and is responsible for creating and managing additional API keys.

BINs are unique numbers used to identify the acquirer on the card network. Typically, an acquirer will have different BIN numbers for each network, and multiple BINs may exist per card network for a single acquirer. BINs are created by Silverflow and assigned to an agent once they are activated by the card network.

A Merchant is a legal entity that accepts card payments through the Agent. The merchant account contains essential data about the legal entity, including its legal name, address, website and contact details. Each merchant account is part of an account hierarchy and has one or more Merchant Acceptors as child entities. In order to create a group structure you can add tags to merchants and/or merchant acceptors.​

Merchant Acceptors are subordinate entities of merchants and are associated with a specific BIN configured by the agent. They contain essential data for processing card payments, such as the MID (Merchant ID), the DBA (Doing Business As) name, and the MCC (Merchant Category Code). Typically, one merchant acceptor is required for each BIN. Additional acceptors can be created to accommodate different MCCs per network or other requirements.

Tags are customizable properties that can be assigned to both Merchants and Merchant Acceptors. They provide a way for clients to organize their entities into groups, such as regions, departments, or franchise groups, without creating separate entities. Tags enable customized reporting and analysis based on the client's preferred hierarchy. Consistent naming conventions and documentation of tag purposes are recommended for clarity and consistency.

Tags can be assigned to merchants and acceptors either during their creation or at a later time by updating their respective entities. For example, tags can be used to distinguish legal entities at the merchant level or to categorize acceptors based on channels like physical stores or e-commerce websites.

Here's an example of assigning a tag to a merchant:

In the above example, an Agent that is operating globally has legal entities in two regions with their own operations. The merchant level tags can be used to assign the groups of merchants to distinguish each legal entity.

Tags can be assigned to the acceptor at the time of creation of the merchant using the merchant acceptor template, creation of the acceptors individually, or at a later point in time by updating the acceptor.

In the above example, an Agent is serving an omni channel merchant that has multiple physical stores as well as a e-commerce website. Each of the stores and the e-commerce website will have at least two merchant acceptors underneath assuming they process Visa and Mastercard for example. The acceptor level tags can be used to assign the pairs (or groups) of acceptors to distinguish each physical store and the e-commerce website.