Platform Overview

Miracle PSP is a modular payment platform that enables you to run your own PSP business. This page explains the core architecture and entity hierarchy.

Entity Hierarchy

Every piece of data in Miracle PSP belongs to a well-defined hierarchy. Understanding this hierarchy is essential for configuring your platform correctly.

BUSINESS HIERARCHY              PROCESSING INFRASTRUCTURE

Platform                        ProviderIntegration (provider library)
  └── Tenant (your PSP)          └── Terminal (tenant-level credentials)
       └── Company                        │
            └── Merchant                  │
                     │                    │
                     └── Channel ─────────┘
                          (bridge)

The two hierarchies are independent. Channel is the bridge that links a Merchant (business side) to a Terminal (processing side), defining which payment methods and routing rules apply.

Platform

Top-level system entity. Owns global configuration such as supported currencies, countries, and platform-wide settings. There is exactly one platform.

Tenant

Your organization. A tenant is a logically isolated PSP company within the platform. Each tenant has its own branding, configuration, fee schedules, routing rules, and merchant base. All data is scoped to a tenant via Row-Level Security — you never see another tenant's data.

Company

A legal entity within your tenant. Companies group merchants under a single legal umbrella. KYB (Know Your Business) verification happens at the company level.

Merchant

A business entity that accepts payments from customers. Every merchant belongs to a company and operates within a tenant. Merchants have their own balances, API keys, webhooks, and fee assignments.

Terminal

A tenant-level connection to a specific provider integration. Terminals hold provider credentials (securely stored in the vault) and define which provider processes the transactions routed through them. One terminal can serve multiple merchants — it has no merchantId.

Channel

A link between a specific merchant and a terminal, defining payment method scope and routing eligibility. A merchant can have multiple channels pointing to different terminals.

Partners

A Partner is a cross-cutting entity that brings merchants to the platform. Partners are linked to merchants via PartnerAssignment and earn commission on transactions processed by their assigned merchants.

Partners are not part of the main entity hierarchy — they exist alongside it and can be associated with merchants across different companies.

Multi-Tenancy

Miracle PSP uses a single database with logical isolation via PostgreSQL Row-Level Security (RLS). Every record in the system carries a tenantId, and all queries are automatically scoped to the current tenant.

This means:

• Each tenant sees only their own data — merchants, transactions, balances, configuration
• There is no data leakage between tenants
• Global platform configuration (currencies, provider integrations) is shared read-only

User Layers

Different users interact with Miracle PSP at different levels. Each user belongs to exactly one layer, which determines their scope of access and the portal experience they see.

Key Concepts

• Payin — incoming payment where a customer pays a merchant
• Payout — merchant sends money to a third-party recipient (a service product)
• Withdrawal — entity withdraws own available balance (requires operator approval)
• Settlement — financial statement document summarizing transactions, fees, and net amounts for a period (draft → finalized). Does NOT trigger withdrawals or payouts
• Availability Transition — automated T+N cron that moves funds from pending to available after N business days. Separate from settlement
• Fee decomposition — merchantFee = providerFee + platformFee + tenantFee + partnerCommission
• Livemode / Testmode — production vs. sandbox environments, toggled per session

For a complete list of terms, see the Glossary.

Next Steps

• First Steps — get operational after your tenant is provisioned
• Glossary — key terms and common confusions