# What is SimPay Flow?

SimPay Flow lets you accept payments **on behalf of your Customers** (submerchants) within a single SimPay account and a single API integration.

SimPay Flow is designed for:

- **marketplace platforms**,
- **products in which your Customers accept payments** - fundraising systems, invoicing systems, ERP applications, booking systems, etc.,
- **regulated payment institutions**.


## Key concepts

| Concept | Description |
|  --- | --- |
| **Flow service** | Your service in SimPay Flow (ID in the `flow_xxxxxxxx` format). You create it in the SimPay Partner Panel, and it must be approved by SimPay before use. |
| **Parent service** | The Online Payments service linked to the Flow service. You pass its `serviceId` in `/payment/{serviceId}/...` requests when creating transactions for submerchants. |
| **Submerchant** | Your Customer, registered by you in the Flow service. It has its own ID (`flsm_xxxxxxxx`) and a `customId` assigned by you. |
| **Submerchant service** | The submerchant's Online Payments service, created automatically during registration. You never use it directly - you always create transactions through the parent service. |
| **Submerchant wallet** | The submerchant's balance, which receives funds from its transactions and from which withdrawals are made. |


## Flow service roles

Every Flow service has one of two roles. The role determines how submerchant onboarding and settlement work.

### Platforms (`role_non_financial_provider`)

For marketplaces and products that **do not intermediate in the transfer of funds**.

- The submerchant goes through full onboarding at SimPay - verification of billing data, UBO data, identity document (or mObywatel) and a verification transfer. Details: [Onboarding via SimPay Panel](/en/simpay-flow/onboarding/redirect).
- SimPay settles with the submerchant - funds go to the submerchant's wallet and are paid out to its bank account.
- You receive a [commission](/en/simpay-flow/commissions) on submerchant transactions.
- Apart from onboarding, you handle everything for the submerchant - payment channels, withdrawals, reports - through the [SimPay Flow API](/apis/flow) in your application.


### Payment institutions (`role_payment_service_provider`)

For **regulated payment institutions (PI)** that are responsible for their own submerchants.

- Onboarding is simplified - via the API you provide basic company data (or unregistered business data), simplified UBO data and the submerchant's Online Payments service data. Details: [Onboarding via API](/en/simpay-flow/onboarding/api).
- All funds are transferred to the PI, and settlement with submerchants is handled by the PI.
- PIs mainly use SimPay Flow to register submerchants for additional payment methods, e.g.:
  - PayPo,
  - Twisto,
  - PaysafeCard,
  - BLIK Level 0 + OneClick,
  - BLIK Recurring Payments,
  - LATAM.
The PI requests the registration of a payment channel for a submerchant via the API, and SimPay registers it with the payment method operator on behalf of the PI.


## What does the integration look like?

1. **Create a Flow service** in the SimPay Partner Panel and wait for its approval (status `flow_service_active`).
2. **Generate an API key** with SimPay Flow permissions (see [API key permissions](#api-key-permissions)).
3. **Register a submerchant** via the API - [Submerchant registration](/en/simpay-flow/onboarding).
4. **Complete the submerchant onboarding** and wait until its status changes to `flow_submerchant_active` - you will be notified by a [webhook](/en/simpay-flow/webhooks).
5. **Configure the submerchant's payment channels** - [Payment channels](/en/simpay-flow/channels).
6. **Accept payments** on behalf of the submerchant - [Payments](/en/simpay-flow/payments).
7. **Handle finances** - balance, withdrawals, reports and invoices - [Finances and withdrawals](/en/simpay-flow/finances).


## API key permissions

SimPay Flow endpoints require an API key with the appropriate permissions. Grant the key only the permissions you actually need.

| Permission | Scope |
|  --- | --- |
| `flow.services` | View Flow services |
| `flow.submerchants` | View submerchants |
| `flow.submerchants.create` | Register submerchants |
| `flow.submerchants.onboardings` | Submerchant onboarding |
| `flow.submerchants.widget` | Generate submerchant widget links |
| `flow.payment_methods` | View and enable/disable payment channels |
| `flow.payment_methods.register` | Register new payment channels |
| `flow.submerchants.webhooks` | View submerchant webhook settings |
| `flow.submerchants.webhooks.update` | Change submerchant webhook settings and keys |
| `flow.submerchants.finances` | View wallets and operations |
| `flow.submerchants.finances.reports` | Generate CSV reports |
| `flow.submerchants.finances.invoices` | View commission invoices |
| `flow.submerchants.withdraws` | View withdrawals |
| `flow.submerchants.withdraws.create` | Request withdrawals |
| `flow.submerchants.withdraws.settings` | Change wallet withdrawal settings |


To create transactions on behalf of submerchants, you also need the standard Online Payments permissions (`payment.*`).