02. Actors and Access Model

Status: draft for discussion

1. Goal

This document describes system actors and business expectations for access.

It is not a technical authorization model or a permission matrix.

2. Platform User

A platform user acts on behalf of our platform.

They can:

• manage merchants;
• work with platform-level settings;
• work in a merchant context;
• grant provider access to a merchant;
• manage roles;
• investigate transactions deeper than merchant users;
• see internal provider data only within the limits of their role.

3. Merchant User

A merchant user works within the merchants or merchant groups available to them.

They can:

• view transactions;
• work with payment methods inside available brands;
• manage users, API keys, and webhooks if their role allows it;
• invite other users if their role allows it;
• see provider details only if separate provider access has been granted.

4. Customer

Customer is the end user who goes through the payment flow.

They should see a simple payment experience:

• open Hosted Payment Page;
• fill additional fields when needed;
• proceed to payment;
• never see routing, providers, or technical statuses.

5. Provider

Provider is an external payment partner.

Provider participates in the execution path, but must not make the merchant or customer experience more complex.

Real provider names are hidden from merchant users unless the business grants separate access.

6. Access Principles

Access is based on:

• user type;
• role;
• merchant context;
• merchant group context;
• provider access;
• visibility rules.

The development team should propose the technical authorization model and permission names.