---
title: "File a movement against what it paid for"
method: POST
path: "/api/v1/banking/matches"
tags: ["Money"]
---

# File a movement against what it paid for

`POST /api/v1/banking/matches`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/banking/matches`
- Auth: API key in cookie `better-auth.session_token`

Money coming in is placed against the invoices named: the notice its structured reference names first, then the oldest due date first, in whole cents that add back exactly. That writes the payment, what each notice now owes and its status, the arrears case it touches, any letter that case had filed and nobody sent, now withdrawn, and an audit line naming the owner. Money going out is filed against a cost, which is marked paid on the day the money left, a supplier invoice, which is marked paid and its cost with it, or a loan. One of `invoiceIds`, `expenseId`, `supplierInvoiceId` or `mortgageId` is required and exactly one kind is accepted: a movement that settles two different kinds of thing is a movement counted twice. The whole of it is one batch, so a movement is never left marked matched against a record that was not written.

## Request body

- object
  - `bankTransactionId` string, required: The movement being settled. It has to still be unmatched.
  - `invoiceIds` string[]: The invoices this credit settles, for money coming in.
  - `expenseId` string: The cost this payment settles, for money going out.
  - `supplierInvoiceId` string: The supplier invoice this payment settles, for money going out.
  - `mortgageId` string: The loan this instalment repays, for money going out.
  - `note` string: Why, in the owner’s own words, kept on the match’s provenance.

## Response `200`

The match as written.

- object
  - `ok` unknown, required
  - `data` object, required
    - `matchId` string, required: Stable record id, e.g. `lse_012`.
    - `bankTransactionId` string, required: Stable record id, e.g. `lse_012`.
    - `status` 'matched', required
    - `paymentId` string: The payment written for money placed against invoices. Absent for money going out.
    - `withdrawn` number, required: Letters a case this payment settled had filed and nobody sent, now withdrawn. Zero for money going out.
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `400`: Nothing named to match against, more than one kind named, the movement is already matched, money going out named against invoices or money coming in against a cost, or a notice that is paid in full, not open, or in another currency.
- `404`: No such movement, or no such thing to match it to, on this portfolio.
- `409`: Something else changed the movement or what it pays at the same moment. Nothing was written; send it again.

---

[API](https://skmtc.dev/dardaris/apis/dardaris-api.md) · [All operations](https://skmtc.dev/dardaris/apis/dardaris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dardaris/apis/dardaris-api/revisions/4aff33835c73?raw)