Skip to content

Merchant hierarchy

How merchants, projects, users and roles fit together, and how permissions are inherited from the merchant down.

Every business on your platform has two levels: the merchant, the business you have an agreement with, and its projects, the places where it accepts payments. Users and roles decide who may log in and what they may do. Permissions flow down from the merchant: nothing below it can do more than the merchant is allowed.

flowchart

Merchants

A merchant is the legal and financial identity of a business: the party that signs the agreement with you. There is one merchant per business, at the top of the hierarchy.

The merchant holds:

  • Legal identity: company name, VAT and chamber of commerce number, addresses, contact persons.
  • Compliance: the information you use to onboard and verify the business.
  • Money: the bank account, payouts and billing.
  • Base permissions: the ceiling of what the merchant and everything under it may do, such as which payment methods it may use. Only you set them.
  • Card settings: its credit-card contract, with one-click and recurring payments for all its projects. See Merchant card settings.
  • Users and roles: the people who log in to the Merchant portal.

Projects

A project is one place where the merchant accepts payments: a webshop, an app, a brand or a market. Projects process the payments. A merchant has as many projects as it needs, and each one works on its own.

A merchant uses separate projects to keep payment flows apart, for example:

  • A webshop and a mobile app.
  • Different brands or trade names under one company.
  • One project per country or currency.
  • A test project next to the live one.

The project holds:

  • Trading identity: the trade name, description and website your merchant's customers see.
  • Integration: the API key and webhook URL that connect the webshop or app to your platform.
  • Payment methods: which methods are enabled, and their settings.
  • Processor contracts: one per processor or payment method, with the identifiers, currencies and capture modes. See Processor contracts.
  • Checkout: the look of the hosted payment page.
  • Permissions: what the project's API key may do, within the limits of the merchant.
  • Status: test or live. See Project statuses.

A merchant has a test project and a live project for each webshop or app. They work the same way, with the same API and the same portal: only the API key and the contracts differ.

Merchant or project

MerchantProject
RepresentsThe legal businessOne place where it accepts payments
How manyOne per businessOne or more per merchant
OwnsAgreement, compliance, bank account, payouts, billing, users and rolesAPI key, webhook URL, payment methods, processor contracts, checkout settings
AnswersWho gets paid?Where and how is the payment taken?
Changes whenThe legal or banking details of the business changeThe business adds a shop, brand, app or market

Users and roles

Users log in to the portals. There are two kinds:

  • Merchant users belong to one merchant and only see its data. They log in to the Merchant portal.
  • System users are your own staff. They see every merchant and log in to the Admin portal.

A role is a named set of permissions, for example for the finance team or the developers. You give users one or more roles, and a user can also have permissions of their own. Users and roles belong to the merchant, and apply across its projects.

How permissions are inherited

Permissions decide what a project's API key, a user or a role may do. They are inherited from the top down:

  1. The merchant's base permissions are the ceiling. You set them in the Admin portal: which payment methods the merchant may use, and which actions are allowed.
  2. A project starts with the base permissions of its merchant. You can narrow them per project, never widen them.
  3. A role has a set of permissions within the base permissions of the merchant.
  4. A user has the permissions of all their roles together, plus their own. A user can only give another user permissions they have themselves.

When you save the permissions of a project, role or user, the platform drops every permission the merchant doesn't have. Merchants can't change the payment method permissions of their projects: only you can, in the Admin portal.

A payment method works on a project when three things are true:

  • The merchant may use it: it's in the base permissions.
  • The project may use it: it's in the project's permissions.
  • The merchant has switched it on for the project.

The project also needs a contract for the payment method: see Processor contracts.

For the full reference of path and field permissions, see Permissions.

Example: Acme

Acme sells online in the Netherlands and Germany, and has a mobile app.

  • Merchant Acme: one agreement, one bank account, weekly payouts, onboarded and verified once. Three users have access to the Merchant portal.
  • Project acme.nl: cards and Apple Pay, with a Dutch checkout.
  • Project acme.de: cards and Google Pay, with a German checkout.
  • Project Acme app: cards only, connected to the mobile app with its own API key and webhook URL.

Acme's base permissions allow cards, Apple Pay and Google Pay. None of the projects can use a payment method outside them. You narrow the permissions of the Acme app project to cards, so the app can't take Apple Pay or Google Pay even if someone switches them on.

Next steps