# Płatności w imieniu submerchanta

Transakcje dla submerchantów tworzysz przez standardowe [API Płatności Online](/apis/payment) - te same endpointy, co przy zwykłej integracji. Różnią się tylko dwa elementy:

1. w ścieżce podajesz `serviceId` **usługi nadrzędnej** (usługi Płatności Online powiązanej z Twoją usługą Flow),
2. w nagłówku `x-sim-flow-submerchant` wskazujesz submerchanta, w imieniu którego wykonujesz żądanie.


`serviceId` usługi nadrzędnej znajdziesz w polu `paymentService.id` w odpowiedzi [`GET /flow/{flowServiceId}`](/apis/flow/flowgetservice).

## Przykład: tworzenie transakcji


```bash
curl -X POST "https://api.simpay.pl/payment/{serviceIdUslugiNadrzednej}/transactions" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-sim-flow-submerchant: user-123" \
  -d '{
    "amount": 49.99,
    "description": "Zamówienie #1001",
    "control": "order-1001"
  }'
```

Transakcja zostanie utworzona w usłudze submerchanta `user-123`, a środki trafią na jego portfel (lub - dla instytucji płatniczych - zostaną rozliczone z IP).

## Nagłówek `x-sim-flow-submerchant`

|  |  |
|  --- | --- |
| **Wartość** | ID submerchanta (`flsm_...`) lub jego `customId` |
| **Kiedy wymagany** | W każdym żądaniu `/payment/{serviceId}/...`, gdy `serviceId` to usługa nadrzędna Twojej aktywnej usługi Flow |
| **Kiedy ignorowany** | Gdy `serviceId` to zwykła usługa Płatności Online, niepowiązana z Flow |


Nagłówek działa dla wszystkich endpointów Płatności Online - transakcji, zwrotów, kanałów, walut, subskrypcji, BLIK Level 0 i aliasów BLIK. Każde z tych żądań jest wykonywane w kontekście usługi wskazanego submerchanta. Przykładowo `GET /payment/{serviceId}/transactions` zwróci tylko transakcje danego submerchanta.

Nie używaj usługi submerchanta bezpośrednio
Każdy submerchant ma własną usługę Płatności Online, ale nie można jej używać bezpośrednio. Podanie jej ID jako `serviceId` zwróci błąd `422`. Zawsze używaj usługi nadrzędnej i nagłówka `x-sim-flow-submerchant`.

### Możliwe błędy

| Kod HTTP | `errorCode` | Przyczyna |
|  --- | --- | --- |
| `422` | `SIMPAY_FLOW_VALIDATION_ERROR` | Brak nagłówka dla usługi nadrzędnej Flow lub nieprawidłowa wartość. |
| `404` | `FLOW_SUBMERCHANT_NOT_FOUND` | Submerchant nie istnieje w ramach Twojej usługi Flow. |
| `403` | `FLOW_SUBMERCHANT_NOT_ACTIVE` | Submerchant nie zakończył onboardingu lub nie jest aktywny. |
| `400` | `FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_FOUND` / `FLOW_SUBMERCHANT_PAYMENT_SERVICE_NOT_ACTIVE` | Usługa Płatności Online submerchanta nie istnieje lub nie jest aktywna. |


## Powiadomienia o płatnościach

Powiadomienia IPN o transakcjach submerchantów działają tak samo jak przy zwykłej integracji - zobacz [Powiadomienia o płatnościach](/notifications/payment).

Domyślnie powiadomienia dla wszystkich submerchantów trafiają na adres IPN usługi nadrzędnej i są podpisywane jej kluczem. Dla wybranego submerchanta możesz ustawić osobny adres.

W powiadomieniach płatności dla submerchantów:

- `service_id` zawiera ID usługi nadrzędnej,
- nowy obiekt `data.flow` wskazuje submerchanta (`submerchant_id`, `submerchant_custom_id`) i usługę Flow - we wszystkich zdarzeniach poza `ipn:test`,
- w `transaction:status_changed` nowe pole `amount.commission_flow` zawiera Twoją prowizję Flow.


Szczegóły i przykład: [Webhooki płatności w SimPay Flow](/simpay-flow/webhooks#webhooki-p%C5%82atno%C5%9Bci-ipn-w-simpay-flow).