# Czym jest SimPay Flow?

SimPay Flow pozwala Ci przyjmować płatności **w imieniu Twoich Klientów** (submerchantów) w ramach jednego konta SimPay i jednej integracji API.

SimPay Flow jest przeznaczony dla:

- **platform marketplace**,
- **produktów, w których Twoi Klienci przyjmują płatności** - systemy zbiórek, systemy fakturowe, aplikacje ERP, systemy rezerwacji itp.,
- **regulowanych instytucji płatniczych**.


## Podstawowe pojęcia

| Pojęcie | Opis |
|  --- | --- |
| **Usługa Flow** | Twoja usługa w SimPay Flow (ID w formacie `flow_xxxxxxxx`). Zakładasz ją w Panelu Partnera SimPay, a przed użyciem musi zostać zaakceptowana przez SimPay. |
| **Usługa nadrzędna** | Usługa Płatności Online powiązana z usługą Flow. To jej `serviceId` podajesz w żądaniach `/payment/{serviceId}/...`, gdy tworzysz transakcje dla submerchantów. |
| **Submerchant** | Twój Klient, zarejestrowany przez Ciebie w usłudze Flow. Ma własne ID (`flsm_xxxxxxxx`) oraz nadany przez Ciebie `customId`. |
| **Usługa submerchanta** | Usługa Płatności Online submerchanta, tworzona automatycznie przy rejestracji. Nie używasz jej bezpośrednio - transakcje tworzysz zawsze przez usługę nadrzędną. |
| **Portfel submerchanta** | Saldo submerchanta, na które trafiają środki z jego transakcji i z którego realizowane są wypłaty. |


## Role usługi Flow

Każda usługa Flow ma jedną z dwóch ról. Rola decyduje o tym, jak wygląda onboarding submerchantów i rozliczenie.

### Platformy (`role_non_financial_provider`)

Dla marketplace'ów i produktów, które **nie pośredniczą w przekazywaniu środków**.

- Submerchant przechodzi pełny onboarding w SimPay - weryfikację danych rozliczeniowych, danych UBO, dokumentu tożsamości (lub mObywatela) oraz przelew weryfikacyjny. Szczegóły: [Onboarding przez Panel SimPay](/simpay-flow/onboarding/redirect).
- Rozliczenie z submerchantem prowadzi SimPay - środki trafiają na portfel submerchanta i są wypłacane na jego rachunek.
- Ty otrzymujesz [prowizję](/simpay-flow/commissions) od transakcji submerchantów.
- Poza onboardingiem całą obsługę submerchanta - kanały płatności, wypłaty, raporty - realizujesz przez [API SimPay Flow](/apis/flow) w swojej aplikacji.


### Instytucje płatnicze (`role_payment_service_provider`)

Dla **regulowanych instytucji płatniczych (IP)**, które same odpowiadają za swoich submerchantów.

- Onboarding jest uproszczony - przekazujesz przez API podstawowe dane firmy (lub działalności nierejestrowanej), uproszczone dane UBO oraz dane usługi Płatności Online submerchanta. Szczegóły: [Onboarding przez API](/simpay-flow/onboarding/api).
- Całość środków jest przekazywana do IP, a rozliczenie z submerchantami leży po stronie IP.
- SimPay Flow służy IP głównie do zgłaszania submerchantów do dodatkowych metod płatności, np.:
  - PayPo,
  - Twisto,
  - PaysafeCard,
  - BLIK Level 0 + OneClick,
  - BLIK Płatności Powtarzalne,
  - LATAM.
IP zgłasza przez API rejestrację kanału płatności dla submerchanta, a SimPay w imieniu IP zgłasza go u operatora metody płatności.


## Jak wygląda integracja?

1. **Załóż usługę Flow** w Panelu Partnera SimPay i poczekaj na jej akceptację (status `flow_service_active`).
2. **Wygeneruj klucz API** z uprawnieniami do SimPay Flow (patrz [Uprawnienia klucza API](#uprawnienia-klucza-api)).
3. **Zarejestruj submerchanta** przez API - [Rejestracja submerchantów](/simpay-flow/onboarding).
4. **Przeprowadź onboarding** submerchanta i poczekaj, aż jego status zmieni się na `flow_submerchant_active` - informację otrzymasz [webhookiem](/simpay-flow/webhooks).
5. **Skonfiguruj kanały płatności** submerchanta - [Kanały płatności](/simpay-flow/channels).
6. **Przyjmuj płatności** w imieniu submerchanta - [Płatności](/simpay-flow/payments).
7. **Obsłuż finanse** - saldo, wypłaty, raporty i faktury - [Finanse i wypłaty](/simpay-flow/finances).


## Uprawnienia klucza API

Endpointy SimPay Flow wymagają klucza API z odpowiednimi uprawnieniami. Nadaj kluczowi tylko te uprawnienia, których faktycznie potrzebujesz.

| Uprawnienie | Zakres |
|  --- | --- |
| `flow.services` | Podgląd usług Flow |
| `flow.submerchants` | Podgląd submerchantów |
| `flow.submerchants.create` | Rejestracja submerchantów |
| `flow.submerchants.onboardings` | Onboarding submerchantów |
| `flow.submerchants.widget` | Generowanie linków do widgetu submerchanta |
| `flow.payment_methods` | Podgląd i włączanie/wyłączanie kanałów płatności |
| `flow.payment_methods.register` | Rejestracja nowych kanałów płatności |
| `flow.submerchants.webhooks` | Podgląd ustawień webhooków submerchanta |
| `flow.submerchants.webhooks.update` | Zmiana ustawień i kluczy webhooków submerchanta |
| `flow.submerchants.finances` | Podgląd portfeli i operacji |
| `flow.submerchants.finances.reports` | Generowanie raportów CSV |
| `flow.submerchants.finances.invoices` | Podgląd faktur prowizyjnych |
| `flow.submerchants.withdraws` | Podgląd wypłat |
| `flow.submerchants.withdraws.create` | Zlecanie wypłat |
| `flow.submerchants.withdraws.settings` | Zmiana ustawień wypłat portfela |


Do tworzenia transakcji w imieniu submerchantów potrzebujesz dodatkowo standardowych uprawnień Płatności Online (`payment.*`).