# Payment in advance

> The patient pays before the treatment — the same flow, but the money becomes a credit.

The clinic wants payment up front, for a course of treatment for example. To Rivr it is an ordinary order. The difference is in the journal: the payment doesn't belong to a completed visit yet, but becomes a credit on the patient that later visits draw from.

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

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. Create an advance order

*Journal system → Rivr*

Create the order as usual, not linked to a treatment, and add the `advancePayment` hint. Delivery follows the clinic's flow: device or payment link.

**Why:** The hint marks the order as an advance payment in the settlement, so the bookkeeping can tell it apart from paid visits.

**Order status:** `Created` · **The journal shows:** Advance — unpaid

**Request:** `PUT /api/public/orders/7b1e7c3a-2f4d-4a51-9c7e-5d0a6b8e2c14` · Merchant token · [Reference](https://developers.rivr.io/reference/api-public/createOrder.md)

```bash
curl -X PUT https://api.test.rivr.io/api/public/orders/7b1e7c3a-2f4d-4a51-9c7e-5d0a6b8e2c14 \
  -H "Authorization: Bearer $MERCHANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "7b1e7c3a-2f4d-4a51-9c7e-5d0a6b8e2c14",
  "merchantId": "MERCHANT_ID",
  "reference": "prepayment-48213",
  "personalNumber": "195001182046",
  "phone": "+46701740605",
  "email": "patient@example.com",
  "currencyCode": "SEK",
  "orderLines": [
    {
      "description": "Förskott behandlingsserie",
      "quantity": 1,
      "unitPriceExclVat": 3800,
      "vatPercentage": 0,
      "discountExclVat": 0
    }
  ],
  "checkoutHints": [
    { "type": "advancePayment", "value": "true" }
  ],
  "callbackUrl": "https://journal.example.com/webhooks/rivr",
  "metadata": { "bookingId": "48213" }
}'
```

## 2. The patient pays

*Patient → Rivr*

Just like a visit: on the device or through the link.

## 3. Completed — record the credit

*Rivr → Journal system*

When `Completed` arrives the advance is paid.

**What your system does:** Record the amount as a credit on the patient's account in the journal.

**Order status:** `Completed` · **The journal shows:** Credit SEK 3,800

**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" }
  }
}
```

## 4. Draw visits from the credit

*Journal system*

As the treatments happen, the journal draws them from the credit. That happens in the journal — Rivr doesn't offset the advance against later orders, so don't create a new Rivr order for the part that is already paid.

## 5. The advance in the settlement

*Rivr → Journal system*

The advance order appears in the settlement like any other order, but with `advancePayment` set to `"true"` in its `metadata`. Read the key case-insensitively.

## Common pitfalls

- Booking the advance as revenue for a visit that hasn't taken place.

## Next guide

- [Bookkeeping and payouts](https://developers.rivr.io/guides/bookkeeping.md): Two entries per order: when it is paid, and when the money reaches the bank.
- [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.