# Inbetalningar (/api/referens/invoicepayments)

> Kundinbetalningar – lista, registrera, hämta, uppdatera och återföra betalningar på kundfakturor via /3/invoicepayments.

Inbetalningsresursen speglar Fortnox `/3/invoicepayments`. En betalning registreras mot en faktura och bokförs direkt – det finns ingen obokförd betalning i Klirr. Betalningen adresseras på sitt publika nummer (`Number`).

**Scope:** `invoice` · <Plan min="ai_pro" />

## Endpoints [#endpoints]

| Metod och sökväg | Beskrivning |
|---|---|
| <Endpoint method="GET" path="/api/v1/3/invoicepayments" /> | Lista betalningar (listform) |
| <Endpoint method="POST" path="/api/v1/3/invoicepayments" /> | Registrera och bokför en betalning. Svarar `201`. |
| <Endpoint method="GET" path="/api/v1/3/invoicepayments/{Number}" /> | Hämta en betalning (fullständig form) |
| <Endpoint method="PUT" path="/api/v1/3/invoicepayments/{Number}" /> | Uppdatera de fria fälten (`ModeOfPayment`, `Source` m.fl.) |
| <Endpoint method="DELETE" path="/api/v1/3/invoicepayments/{Number}" /> | Återför betalningen. Svarar `204`. |
| <Endpoint method="PUT" path="/api/v1/3/invoicepayments/{Number}/bookkeep" /> | No-op – returnerar betalningen |

Bas-URL: `https://app.klirr.ai/api/v1`. Skrivningar kuverteras i `InvoicePayment`.

## Listparametrar [#listparametrar]

Utöver [paginering](/api/paginering) (`page`, `limit`, `offset`) och `sortorder` (`asc`/`desc`):

| Parameter | Värden | Beskrivning |
|---|---|---|
| `sortby` | `paymentdate` | Enda värdet, och standard. |
| `invoicenumber` | heltal | Fakturans `DocumentNumber`. Ett okänt eller icke-numeriskt nummer ger en tom lista, inte ett fel. |

Återförda betalningar visas aldrig i listan.

## Fält [#fält]

Fullständig form (`GET /3/invoicepayments/{Number}`, och svaret på `POST`, `PUT` och `/bookkeep`).

