# Bookkeeping and payouts

> Two entries per order: when it is paid, and when the money reaches the bank.

The clinic has a receivable from the patient when the visit is over. That receivable is settled when the order is paid, and the money reaches the clinic's account in a nightly settlement. A journal that keeps the clinic's books therefore posts two entries per order — a day or a month apart.

- Market: Sweden (`se`). Norway differs in currency, payment methods and what happens when nobody pays: https://developers.rivr.io/guides/bookkeeping.md?market=no
- Language: English (`en`). Svenska: https://developers.rivr.io/guides/bookkeeping.md?lang=sv
- 6 min read · 5 steps
- Page in the portal: https://developers.rivr.io/guides/bookkeeping

Every example targets the sandbox (`https://api.test.rivr.io`) and needs test credentials. A platform client's tokens come from `https://auth.test.rivr.io`, an organisation key's from `https://auth.test.rivr.tech`.

## 1. The receivable from the patient already exists

*Journal system*

When the visit is checked out the journal has a receivable from the patient, just as today. Creating a Rivr order changes nothing in the books.

**Order status:** `Created` · **The journal shows:** Unpaid

## 2. Step A — on Completed

*Rivr → Journal system*

When the `Completed` webhook arrives, the patient is done. Move the receivable from the patient to a receivable from Rivr.

**Why:** The patient's debt is settled, but the money has not reached the clinic's account yet. Booking it straight to the bank would give a balance that doesn't match the bank statement until after the settlement.

> **Rule.** Only on `Completed` — never on `Created` or `Pending`.

**Order status:** `Completed` · **The journal shows:** Paid

**Webhook to you** (`Completed`)

```http
POST /webhooks/rivr
Content-Type: application/json
Rivr-Signature: t=1789640080,v1=5f2b0c…

{
  "id": "7b1e7c3a-2f4d-4a51-9c7e-5d0a6b8e2c14",
  "type": "Order",
  "merchantId": "MERCHANT_ID",
  "status": "Completed",
  "data": {
    "CreatedDate": "2026-09-17T09:12:03Z",
    "Reference": "visit-48213",
    "CompletedDate": "2026-09-17T09:14:40Z",
    "PaymentMethod": "Swish",
    "Metadata": { "bookingId": "48213" }
  }
}
```

**Bookkeeping (example)**

| Account | Debit | Credit |
| --- | ---: | ---: |
| 1580 Receivable from Rivr | 950.00 |  |
| 1510 Accounts receivable (patient) |  | 950.00 |

## 3. Rivr makes a settlement

*Rivr · 00:00*

Every night at midnight Swedish time Rivr compiles settlements per clinic with the orders that were paid or refunded. Depending on how the money came in, a clinic normally gets up to three settlements the same night.

## 4. Fetch the settlement

*Journal system → Rivr*

List settlements with `GET /api/public/order-settlements` and fetch each with `GET /api/public/order-settlements/{id}`. The detail groups orders by payment method: `orders` for paid and `refundedOrders` for refunded, each with `orderId`, `reference` and your `metadata`. The currency is in `settlementInfo.ledger.currency`, not at the top level.

**What your system does:** Match on `orderId`. Record which settlements you have booked, so an interrupted run can be repeated without double booking.

> **Warning.** There is also `GET …/next-unread`, but it **marks the settlement as read in the same call**. If you lose the response, it is used up. List and fetch instead, and keep track yourself.

**Request:** `GET /api/public/order-settlements/SETTLEMENT_ID` · Merchant token · [Reference](https://developers.rivr.io/reference/api-public/getOrderSettlement.md)

```bash
curl -X GET https://api.test.rivr.io/api/public/order-settlements/SETTLEMENT_ID \
  -H "Authorization: Bearer $MERCHANT_TOKEN"
```

**Response (excerpt)**

```json
{
  "id": "SETTLEMENT_ID",
  "merchantId": "MERCHANT_ID",
  "settlementNumber": "…",
  "reference": "…",
  "preparedDate": "2026-09-17T22:00:12Z",
  "payoutCompletedDate": "2026-09-18T…",
  "totalAmount": 950.00,
  "settlementInfo": { "ledger": { "currency": "SEK" } },
  "ordersByPaymentMethod": [
    {
      "paymentMethod": 64,
      "completedAmount": 950.00,
      "refundedAmount": 0,
      "orders": [
        {
          "orderId": "7b1e7c3a-2f4d-4a51-9c7e-5d0a6b8e2c14",
          "reference": "visit-48213",
          "totalAmountInclVat": 950.00,
          "vatPercentage": 0,
          "metadata": { "bookingId": "48213" }
        }
      ],
      "refundedOrders": []
    }
  ]
}
```

**In the portal:** [See the clinic's settlements](https://developers.rivr.io/settlements)

## 5. Step B — the money in the bank

*Clinic's bank → Journal system · 04:00*

Payouts are created at 04:00 on banking days, for some clinics a few days later according to the clinic's settings. Once the settlement has `payoutCompletedDate` the payout is done. Book the deposit against the receivable from Rivr.

**Bookkeeping (example)**

| Account | Debit | Credit |
| --- | ---: | ---: |
| 1930 Business account | 950.00 |  |
| 1580 Receivable from Rivr |  | 950.00 |

## Common pitfalls

- The account numbers above are BAS examples. Check them with the clinic's accountant.
- Amounts in the settlement list are objects (`{ "money": { "value": 95000, "decimals": 2 }, … }`), while the detail gives major units as decimals. Do the maths on the detail.
- `paymentMethod` in the settlement is Rivr's internal code as a number (e.g. 64 Swish, 256 Card, 1024 invoice through the financing partner) — not the same values as in the webhook. Refunded orders sit under `0`. Match on `orderId`, not on payment method.
- Counting one row per order. An order with several VAT rates has one row per rate — sum per `orderId`. `vatPercentage` is a fraction (0.25), not a percentage.

## Next guide

- [Cancel and refund](https://developers.rivr.io/guides/cancel-refund.md): Cancel an unpaid order, pay back a paid one — and wait for the webhook.
- [The checklist before the first clinic](https://developers.rivr.io/guides/go-live.md): What must be proven in test before a real clinic is switched on.