Entities & Hierarchy

The hierarchy between the different accounts is visualised below and consists of the following entities:

An Agent is the client’s top level entity in the Silverflow hierarchy. It is a legal entity that has a commercial relationship with Silverflow and uses the Silverflow API to process card transactions. The client receives the Agent and an activation token from Silverflow once a signed contract is in place. Activation of the agent returns the Master API key to the client. This key can be used to generate other API keys. The agent owns the master API key and is responsible for creating and managing additional API keys.

A Bank Identification Number (‘BIN’) is the number used to identify the acquirer on the card network. Typically, an acquirer will have a different BIN number for each network. An acquirer may also have multiple BINs per card network. BINs are created by and assigned to an agent by Silverflow once the BIN has been 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.​

A Merchant Acceptor is a child entity of a merchant and is linked to a BIN configured by the agent. The merchant acceptor contains the required data to process card payments, such as the mid, the doingBusinessAsName and the mcc. Since one merchant acceptor is required for each BIN, a merchant processing two card networks (e.g. Visa and Mastercard) will require at least two merchant acceptors. Additional merchant acceptors can be created in situations where a merchant needs to operate with different MCCs per network.

Tags are a customizable, optional properties that can be assigned to the Merchant and/or to the Merchant Acceptor. They allow clients to organize their merchants and acceptors into groups, such as regions, departments, or franchise groups without having to create separate entities. As a result, clients can generate customised reporting and perform analysis based on the hierarchy that fits them the best. We recommend using consistent naming conventions and documenting the purpose and usage of each tag to ensure clarity and consistency.

Tags can be assigned to the merchant at the time of creation of the merchant or at a later point in time by updating the 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.