| Fält | Typ | Skrivskyddat | Beskrivning |
|---|---|---|---|
| `@url` | string | ja | Resursens URL. |
| `Number` | string | ja | Betalningens publika nummer. Återanvänds aldrig. |
| `InvoiceNumber` | number | efter skapande | **Obligatoriskt vid `POST`.** Fakturans `DocumentNumber` – ett **tal** här, till skillnad från fakturan där det är en sträng. |
| `Amount` | number | efter skapande | Betalningens belopp i **kronor**. Se [belopp och valuta](#belopp-och-valuta). |
| `AmountCurrency` | number | efter skapande | Beloppet i fakturans valuta. Samma som `Amount` för en kronfaktura. |
| `PaymentDate` | string | efter skapande | `ÅÅÅÅ-MM-DD`. Standard är dagens datum. Får inte ligga i framtiden. |
| `ModeOfPaymentAccount` | number | efter skapande | Kontot som debiteras, fyrsiffrigt BAS-konto. `0` eller utelämnat ger standardkontot. |
| `ModeOfPayment` | string | nej | Betalningssätt. Standard `BG`. Lagras bara som metadata. |
| `Source` | string | nej | Standard `manual`. |
| `Booked` | boolean | ja | Alltid `true`. |
| `InvoiceCustomerName` | string | ja | Fakturans kundnamn. |
| `InvoiceCustomerNumber` | string | ja | Fakturans kundnummer. |
| `InvoiceDueDate` | string | ja | Fakturans förfallodatum. |
| `InvoiceOCR` | string | ja | Fakturans OCR. |
| `InvoiceTotal` | number | ja | Fakturans totalbelopp. |
| `Currency` | string | ja | Fakturans valuta. |
| `CurrencyRate` | number | nej | Kronor per enhet vid betalningen. `1` för kronfakturor. |
| `CurrencyUnit` | number | nej | Alltid `1` i svaret. Vid `POST` delas `CurrencyRate` med värdet (t.ex. `100` för JPY). |
| `VoucherNumber`, `VoucherSeries`, `VoucherYear` | number / string / number | ja | Betalningens verifikat. |

`Booked`, `VoucherNumber`, `VoucherSeries` och `VoucherYear` ignoreras om de skickas vid `POST`. Fält som Klirr inte modellerar sparas och returneras oförändrade.

### Listform [#listform]

`GET /3/invoicepayments` returnerar: `@url`, `Number`, `InvoiceNumber`, `Amount`, `PaymentDate`, `Currency`, `CurrencyRate`, `AmountCurrency`, `InvoiceCustomerName`, `InvoiceCustomerNumber`, `InvoiceTotal`, `ModeOfPaymentAccount`, `VoucherNumber`, `VoucherSeries`, `VoucherYear`. Belopp och nummer är **strängar** i listformen – utom `InvoiceNumber`, som är ett tal i båda formerna.

## Belopp och valuta [#belopp-och-valuta]

Klirr följer Fortnox definition: `Amount` är kronor och `AmountCurrency` är beloppet i fakturans valuta.

- **Kronfaktura:** `Amount` är betalningens belopp. `AmountCurrency` behövs inte.
- **Faktura i utländsk valuta:** `AmountCurrency` är **obligatoriskt** (och får inte vara `0`). `Amount` är valfritt och anger kronorna som faktiskt kom in på kontot. Utan `Amount` och `CurrencyRate` används Riksbankens kurs för betalningsdagen, och kursdifferensen mot fordran bokförs.
- Ett belopp som inte går att tolka (t.ex. `"1 500 kr"`) ger `400` – det tolkas aldrig som "hela beloppet".

## Delbetalning [#delbetalning]

Utelämnas beloppet regleras hela det öppna beloppet. Ett lägre belopp ger en delbetalning; fakturan står då kvar som obetald och `Balance` på fakturan visar återstoden.

- Beloppet måste vara större än noll och får inte överstiga fakturans öppna belopp – Klirr har ingen modell för överbetalning (`400`).
- Fakturan måste vara bokförd och obetald (skickad eller förfallen), annars `400`. En avskriven kundförlust ger `409`.
- En förskottsfaktura kan inte delbetalas (`400`).
- Organisationer som använder kontantmetoden kan inte delbetala ännu (`400`) – registrera hela beloppet eller kreditera mellanskillnaden.
- `WriteOffs` (öres- och kursdifferenser) stöds inte och ger `400`.
- Är det öppna beloppet redan noll (fakturan är utkvittad av krediteringar) svarar API:t `409`; fakturan markeras då som betald.

## Registrera en betalning [#registrera-en-betalning]

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl -X POST https://app.klirr.ai/api/v1/3/invoicepayments \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"InvoicePayment":{"InvoiceNumber":42,"Amount":5000,"PaymentDate":"2026-10-15","ModeOfPayment":"BG"}}'
```
</Tab>
<Tab value="TypeScript">
```ts
const res = await fetch('https://app.klirr.ai/api/v1/3/invoicepayments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <access_token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    InvoicePayment: {
      InvoiceNumber: 42,
      Amount: 5000,
      PaymentDate: '2026-10-15',
      ModeOfPayment: 'BG',
    },
  }),
});
const { InvoicePayment } = await res.json(); // 201 Created
```
</Tab>
</Tabs>

Svar (`201`):

```json
{
  "InvoicePayment": {
    "@url": "https://app.klirr.ai/api/v1/3/invoicepayments/7",
    "Number": "7",
    "InvoiceNumber": 42,
    "Amount": 5000,
    "PaymentDate": "2026-10-15",
    "ModeOfPaymentAccount": 1930,
    "ModeOfPayment": "BG",
    "Booked": true,
    "InvoiceCustomerName": "Bergström Bygg AB",
    "InvoiceCustomerNumber": "1001",
    "InvoiceDueDate": "2026-11-17",
    "InvoiceOCR": "4200007",
    "InvoiceTotal": 11875,
    "Currency": "SEK",
    "CurrencyRate": 1,
    "CurrencyUnit": 1,
    "AmountCurrency": 5000,
    "VoucherNumber": 18,
    "VoucherSeries": "C",
    "VoucherYear": 1,
    "Source": "manual"
  }
}
```

## Lista betalningar [#lista-betalningar]

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl "https://app.klirr.ai/api/v1/3/invoicepayments?invoicenumber=42" \
  -H "Authorization: Bearer <access_token>"
```
</Tab>
<Tab value="TypeScript">
```ts
const res = await fetch(
  'https://app.klirr.ai/api/v1/3/invoicepayments?invoicenumber=42',
  { headers: { Authorization: 'Bearer <access_token>' } },
);
const { InvoicePayments, MetaInformation } = await res.json();
```
</Tab>
</Tabs>

