# 

## Account model

Reefpay organizes accounts as **clients**. Each client has a `type` that determines its role in the hierarchy.

| Client type | Description | Can process transactions | Can manage sub-accounts |
|  --- | --- | --- | --- |
| `reseller` | An organization that onboards and manages merchants (ISOs, agents, acquirers, payment facilitators) | No (transactions flow through merchant children) | Yes |
| `merchant` | A business that processes payments through Reefpay | Yes | No |


Every client has:

* A unique `id` (for example, `CLIENT-3MtwBwLkdIwHu7ix28a3tqPa`)
* A `parent_id` that links it to its parent in the hierarchy
* A `dba` (doing-business-as) name
* Admin contact details


## Hierarchy structure

The hierarchy is a tree. Resellers sit above merchants and can have other resellers as children, enabling multi-level distribution models.

![image](https://files.modern-mermaid.live/images/1776271376268-mermaid-diagram-1776271376228.png)

### How `parent_id` works

Each client's `parent_id` points to the client directly above it in the tree.

| Client | Type | `parent_id` |
|  --- | --- | --- |
| Reseller A | `reseller` | Platform root |
| Merchant 1 | `merchant` | Reseller A |
| Sub-reseller | `reseller` | Reseller A |
| Merchant 3 | `merchant` | Sub-reseller |


A reseller can view and manage all clients beneath it in the tree — including clients under its sub-resellers.

## Merchants

A merchant is a business entity that processes payment transactions. Each merchant has:

* One or more **MIDs** (Merchant Identification Numbers) assigned by the processor
* **Integrations** with payment processors (TSYS for cards, Vericheck for ACH)
* **Users** who can access the API and web portal
* **Payment tokens** scoped to that merchant
* **Batches** and **transactions** associated with their MIDs


Merchants are always leaf nodes in the hierarchy — they cannot have child accounts.

## Resellers

A reseller is an organization that onboards, manages, and supports merchants. Resellers can:

* **Create merchant accounts** under their hierarchy
* **Create sub-resellers** for multi-level distribution
* **View transactions and reports** across all merchants in their tree
* **Manage users** for their own account and child accounts
* **Configure integrations** for child merchants


Resellers do not process transactions directly. All payment processing happens at the merchant level.

## Creating a client

Create a new client (merchant or reseller) with `POST /v1/clients`.

```json
POST /v1/clients

{
  "dba": "Acme Jewelry",
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "merchant",
  "admin_contact_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "time_zone": "America/New_York"
  }
}
```

### Required fields

| Field | Description |
|  --- | --- |
| `dba` | Business name (1–100 characters) |
| `parent_id` | ID of the parent client (reseller) |
| `type` | `merchant` or `reseller` |
| `admin_contact_details` | Contact information including `first_name`, `last_name`, `email`, `phone`, `time_zone` |


Who can create clients
Only reseller accounts (or platform administrators) can create child clients. A merchant cannot create sub-accounts.

## Managing clients

| Operation | Endpoint | Description |
|  --- | --- | --- |
| Create | `POST /v1/clients` | Create a merchant or reseller |
| List | `GET /v1/clients` | List all clients in your hierarchy |
| Retrieve | `GET /v1/clients/{id}` | Get details for a specific client |
| Update | `POST /v1/clients/{id}` | Update client details (DBA name, contact info) |


## Integrations

Before a merchant can process transactions, it must have at least one **integration** with a payment processor.

| Processor | Integration type | Payment types |
|  --- | --- | --- |
| TSYS | Card processing | Credit/debit card sales, authorizations, captures, cancels, refunds |
| Vericheck | ACH processing | Bank account payments, payouts, cancels |


Integrations are created with `POST /v1/integrations` and are scoped to a specific client. Each integration provides the processor credentials (MID, terminal ID) needed for transaction routing.

For more information, see [Supported processors](/docs/get-started/supported-processors).

## Data isolation

Reefpay enforces strict data isolation between clients.

| Scope | Rule |
|  --- | --- |
| Transactions | Visible only to the merchant that processed them and its parent resellers |
| Payment tokens | Scoped to the merchant MID — cannot be used across merchants |
| API keys | Authenticate to a specific client — cannot access other clients' data |
| Users | Belong to a single client; reseller users can access child client data |
| Batches | Contain only transactions from the associated merchant |


## Common patterns

### Payment facilitator (PayFac)

A PayFac registers as a reseller and onboards sub-merchants under its account. The PayFac manages compliance and settlement, while each sub-merchant has its own MID and transaction history.

### ISO / agent model

An Independent Sales Organization (ISO) or agent registers as a reseller to manage a portfolio of merchants. The ISO can view aggregate reporting across all merchants and manage their integrations.

### Direct merchant

A merchant that integrates directly with Reefpay (no reseller) has its `parent_id` set to the platform root.

## Further reading

* [About users and roles](/docs/concepts/account-hierarchy/users-and-roles)
* [Supported processors](/docs/get-started/supported-processors)