Ś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.
Submerchant może mieć kilka portfeli (np. w różnych walutach). Listę pobierzesz przez GET .../submerchants/{submerchantId}/finances, a pojedynczy portfel przez GET .../finances/{walletId}.
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) |
Typ wypłat ustawiasz żądaniem PATCH .../finances/{walletId}.
withdraw.type | Działanie | Wymagane pola |
|---|---|---|
manual | Wypłaty wyłącznie na żądanie - zlecasz je przez API | - |
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.
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
}
}'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.
Jeśli portfel ma typ wypłat manual, wypłatę zlecasz żądaniem POST .../finances/{walletId}/withdraws. 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 (filtry: id, shortId, status). Statusy wypłaty: new, accepted, waiting, done, rejected. O każdej zmianie statusu poinformujemy webhookiem flow_submerchant_withdraw:status_changed.
GET .../finances/{walletId}/transactions 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.
POST .../finances/{walletId}/raport 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.
GET .../finances/invoices zwraca miesięczne faktury prowizyjne submerchanta wraz z linkiem do pobrania (invoiceUrl). Język faktur ustawisz polem invoiceLocale portfela.