```json
{
  "InvoicePayments": [
    {
      "@url": "https://app.klirr.ai/api/v1/3/invoicepayments/7",
      "Number": "7",
      "InvoiceNumber": 42,
      "Amount": "5000",
      "PaymentDate": "2026-10-15",
      "Currency": "SEK",
      "CurrencyRate": "1",
      "AmountCurrency": "5000",
      "InvoiceCustomerName": "Bergström Bygg AB",
      "InvoiceCustomerNumber": "1001",
      "InvoiceTotal": "11875",
      "ModeOfPaymentAccount": "1930",
      "VoucherNumber": "18",
      "VoucherSeries": "C",
      "VoucherYear": "1"
    }
  ],
  "MetaInformation": { "@TotalResources": 1, "@TotalPages": 1, "@CurrentPage": 1 }
}
```

## Uppdatera en betalning [#uppdatera-en-betalning]

Belopp, datum och konto är bokförda och kan inte ändras (bokföringslagen 5 kap. 5 §). `PUT` ändrar bara de fria fälten, som `ModeOfPayment` och `Source`, och lägger till dem utan att ersätta tidigare lagrade fält. Skickar du tillbaka belopp, datum eller konto **oförändrade** (t.ex. ditt eget `GET`-svar) går anropet igenom; ett ändrat värde ger `409`. Vill du rätta beloppet: återför betalningen med `DELETE` och registrera en ny.

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl -X PUT https://app.klirr.ai/api/v1/3/invoicepayments/7 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"InvoicePayment":{"ModeOfPayment":"SWISH"}}'
```
</Tab>
<Tab value="TypeScript">
```ts
await fetch('https://app.klirr.ai/api/v1/3/invoicepayments/7', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <access_token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ InvoicePayment: { ModeOfPayment: 'SWISH' } }),
});
```
</Tab>
</Tabs>

## Återföra en betalning [#återföra-en-betalning]

`DELETE` raderar inte betalningen. Klirr bokför ett rättelseverifikat (BFNAR 2013:2 p. 2.17), markerar betalningen som återförd och öppnar fakturans saldo igen. Svaret är `204`, och betalningen försvinner ur `GET /3/invoicepayments`. Ett nytt `DELETE` eller `GET` på samma nummer ger `404`. Numret återanvänds aldrig.

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl -X DELETE https://app.klirr.ai/api/v1/3/invoicepayments/7 \
  -H "Authorization: Bearer <access_token>"
```
</Tab>
<Tab value="TypeScript">
```ts
const res = await fetch('https://app.klirr.ai/api/v1/3/invoicepayments/7', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer <access_token>' },
});
// res.status === 204
```
</Tab>
</Tabs>

## bookkeep [#bookkeep]

`PUT /3/invoicepayments/{Number}/bookkeep` gör ingenting i Klirr, eftersom betalningen bokfördes redan när den registrerades. Endpointen finns för att Fortnox-integrationer som anropar den ska fungera, och svarar `200` med `{"InvoicePayment": {...}}`.

## Fel [#fel]

| Status | `Code` | När |
|---|---|---|
| 400 | 9000400 | `InvoiceNumber` saknas; otolkbart `Amount`, `AmountCurrency`, `CurrencyRate` eller `CurrencyUnit`; `AmountCurrency` saknas för en faktura i utländsk valuta; ogiltigt `ModeOfPaymentAccount`; ogiltigt eller framtida `PaymentDate`; överbetalning; fakturan är inte skickad eller förfallen; delbetalning av förskottsfaktura eller under kontantmetoden; `WriteOffs`. |
| 404 | 9000404 | `Kan inte hitta betalningen` (även för återförda), eller fakturan i `InvoiceNumber` finns inte. |
| 409 | 9000409 | Försök att ändra belopp, datum eller konto med `PUT`; fakturan hade inget öppet belopp; fakturan är avskriven som kundförlust. |

Allmänna fel (401, 403, 429) beskrivs under [Felkoder](/api/felkoder).