# Finances and withdrawals

Funds from submerchant transactions go to its **wallet** at SimPay. With the SimPay Flow API you can show the submerchant its balance and operation history, configure withdrawals, request them manually, and download reports and invoices.

## Wallets

A submerchant can have several wallets (e.g. in different currencies). You get the list with [`GET .../submerchants/{submerchantId}/finances`](/apis/flow/flowgetsubmerchantwallets), and a single wallet with [`GET .../finances/{walletId}`](/apis/flow/flowgetsubmerchantwallet).

Most important wallet fields:

| Field | Description |
|  --- | --- |
| `id` | Wallet ID (UUID) - you use it in the other finance endpoints |
| `balance` | Current balance |
| `currency.isoCode` | Wallet currency |
| `withdrawType` | Withdrawal type (see below) |
| `invoiceLocale` | Commission invoice language (`pl` / `en`) |


## Withdrawal settings

You set the withdrawal type with the [`PATCH .../finances/{walletId}`](/apis/flow/flowupdatesubmerchantwallet) request.

| `withdraw.type` | Behavior | Required fields |
|  --- | --- | --- |
| `manual` | Withdrawals on demand only - [you request them via the API](#requesting-a-withdrawal) | - |
| `workdays` | Automatic withdrawal on every business day | - |
| `balance_greater_than` | Automatic withdrawal when the balance exceeds `balanceToAutoPayout` | `balanceToAutoPayout` |
| `custom_days` | Automatic withdrawal on selected weekdays when the balance exceeds `balanceToAutoPayout` | `balanceToAutoPayout`, `customDays` |


Additionally, for automatic withdrawals you can set `leftBalance` - the amount that always stays in the wallet.


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

Settings are overwritten entirely
Each time you send the `withdraw` object, it replaces all existing withdrawal settings. Fields you don't send will be cleared.

`customDays` are weekdays: `1` - Monday, ..., `5` - Friday.

## Requesting a withdrawal

If the wallet has the `manual` withdrawal type, you request a withdrawal with the [`POST .../finances/{walletId}/withdraws`](/apis/flow/flowcreatesubmerchantwithdraw) request. Withdrawals can be requested only for an active submerchant.

| Error | Cause |
|  --- | --- |
| `ERR_MANUAL_WITHDRAWALS_DISABLED` | The wallet doesn't have the `manual` withdrawal type. |
| `UBO_DOCUMENT_REVERIFICATION_REQUIRED` | The ultimate beneficial owner's identity document has expired - withdrawals are blocked until a new document is approved. |
| `ERR_WITHDRAW_ERROR` | The withdrawal cannot be processed - details in the `message` field. |


You get the withdrawal history with [`GET .../finances/{walletId}/withdraws`](/apis/flow/flowgetsubmerchantwithdraws) (filters: `id`, `shortId`, `status`). Withdrawal statuses: `new`, `accepted`, `waiting`, `done`, `rejected`. We will notify you about each status change with the `flow_submerchant_withdraw:status_changed` [webhook](/en/simpay-flow/webhooks).

## Operation history

[`GET .../finances/{walletId}/transactions`](/apis/flow/flowgetsubmerchantwallettransactions) returns all wallet operations:

| `action` | Operation |
|  --- | --- |
| `service` | Deposit from a transaction |
| `commission` | Transaction commission |
| `refund` | Transaction refund (or its reversal) |
| `withdraw` | Funds withdrawal |
| `bank_fee` | Bank fee for the withdrawal |
| `fraud` | Operation related to a transaction flagged as fraud |


The list uses cursor pagination - to get the next page, pass the `cursor.next.cursor` value in the `cursor` parameter.

## CSV reports

[`POST .../finances/{walletId}/raport`](/apis/flow/flowsubmerchantwalletreport) generates a CSV report of wallet operations:

- for a selected period - `{"date": {"from": "2026-09-01", "to": "2026-09-30"}}`,
- for a selected withdrawal - `{"withdraw": {"shortId": "1f2b3c4d"}}`. The report then covers all operations since the previous withdrawal, i.e. exactly what the given withdrawal consists of.


The CSV column headers are in Polish - see the [endpoint specification](/apis/flow/flowsubmerchantwalletreport) for their translation.

## Commission invoices

[`GET .../finances/invoices`](/apis/flow/flowgetsubmerchantinvoices) returns the submerchant's monthly commission invoices with a download link (`invoiceUrl`). You set the invoice language with the wallet's `invoiceLocale` field.