# Rejestracja submerchantów

Każdy Twój Klient, który ma przyjmować płatności przez SimPay Flow, musi zostać zarejestrowany jako submerchant Twojej usługi Flow, a następnie przejść onboarding.

## Krok 1: Rejestracja submerchanta

Submerchanta rejestrujesz żądaniem [`POST /flow/{flowServiceId}/submerchants`](/apis/flow/flowcreatesubmerchant).


```bash
curl -X POST "https://api.simpay.pl/flow/{flowServiceId}/submerchants" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customId": "user-123",
    "email": "jan.kowalski@example.com",
    "name": "Jan Kowalski"
  }'
```

| Pole | Opis |
|  --- | --- |
| `customId` | **Wymagane.** Twoje własne ID submerchanta, np. ID użytkownika w Twoim systemie. Maks. 36 znaków (`a-z`, `A-Z`, `0-9`, `-`, `_`), unikalne w ramach usługi Flow, nie może zaczynać się od `flsm_`. |
| `email` | **Wymagane.** Adres email submerchanta, unikalny w ramach usługi Flow. |
| `name` | Nazwa submerchanta (firmy). |
| `service` | Dane usługi Płatności Online submerchanta (nazwa, URL, regulamin, MCC, dane kontaktowe). **Wymagane dla instytucji płatniczych.** |


Usługa Flow musi być aktywna
Submerchantów możesz rejestrować dopiero po akceptacji usługi Flow przez SimPay. W przeciwnym wypadku API zwróci błąd `FLOW_SERVICE_NOT_ACTIVE`.

### Odpowiedź


```json
{
  "success": true,
  "message": "Submerchant successfully registered",
  "data": {
    "submerchantId": "flsm_aaaabbbb",
    "customId": "user-123",
    "onboarding": {
      "action": "redirect_user",
      "redirectUrl": "https://panel.simpay.pl/..."
    }
  }
}
```

Zapisz `submerchantId` w swojej bazie danych. Obiekt `onboarding` mówi, co dalej:

| `action` | Co robisz |
|  --- | --- |
| `redirect_user` | Przekieruj submerchanta na `redirectUrl` - onboarding odbywa się w Panelu SimPay. Zobacz [Onboarding przez Panel SimPay](/simpay-flow/onboarding/redirect). |
| `provide_api` | Przekaż dane submerchanta przez API. Zobacz [Onboarding przez API](/simpay-flow/onboarding/api). |


## Krok 2: Onboarding

Sposób onboardingu zależy od roli Twojej usługi Flow:

1. [Onboarding przez Panel SimPay](/simpay-flow/onboarding/redirect) - dla platform marketplace i produktów niepośredniczących w przekazywaniu środków (`role_non_financial_provider`). Submerchant przechodzi pełną weryfikację w SimPay.
2. [Onboarding przez API](/simpay-flow/onboarding/api) - dla regulowanych instytucji płatniczych (`role_payment_service_provider`). Procedura jest uproszczona, a dane przekazujesz Ty.


## Identyfikacja submerchanta

We wszystkich endpointach SimPay Flow (oraz w nagłówku `x-sim-flow-submerchant`) submerchanta możesz wskazać na dwa sposoby:

- przez **ID SimPay** - `flsm_aaaabbbb`,
- przez **Twoje `customId`** - `user-123`.


Dzięki temu nie musisz przechowywać ID SimPay, jeśli wygodniej Ci posługiwać się własnymi identyfikatorami.

## Statusy submerchanta

| Status | Znaczenie |
|  --- | --- |
| `flow_submerchant_pending` | Submerchant zarejestrowany, oczekuje na onboarding. |
| `flow_submerchant_in_verification` | Dane zostały przekazane, trwa weryfikacja przez SimPay. |
| `flow_submerchant_active` | Submerchant aktywny - może przyjmować płatności. |
| `flow_submerchant_inactive` | Submerchant nieaktywny (np. odrzucony lub zablokowany). |


Większość operacji (kanały płatności, tworzenie transakcji, zlecanie wypłat) jest dostępna wyłącznie dla submerchantów w statusie `flow_submerchant_active`. Dla pozostałych API zwraca błąd `FLOW_SUBMERCHANT_NOT_ACTIVE`.

Aktualny status sprawdzisz przez [`GET /flow/{flowServiceId}/submerchants/{submerchantId}`](/apis/flow/flowgetsubmerchant), ale zalecamy reagowanie na [webhook](/simpay-flow/webhooks) `flow_submerchant:status_changed` zamiast cyklicznego odpytywania API.