# Finanse i wypłaty

Środki z transakcji submerchanta trafiają na jego **portfel** w SimPay. Przez API SimPay Flow możesz pokazać submerchantowi saldo i historię operacji, skonfigurować wypłaty, zlecać je ręcznie oraz pobierać raporty i faktury.

## Portfele

Submerchant może mieć kilka portfeli (np. w różnych walutach). Listę pobierzesz przez [`GET .../submerchants/{submerchantId}/finances`](/apis/flow/flowgetsubmerchantwallets), a pojedynczy portfel przez [`GET .../finances/{walletId}`](/apis/flow/flowgetsubmerchantwallet).

Najważniejsze pola portfela:

| Pole | Opis |
|  --- | --- |
| `id` | ID portfela (UUID) - używasz go w pozostałych endpointach finansowych |
| `balance` | Aktualne saldo |
| `currency.isoCode` | Waluta portfela |
| `withdrawType` | Typ wypłat (patrz niżej) |
| `invoiceLocale` | Język faktur prowizyjnych (`pl` / `en`) |


## Ustawienia wypłat

Typ wypłat ustawiasz żądaniem [`PATCH .../finances/{walletId}`](/apis/flow/flowupdatesubmerchantwallet).

| `withdraw.type` | Działanie | Wymagane pola |
|  --- | --- | --- |
| `manual` | Wypłaty wyłącznie na żądanie - [zlecasz je przez API](#zlecanie-wyp%C5%82aty) | - |
| `workdays` | Automatyczna wypłata w każdy dzień roboczy | - |
| `balance_greater_than` | Automatyczna wypłata, gdy saldo przekroczy `balanceToAutoPayout` | `balanceToAutoPayout` |
| `custom_days` | Automatyczna wypłata w wybrane dni tygodnia, gdy saldo przekroczy `balanceToAutoPayout` | `balanceToAutoPayout`, `customDays` |


Dodatkowo dla wypłat automatycznych możesz ustawić `leftBalance` - kwotę, która zawsze zostaje na portfelu.


```bash
curl -X PATCH "https://api.simpay.pl/flow/{flowServiceId}/submerchants/user-123/finances/{walletId}" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -d '{
    "withdraw": {
      "type": "custom_days",
      "customDays": [1, 5],
      "balanceToAutoPayout": 100.00,
      "leftBalance": 10.00
    }
  }'
```

Ustawienia są nadpisywane w całości
Każde przesłanie obiektu `withdraw` zastępuje wszystkie dotychczasowe ustawienia wypłat. Pola, których nie przekażesz, zostaną wyczyszczone.

`customDays` to dni tygodnia: `1` - poniedziałek, ..., `5` - piątek.

## Zlecanie wypłaty

Jeśli portfel ma typ wypłat `manual`, wypłatę zlecasz żądaniem [`POST .../finances/{walletId}/withdraws`](/apis/flow/flowcreatesubmerchantwithdraw). Zlecenie wypłaty jest możliwe tylko dla aktywnego submerchanta.

| Błąd | Przyczyna |
|  --- | --- |
| `ERR_MANUAL_WITHDRAWALS_DISABLED` | Portfel nie ma ustawionego typu wypłat `manual`. |
| `UBO_DOCUMENT_REVERIFICATION_REQUIRED` | Dokument tożsamości beneficjenta rzeczywistego wygasł - wypłaty są zablokowane do czasu zatwierdzenia nowego dokumentu. |
| `ERR_WITHDRAW_ERROR` | Wypłata nie może zostać zrealizowana - szczegóły w polu `message`. |


Historię wypłat pobierzesz przez [`GET .../finances/{walletId}/withdraws`](/apis/flow/flowgetsubmerchantwithdraws) (filtry: `id`, `shortId`, `status`). Statusy wypłaty: `new`, `accepted`, `waiting`, `done`, `rejected`. O każdej zmianie statusu poinformujemy [webhookiem](/simpay-flow/webhooks) `flow_submerchant_withdraw:status_changed`.

## Historia operacji

[`GET .../finances/{walletId}/transactions`](/apis/flow/flowgetsubmerchantwallettransactions) zwraca wszystkie operacje na portfelu:

| `action` | Operacja |
|  --- | --- |
| `service` | Wpłata z transakcji |
| `commission` | Prowizja od transakcji |
| `refund` | Zwrot transakcji (lub jego cofnięcie) |
| `withdraw` | Wypłata środków |
| `bank_fee` | Opłata banku za wypłatę |
| `fraud` | Operacja związana z transakcją oznaczoną jako fraud |


Lista korzysta z paginacji kursorowej - kolejną stronę pobierzesz, przekazując wartość `cursor.next.cursor` w parametrze `cursor`.

## Raporty CSV

[`POST .../finances/{walletId}/raport`](/apis/flow/flowsubmerchantwalletreport) generuje raport CSV operacji portfela:

- za wybrany okres - `{"date": {"from": "2026-09-01", "to": "2026-09-30"}}`,
- dla wybranej wypłaty - `{"withdraw": {"shortId": "1f2b3c4d"}}`. Raport obejmuje wtedy wszystkie operacje od poprzedniej wypłaty, czyli dokładnie to, z czego składa się dana wypłata.


## Faktury prowizyjne

[`GET .../finances/invoices`](/apis/flow/flowgetsubmerchantinvoices) zwraca miesięczne faktury prowizyjne submerchanta wraz z linkiem do pobrania (`invoiceUrl`). Język faktur ustawisz polem `invoiceLocale` portfela.