@stamhoofd/backend 2.131.0 → 2.132.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stamhoofd/backend",
-    "version": "2.131.0",
+    "version": "2.132.1",
     "type": "module",
     "main": "./dist/index.js",
     "exports": {
@@ -57,20 +57,20 @@
         "@simonbackx/simple-endpoints": "1.21.1",
         "@simonbackx/simple-errors": "1.5.0",
         "@simonbackx/simple-logging": "1.0.1",
-        "@stamhoofd/backend-env": "2.131.0",
-        "@stamhoofd/backend-i18n": "2.131.0",
-        "@stamhoofd/backend-middleware": "2.131.0",
-        "@stamhoofd/crons": "2.131.0",
-        "@stamhoofd/email": "2.131.0",
-        "@stamhoofd/excel-writer": "2.131.0",
-        "@stamhoofd/logging": "2.131.0",
-        "@stamhoofd/models": "2.131.0",
-        "@stamhoofd/object-differ": "2.131.0",
-        "@stamhoofd/queues": "2.131.0",
-        "@stamhoofd/sql": "2.131.0",
-        "@stamhoofd/structures": "2.131.0",
-        "@stamhoofd/types": "2.131.0",
-        "@stamhoofd/utility": "2.131.0",
+        "@stamhoofd/backend-env": "2.132.1",
+        "@stamhoofd/backend-i18n": "2.132.1",
+        "@stamhoofd/backend-middleware": "2.132.1",
+        "@stamhoofd/crons": "2.132.1",
+        "@stamhoofd/email": "2.132.1",
+        "@stamhoofd/excel-writer": "2.132.1",
+        "@stamhoofd/logging": "2.132.1",
+        "@stamhoofd/models": "2.132.1",
+        "@stamhoofd/object-differ": "2.132.1",
+        "@stamhoofd/queues": "2.132.1",
+        "@stamhoofd/sql": "2.132.1",
+        "@stamhoofd/structures": "2.132.1",
+        "@stamhoofd/types": "2.132.1",
+        "@stamhoofd/utility": "2.132.1",
         "archiver": "7.0.1",
         "axios": "1.16.0",
         "base-x": "3.0.11",
@@ -91,7 +91,7 @@
         "stripe": "16.12.0"
     },
     "devDependencies": {
-        "@stamhoofd/test-utils": "2.131.0",
+        "@stamhoofd/test-utils": "2.132.1",
         "@types/cookie": "0.6.0",
         "@types/luxon": "3.7.1",
         "@types/mailparser": "3.4.6",
@@ -107,5 +107,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "51de524c831dac65960440d9a5aabe9cad1feae8"
+    "gitHead": "99e4195c2638521cf24f1e5ebef5ae9bf5009d1d"
 }

package/src/endpoints/admin/organizations/ChargeOrganizationsEndpoint.ts

@@ -58,7 +58,7 @@ export class ChargeOrganizationsEndpoint extends Endpoint<Params, Query, Body, R
                 filter: body.filter,
                 limit: 100,
             }), {
-                fetch: GetOrganizationsEndpoint.buildData,
+                fetch: request => GetOrganizationsEndpoint.buildData(request),
             });
 
             for await (const data of dataGenerator) {

package/src/endpoints/organization/dashboard/invoices/GetInvoicesEndpoint.ts

@@ -198,7 +198,7 @@ export class GetInvoicesEndpoint extends Endpoint<Params, Query, Body, ResponseB
         }
 
         return new PaginatedResponse<InvoiceStruct[], LimitedFilteredRequest>({
-            results: await AuthenticatedStructures.invoices(invoices),
+            results: await AuthenticatedStructures.invoices(invoices, true),
             next,
         });
     }

package/src/endpoints/organization/dashboard/invoices/PatchInvoicesEndpoint.test.ts

@@ -0,0 +1,143 @@
+import type { PatchableArrayAutoEncoder } from '@simonbackx/simple-encoding';
+import { PatchableArray } from '@simonbackx/simple-encoding';
+import { Request } from '@simonbackx/simple-endpoints';
+import type { Organization, User } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemFactory, Invoice, InvoicedBalanceItem, OrganizationFactory, Payment, Token, UserFactory } from '@stamhoofd/models';
+import type { InvoiceStruct } from '@stamhoofd/structures';
+import { PaymentMethod, PaymentStatus, PermissionLevel, Permissions } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { PatchInvoicesEndpoint } from './PatchInvoicesEndpoint.js';
+
+describe('Endpoint.PatchInvoicesEndpoint', () => {
+    const endpoint = new PatchInvoicesEndpoint();
+
+    const createBalanceItem = async ({ organization, unitPrice = 10_00 }: { organization: Organization; unitPrice?: number }) => {
+        return await new BalanceItemFactory({
+            organizationId: organization.id,
+            amount: 1,
+            unitPrice,
+        }).create();
+    };
+
+    const createInvoice = async ({ organization, balanceItemIds, number = '1' }: { organization: Organization; balanceItemIds: string[]; number?: string | null }) => {
+        const invoice = new Invoice();
+        invoice.organizationId = organization.id;
+        invoice.number = number;
+        invoice.invoicedAt = number ? new Date() : null;
+        await invoice.save();
+
+        for (const balanceItemId of balanceItemIds) {
+            const item = new InvoicedBalanceItem();
+            item.organizationId = organization.id;
+            item.invoiceId = invoice.id;
+            item.balanceItemId = balanceItemId;
+            item.name = 'Test item';
+            item.unitPrice = 10_00;
+            item.balanceInvoicedAmount = 10_00;
+            await item.save();
+        }
+
+        // Make sure the invoiced cache of the balance items is up to date, like it would be for a real invoice.
+        await BalanceItem.updateInvoiced(balanceItemIds);
+
+        return invoice;
+    };
+
+    const createPayment = async ({ organization, invoice }: { organization: Organization; invoice: Invoice }) => {
+        const payment = new Payment();
+        payment.organizationId = organization.id;
+        payment.method = PaymentMethod.PointOfSale;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = 10_00;
+        payment.invoiceId = invoice.id;
+        await payment.save();
+        return payment;
+    };
+
+    const patchInvoices = async ({ body, organization, user }: { body: PatchableArrayAutoEncoder<InvoiceStruct>; organization: Organization; user: User }) => {
+        const token = await Token.createToken(user);
+        const request = Request.buildJson('PATCH', '/invoices', organization.getApiHost(), body);
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test<InvoiceStruct[]>(endpoint, request);
+    };
+
+    describe('Deleting invoices', () => {
+        test('deletes the invoice, its invoiced balance items and unlinks the payments', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({
+                organization,
+                permissions: Permissions.create({ level: PermissionLevel.Full }),
+            }).create();
+
+            const balanceItem = await createBalanceItem({ organization });
+            const invoice = await createInvoice({ organization, balanceItemIds: [balanceItem.id] });
+            const payment = await createPayment({ organization, invoice });
+
+            // Sanity check: the balance item is marked as invoiced
+            const before = await BalanceItem.getByID(balanceItem.id);
+            expect(before!.priceInvoiced).toBe(10_00);
+
+            const body = new PatchableArray() as PatchableArrayAutoEncoder<InvoiceStruct>;
+            body.addDelete(invoice.id);
+
+            const response = await patchInvoices({ body, organization, user });
+            expect(response.status).toBe(200);
+
+            // Invoice is gone
+            expect(await Invoice.getByID(invoice.id)).toBeUndefined();
+
+            // Invoiced balance items are cascade deleted
+            const remainingItems = await InvoicedBalanceItem.select().where('invoiceId', invoice.id).fetch();
+            expect(remainingItems).toHaveLength(0);
+
+            // Payment is kept but unlinked
+            const reloadedPayment = await Payment.getByID(payment.id);
+            expect(reloadedPayment).toBeDefined();
+            expect(reloadedPayment!.invoiceId).toBeNull();
+
+            // Invoiced cache of the balance item is recalculated
+            const after = await BalanceItem.getByID(balanceItem.id);
+            expect(after!.priceInvoiced).toBe(0);
+        });
+
+        test('user without full access cannot delete invoices', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({
+                organization,
+                permissions: Permissions.create({ level: PermissionLevel.Read }),
+            }).create();
+
+            const balanceItem = await createBalanceItem({ organization });
+            const invoice = await createInvoice({ organization, balanceItemIds: [balanceItem.id] });
+
+            const body = new PatchableArray() as PatchableArrayAutoEncoder<InvoiceStruct>;
+            body.addDelete(invoice.id);
+
+            await expect(patchInvoices({ body, organization, user })).rejects.toThrow(STExpect.errorWithCode('permission_denied'));
+
+            // Invoice is untouched
+            expect(await Invoice.getByID(invoice.id)).toBeDefined();
+        });
+
+        test('cannot delete an invoice of another organization', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const otherOrganization = await new OrganizationFactory({}).create();
+            const user = await new UserFactory({
+                organization,
+                permissions: Permissions.create({ level: PermissionLevel.Full }),
+            }).create();
+
+            const balanceItem = await createBalanceItem({ organization: otherOrganization });
+            const invoice = await createInvoice({ organization: otherOrganization, balanceItemIds: [balanceItem.id] });
+
+            const body = new PatchableArray() as PatchableArrayAutoEncoder<InvoiceStruct>;
+            body.addDelete(invoice.id);
+
+            await expect(patchInvoices({ body, organization, user })).rejects.toThrow(STExpect.errorWithCode('not_found'));
+
+            // Invoice is untouched
+            expect(await Invoice.getByID(invoice.id)).toBeDefined();
+        });
+    });
+});

package/src/endpoints/organization/dashboard/invoices/PatchInvoicesEndpoint.ts

@@ -6,7 +6,7 @@ import { Invoice as InvoiceStruct } from '@stamhoofd/structures';
 
 import { AuthenticatedStructures } from '../../../../helpers/AuthenticatedStructures.js';
 import { Context } from '../../../../helpers/Context.js';
-import type { Invoice } from '@stamhoofd/models';
+import { Invoice } from '@stamhoofd/models';
 import { SimpleError } from '@simonbackx/simple-errors';
 import { ViesHelper } from '../../../../helpers/ViesHelper.js';
 import { InvoiceService } from '../../../../services/InvoiceService.js';
@@ -57,8 +57,17 @@ export class PatchInvoicesEndpoint extends Endpoint<Params, Query, Body, Respons
             invoices.push(model);
         }
 
+        for (const id of request.body.getDeletes()) {
+            const model = await Invoice.getByID(id);
+            if (!model || model.organizationId !== organization.id) {
+                throw Context.auth.notFoundOrNoAccess($t('%ZcE'));
+            }
+
+            await InvoiceService.delete(model);
+        }
+
         return new Response(
-            await AuthenticatedStructures.invoices(invoices),
+            await AuthenticatedStructures.invoices(invoices, true),
         );
     }
 }

package/src/endpoints/organization/dashboard/receivable-balances/ChargeReceivableBalancesEndpoint.ts

@@ -6,7 +6,7 @@ import { CountFilteredRequest, CountResponse, PaymentCustomer, PaymentMethod, Pe
 import { Context } from '../../../../helpers/Context.js';
 import { GetReceivableBalancesEndpoint } from './GetReceivableBalancesEndpoint.js';
 import type { BalanceItem } from '@stamhoofd/models';
-import { Organization, User } from '@stamhoofd/models';
+import { Organization, Platform, User } from '@stamhoofd/models';
 import { CachedBalance } from '@stamhoofd/models';
 import { PaymentService } from '../../../../services/PaymentService.js';
 import { SimpleError } from '@simonbackx/simple-errors';
@@ -15,12 +15,12 @@ import { BalanceItemService } from '../../../../services/BalanceItemService.js';
 import { QueueHandler } from '@stamhoofd/queues';
 
 type Params = Record<string, never>;
-type Query = CountFilteredRequest;
-type Body = undefined;
+type Query = undefined;
+type Body = CountFilteredRequest;
 type ResponseBody = undefined;
 
 export class ChargeReceivableBalancesEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
-    queryDecoder = CountFilteredRequest as Decoder<CountFilteredRequest>;
+    bodyDecoder = CountFilteredRequest as Decoder<CountFilteredRequest>;
 
     protected doesMatch(request: Request): [true, Params] | [false] {
         if (request.method !== 'POST') {
@@ -38,6 +38,7 @@ export class ChargeReceivableBalancesEndpoint extends Endpoint<Params, Query, Bo
     async handle(request: DecodedRequest<Params, Query, Body>) {
         const sellingOrganization = await Context.setOrganizationScope();
         const { user } = await Context.authenticate();
+        const platform = await Platform.getShared();
 
         if (!await Context.auth.canManageFinances(sellingOrganization.id)) {
             throw Context.auth.error();
@@ -53,7 +54,7 @@ export class ChargeReceivableBalancesEndpoint extends Endpoint<Params, Query, Bo
         }
 
         await QueueHandler.schedule(queueId, async () => {
-            const query = await GetReceivableBalancesEndpoint.buildQuery(request.query);
+            const query = await GetReceivableBalancesEndpoint.buildQuery(request.body);
 
             for await (const cachedBalance of query.all()) {
                 if (cachedBalance.organizationId !== sellingOrganization.id) {
@@ -80,6 +81,12 @@ export class ChargeReceivableBalancesEndpoint extends Endpoint<Params, Query, Bo
                     continue;
                 }
 
+                if (total <= 4_00_00 && sellingOrganization.id === platform.membershipOrganizationId && STAMHOOFD.userMode === 'organization') {
+                    // Skip too small payments for Stamhoofd
+                    console.error('Skipped charging too small payment for', cachedBalance.objectId, cachedBalance.objectType);
+                    continue;
+                }
+
                 let payingOrganization: Organization | null = null;
                 let customerUser: User | null = null;
                 if (cachedBalance.objectType === ReceivableBalanceType.organization) {

package/src/endpoints/organization/dashboard/receivable-balances/GetReceivableBalanceEndpoint.ts

@@ -83,7 +83,7 @@ export class GetReceivableBalanceEndpoint extends Endpoint<Params, Query, Body,
         const balanceItemModels = await CachedBalance.balanceForObjects(organization.id, [request.params.id], request.params.type);
         const balanceItems = await BalanceItem.getStructureWithPayments(balanceItemModels);
         const payments = await AuthenticatedStructures.paymentsGeneral(paymentModels, false);
-        const invoices = await AuthenticatedStructures.invoices(invoiceModels);
+        const invoices = await AuthenticatedStructures.invoices(invoiceModels, true);
 
         const balances = await CachedBalance.getForObjects([request.params.id], organization.id, request.params.type);
 

package/src/helpers/AuthenticatedStructures.ts

@@ -70,7 +70,7 @@ export class AuthenticatedStructures {
         });
     }
 
-    static async invoices(invoices: Invoice[]): Promise<InvoiceStruct[]> {
+    static async invoices(invoices: Invoice[], incldueSettlements = false): Promise<InvoiceStruct[]> {
         if (invoices.length === 0) {
             return [];
         }
@@ -78,7 +78,7 @@ export class AuthenticatedStructures {
         const { invoicedBalanceItems } = await Invoice.loadBalanceItems(invoices);
 
         const paymentModels = await Payment.select().where('invoiceId', invoices.map(i => i.id)).fetch();
-        const payments = await this.paymentsGeneral(paymentModels, false);
+        const payments = await this.paymentsGeneral(paymentModels, incldueSettlements);
 
         return invoices.map((invoice) => {
             const items = invoicedBalanceItems.filter(i => i.invoiceId === invoice.id);

package/src/helpers/CheckSettlements.test.ts

@@ -0,0 +1,190 @@
+import { MolliePayment, OrganizationFactory, Payment } from '@stamhoofd/models';
+import { PaymentMethod, PaymentProvider, PaymentStatus, PaymentType } from '@stamhoofd/structures';
+import type { MollieMockPayment, MollieMockRefund } from '../../tests/helpers/MollieMocker.js';
+import { MollieMocker } from '../../tests/helpers/MollieMocker.js';
+import { checkMollieSettlementsFor } from './CheckSettlements.js';
+
+describe('Helper.CheckSettlements', () => {
+    let mollieMocker: MollieMocker;
+
+    beforeAll(() => {
+        mollieMocker = new MollieMocker();
+        mollieMocker.start();
+    });
+
+    afterAll(() => {
+        mollieMocker.stop();
+    });
+
+    beforeEach(() => {
+        mollieMocker.reset();
+    });
+
+    /**
+     * Create an organization with a Mollie token, a succeeded Mollie payment and a Mollie refund
+     * payment reversing it. Both are linked to their Mollie ids (tr_... / re_...) like the real crons do.
+     */
+    const init = async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const token = await mollieMocker.setupToken(organization);
+
+        // Source payment
+        const payment = new Payment();
+        payment.organizationId = organization.id;
+        payment.method = PaymentMethod.Bancontact;
+        payment.provider = PaymentProvider.Mollie;
+        payment.status = PaymentStatus.Succeeded;
+        payment.type = PaymentType.Payment;
+        payment.price = 50_0000;
+        payment.paidAt = new Date();
+        await payment.save();
+
+        const mockPayment: MollieMockPayment = {
+            id: mollieMocker.createId('tr'),
+            status: 'paid',
+            amount: { currency: 'EUR', value: '50.00' },
+            internalPaymentId: payment.id,
+            redirectUrl: null,
+            sequenceType: 'oneoff',
+            customerId: null,
+            mandateId: null,
+            isCancelable: false,
+            details: null,
+        };
+        mollieMocker.payments.push(mockPayment);
+
+        const paymentLink = new MolliePayment();
+        paymentLink.paymentId = payment.id;
+        paymentLink.mollieId = mockPayment.id;
+        await paymentLink.save();
+
+        // Refund payment reversing the source payment
+        const refundPayment = new Payment();
+        refundPayment.organizationId = organization.id;
+        refundPayment.method = PaymentMethod.Bancontact;
+        refundPayment.provider = PaymentProvider.Mollie;
+        refundPayment.status = PaymentStatus.Succeeded;
+        refundPayment.type = PaymentType.Refund;
+        refundPayment.price = -20_0000;
+        refundPayment.reversingPaymentId = payment.id;
+        refundPayment.paidAt = new Date();
+        await refundPayment.save();
+
+        const mockRefund = mollieMocker.createRefund(mockPayment, { value: '20.00', status: 'refunded' });
+
+        const refundLink = new MolliePayment();
+        refundLink.paymentId = refundPayment.id;
+        refundLink.mollieId = mockRefund.id;
+        await refundLink.save();
+
+        return { organization, token, payment, refundPayment, mockPayment, mockRefund };
+    };
+
+    const runCron = async (token: { accessToken: string }) => {
+        await checkMollieSettlementsFor(token.accessToken, true);
+    };
+
+    /**
+     * Add a Mollie chargeback payment reversing the given source payment, linked to its Mollie
+     * chargeback id (chb_...) like the mollie-chargebacks cron does.
+     */
+    const addChargeback = async (organizationId: string, sourcePayment: Payment, mockPayment: MollieMockPayment) => {
+        const chargebackPayment = new Payment();
+        chargebackPayment.organizationId = organizationId;
+        chargebackPayment.method = PaymentMethod.Bancontact;
+        chargebackPayment.provider = PaymentProvider.Mollie;
+        chargebackPayment.status = PaymentStatus.Succeeded;
+        chargebackPayment.type = PaymentType.Chargeback;
+        chargebackPayment.price = -sourcePayment.price;
+        chargebackPayment.reversingPaymentId = sourcePayment.id;
+        chargebackPayment.paidAt = new Date();
+        await chargebackPayment.save();
+
+        const mockChargeback = mollieMocker.createChargeback(mockPayment);
+
+        const chargebackLink = new MolliePayment();
+        chargebackLink.paymentId = chargebackPayment.id;
+        chargebackLink.mollieId = mockChargeback.id;
+        await chargebackLink.save();
+
+        return { chargebackPayment, mockChargeback };
+    };
+
+    test('The settlement of a refund settled at Mollie is stored on the refund payment', async () => {
+        const { token, payment, refundPayment, mockPayment, mockRefund } = await init();
+
+        const settlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            refunds: [mockRefund],
+            value: '100.00',
+        });
+
+        await runCron(token);
+
+        // The source payment gets the settlement metadata (existing behaviour)
+        const updatedPayment = await Payment.getByID(payment.id);
+        expect(updatedPayment!.settlement).toMatchObject({
+            id: settlement.id,
+            reference: settlement.reference,
+        });
+
+        // The refund payment gets the same settlement metadata (new behaviour)
+        const updatedRefund = await Payment.getByID(refundPayment.id);
+        expect(updatedRefund!.settlement).toMatchObject({
+            id: settlement.id,
+            reference: settlement.reference,
+            amount: 100_0000,
+        });
+    });
+
+    test('A refund that is not part of any settlement keeps no settlement', async () => {
+        const { token, refundPayment, mockPayment } = await init();
+
+        // A settlement that only contains the source payment, not the refund
+        mollieMocker.createSettlement({ payments: [mockPayment], value: '50.00' });
+
+        await runCron(token);
+
+        const updatedRefund = await Payment.getByID(refundPayment.id);
+        expect(updatedRefund!.settlement).toBeNull();
+    });
+
+    test('The settlement of a chargeback settled at Mollie is stored on the chargeback payment', async () => {
+        const { organization, token, payment, mockPayment } = await init();
+        const { chargebackPayment, mockChargeback } = await addChargeback(organization.id, payment, mockPayment);
+
+        const settlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            chargebacks: [mockChargeback],
+            value: '100.00',
+        });
+
+        await runCron(token);
+
+        const updatedChargeback = await Payment.getByID(chargebackPayment.id);
+        expect(updatedChargeback!.settlement).toMatchObject({
+            id: settlement.id,
+            reference: settlement.reference,
+            amount: 100_0000,
+        });
+    });
+
+    test('An unlinked refund entry in a settlement is skipped without affecting the known refund', async () => {
+        const { token, refundPayment, mockPayment, mockRefund } = await init();
+
+        // A refund that belongs to a different system: it exists at Mollie but has no MolliePayment link
+        const unlinkedRefund: MollieMockRefund = mollieMocker.createRefund(mockPayment, { value: '5.00', status: 'refunded' });
+
+        const settlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            refunds: [unlinkedRefund, mockRefund],
+            value: '100.00',
+        });
+
+        await runCron(token);
+
+        // The known refund still gets its settlement, the unlinked one is silently ignored
+        const updatedRefund = await Payment.getByID(refundPayment.id);
+        expect(updatedRefund!.settlement).toMatchObject({ id: settlement.id });
+    });
+});

package/src/helpers/CheckSettlements.ts

@@ -16,7 +16,11 @@ type MollieSettlement = {
     };
 };
 
-type MolliePaymentJSON = {
+/**
+ * Both payments (tr_...) and refunds (re_...) settled in a settlement are matched to a local
+ * payment through the mollieId of their MolliePayment link, so we only need their id here.
+ */
+type MollieSettlementEntryJSON = {
     id: string;
 };
 
@@ -146,64 +150,88 @@ export async function checkMollieSettlementsFor(token: string, checkAll = false)
     }
 }
 
-async function updateSettlement(token: string, settlement: MollieSettlement, fromPaymentId?: string) {
+async function updateSettlement(token: string, settlement: MollieSettlement) {
+    // Regular payments settled in this settlement
+    await updateSettlementResource(token, settlement, 'payments');
+
+    // Refunds settled in this settlement. These are negative entries linked to a refund payment
+    // (created by the mollie-refunds cron), so we can set their settlement metadata too.
+    await updateSettlementResource(token, settlement, 'refunds');
+
+    // Chargebacks settled in this settlement. Like refunds, these are negative entries linked to a
+    // chargeback payment (created by the mollie-chargebacks cron).
+    await updateSettlementResource(token, settlement, 'chargebacks');
+}
+
+/**
+ * Loop over all entries (payments, refunds or chargebacks) that are part of a settlement and set the
+ * settlement metadata on the matching local payment. Every resource exposes its entries under
+ * `_embedded[resource]` and uses the same pagination, so they share this logic.
+ */
+async function updateSettlementResource(token: string, settlement: MollieSettlement, resource: 'payments' | 'refunds' | 'chargebacks', fromId?: string) {
     const limit = 250;
 
-    // Loop all payments of this settlement
-    const request = await axios.get('https://api.mollie.com/v2/settlements/' + settlement.id + '/payments?limit=' + limit + (fromPaymentId ? ('&from=' + encodeURIComponent(fromPaymentId)) : ''), {
+    const request = await axios.get('https://api.mollie.com/v2/settlements/' + settlement.id + '/' + resource + '?limit=' + limit + (fromId ? ('&from=' + encodeURIComponent(fromId)) : ''), {
         headers: {
             Authorization: 'Bearer ' + token,
         },
     });
 
     if (request.status === 200) {
-        const molliePayments = request.data._embedded.payments as MolliePaymentJSON[];
-
-        for (const mollie of molliePayments) {
-            // Search payment
-            const mps = await MolliePayment.where({ mollieId: mollie.id });
-            if (mps.length == 1) {
-                const mp = mps[0];
-                const payment = await Payment.getByID(mp.paymentId);
-                if (payment) {
-                    payment.settlement = Settlement.create({
-                        id: settlement.id,
-                        reference: settlement.reference,
-                        settledAt: new Date(settlement.settledAt),
-                        amount: Math.round(parseFloat(settlement.amount.value) * 100) * 100,
-                    });
-                    const saved = await payment.save();
-
-                    if (saved) {
-                        // Mark order as 'updated', or the frontend won't pull in the updates
-                        const order = await Order.getForPayment(null, payment.id);
-                        if (order) {
-                            order.updatedAt = new Date();
-                            order.forceSaveProperty('updatedAt');
-                            await order.save();
-                        }
-
-                        // TODO: Mark registrations as 'saved'
-                    }
+        const entries = request.data._embedded[resource] as MollieSettlementEntryJSON[];
 
-                    if (STAMHOOFD.environment === 'development') {
-                        console.log('Updated settlement of payment ' + payment.id);
-                        console.log(payment.settlement);
-                    }
-                } else {
-                    console.log('Missing payment ' + mp.paymentId);
-                }
-            } else {
-                // Probably a payment in a different system/platform
-                // console.log("No mollie payment found for id "+mollie.id)
-            }
+        for (const entry of entries) {
+            await applySettlementToPayment(settlement, entry.id);
         }
 
         // Check next page
-        if (request.data._links.next) {
-            await updateSettlement(token, settlement, molliePayments[molliePayments.length - 1].id);
+        if (request.data._links.next && entries.length > 0) {
+            await updateSettlementResource(token, settlement, resource, entries[entries.length - 1].id);
         }
     } else {
         console.error(request.data);
     }
 }
+
+/**
+ * Find the local payment linked to a Mollie payment or refund id and store the settlement metadata.
+ */
+async function applySettlementToPayment(settlement: MollieSettlement, mollieId: string) {
+    // Search payment
+    const mps = await MolliePayment.where({ mollieId });
+    if (mps.length === 1) {
+        const mp = mps[0];
+        const payment = await Payment.getByID(mp.paymentId);
+        if (payment) {
+            payment.settlement = Settlement.create({
+                id: settlement.id,
+                reference: settlement.reference,
+                settledAt: new Date(settlement.settledAt),
+                amount: Math.round(parseFloat(settlement.amount.value) * 100) * 100,
+            });
+            const saved = await payment.save();
+
+            if (saved) {
+                // Mark order as 'updated', or the frontend won't pull in the updates
+                const order = await Order.getForPayment(null, payment.id);
+                if (order) {
+                    order.updatedAt = new Date();
+                    order.forceSaveProperty('updatedAt');
+                    await order.save();
+                }
+
+                // TODO: Mark registrations as 'saved'
+            }
+
+            if (STAMHOOFD.environment === 'development') {
+                console.log('Updated settlement of payment ' + payment.id);
+                console.log(payment.settlement);
+            }
+        } else {
+            console.log('Missing payment ' + mp.paymentId);
+        }
+    } else {
+        // Probably a payment in a different system/platform
+        // console.log("No mollie payment found for id "+mollieId)
+    }
+}

package/src/helpers/StripeInvoicer.ts

@@ -57,10 +57,6 @@ export class ApplicationFeeDetails {
         this.combine(ApplicationFeeDetails.fromStripe(fee));
     }
 
-    remove(fee: Stripe.BalanceTransaction) {
-        this.combine(ApplicationFeeDetails.fromStripe(fee));
-    }
-
     combine(other: ApplicationFeeDetails) {
         this.serviceFee += other.serviceFee;
         this.transferFee += other.transferFee;

package/src/helpers/StripePayoutChecker.ts

@@ -69,13 +69,9 @@ export class StripePayoutChecker {
             payout: payout.id,
             // Via the Application Fee object, we can get the original payment metadata
             expand: ['data.source', 'data.source.application_fee', 'data.source.application_fee.originating_transaction'],
-            // TODO: ALSO DO CARDS! (type: 'charge')
-            // type: 'payment'
         };
 
         for await (const balanceItem of this.stripe.balanceTransactions.list(params)) {
-            // TODO
-
             if (balanceItem.type === 'charge' || balanceItem.type === 'payment') {
                 await this.handleBalanceItem(payout, balanceItem);
             }

package/src/seeds/1783520259-make-old-group-filters-readable.ts

@@ -0,0 +1,454 @@
+import { Migration } from '@simonbackx/simple-database';
+import { Group, Organization, RegistrationPeriod } from '@stamhoofd/models';
+import type { RecordCategory, RegistrationPeriodBase, StamhoofdCompareValue, StamhoofdFilter, StamhoofdMagicRelationFilter } from '@stamhoofd/structures';
+import { GroupType } from '@stamhoofd/structures';
+import { SeedTools } from '../helpers/SeedTools.js';
+
+export async function startMigration(dryRun = false) {
+    await SeedTools.loop({
+        batchSize: 100,
+        query: Organization.select(),
+        action: async (organization: Organization) => {
+            await fixUnreadableGroupFilters(organization, dryRun);
+        },
+    });
+
+    if (dryRun) {
+        throw new Error('Migration did not finish because of dryRun');
+    }
+}
+
+export default new Migration(async () => {
+    if (STAMHOOFD.environment === 'test') {
+        console.log('skipped in tests');
+        return;
+    }
+
+    if (STAMHOOFD.platformName.toLowerCase() !== 'stamhoofd') {
+        console.log('skipped for platform (only runs for Stamhoofd): ' + STAMHOOFD.platformName);
+        return;
+    }
+
+    const dryRun = false;
+    await startMigration(dryRun);
+});
+
+function getAllRecordCategories(organization: Organization): RecordCategory[] {
+    function getAllRecordCategoiesRecursive(category: RecordCategory) {
+        const results: RecordCategory[] = [category];
+
+        for (const child of category.childCategories) {
+            results.push(...getAllRecordCategoiesRecursive(child));
+        }
+        return results;
+    }
+
+    return organization.meta.recordsConfiguration.recordCategories.flatMap(c => getAllRecordCategoiesRecursive(c));
+}
+
+async function fixUnreadableGroupFilters(organization: Organization, dryRun: boolean) {
+    const filtersWithGroupFilters: StamhoofdFilter[] = getAllRecordCategories(organization).flatMap((c) => {
+        const filter = c.filter;
+        if (filter === null) {
+            return [];
+        }
+
+        return [filter.enabledWhen, filter.requiredWhen].filter((f) => {
+            return hasRegistrationsFilter(f);
+        });
+    });
+
+    if (filtersWithGroupFilters.length === 0) {
+        return;
+    }
+
+    console.log('organization:', organization.name);
+
+    for (const filter of filtersWithGroupFilters) {
+        const groupIds = getGroupIdsFromFilter(filter);
+        if (groupIds.length === 0) {
+            continue;
+        }
+
+        const groups = await Group.getByIDs(...new Set(groupIds));
+        const groupMap = new Map(groups.map(g => [g.id, g]));
+
+        console.error('filter before: ', JSON.stringify(filter));
+
+        await makeGroupFiltersReadable(filter, groupMap);
+
+        console.error('filter after: ', JSON.stringify(filter));
+    }
+
+    if (!dryRun) {
+        await organization.save();
+    }
+}
+
+class StamhoofdFilterHelper {
+    static isRecordOrArray(value: StamhoofdFilter): value is { [key: string]: StamhoofdFilter } | StamhoofdFilter[] {
+        if (typeof value !== 'object' || value === null || value instanceof Date) {
+            return false;
+        }
+
+        return true;
+    }
+
+    static isRecord(value: StamhoofdFilter): value is { [key: string]: StamhoofdFilter } {
+        if (!this.isRecordOrArray(value) || Array.isArray(value)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    static isRecordWithSingleEntry(value: StamhoofdFilter): value is { [key: string]: StamhoofdFilter } {
+        if (!this.isRecord(value)) {
+            return false;
+        }
+
+        return Object.entries(value).length === 1;
+    }
+
+    static isEmptyRecord(value: StamhoofdFilter): value is { [key: string]: never } {
+        if (!this.isRecord(value)) {
+            return false;
+        }
+
+        return Object.entries(value).length === 0;
+    }
+
+    static hasRegistrationsFilter(filter: StamhoofdFilter): boolean {
+        if (filter === null) {
+            return false;
+        }
+
+        if (typeof filter !== 'object') {
+            return false;
+        }
+
+        if (filter instanceof Date) {
+            return false;
+        }
+
+        if (Array.isArray(filter)) {
+            return filter.some(f => this.hasRegistrationsFilter(f));
+        }
+
+        if (this.isRegistrationFilter(filter)) {
+            return true;
+        }
+
+        // iterate properties
+        for (const [, value] of Object.entries(filter as object) as [string, StamhoofdFilter | StamhoofdCompareValue][]) {
+            if (this.hasRegistrationsFilter(value)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    static isRegistrationFilter(filter: StamhoofdFilter): filter is { registrations: StamhoofdFilter } & StamhoofdFilter {
+        if (!StamhoofdFilterHelper.isRecord(filter)) {
+            return false;
+        }
+
+        return Object.entries(filter).some(entry => entry[0] === 'registrations');
+    }
+}
+
+function hasRegistrationsFilter(filter: StamhoofdFilter): boolean {
+    if (filter === null) {
+        return false;
+    }
+
+    if (typeof filter !== 'object') {
+        return false;
+    }
+
+    if (filter instanceof Date) {
+        return false;
+    }
+
+    if (Array.isArray(filter)) {
+        return filter.some(f => hasRegistrationsFilter(f));
+    }
+
+    if (isRegistrationFilter(filter)) {
+        return true;
+    }
+
+    // iterate properties
+    for (const [, value] of Object.entries(filter as object) as [string, StamhoofdFilter | StamhoofdCompareValue][]) {
+        if (hasRegistrationsFilter(value)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function isRegistrationFilter(filter: StamhoofdFilter): filter is { registrations: StamhoofdFilter } & StamhoofdFilter {
+    if (!StamhoofdFilterHelper.isRecord(filter)) {
+        return false;
+    }
+
+    return Object.entries(filter).some(entry => entry[0] === 'registrations');
+}
+
+function getGroupIdsFromRegistrationsFilter(registrationFilter: { registrations: StamhoofdFilter }): string[] {
+    if (!StamhoofdFilterHelper.isRecordWithSingleEntry(registrationFilter)) {
+        throw new Error('Invalid registration filter: ' + JSON.stringify(registrationFilter));
+    }
+
+    const entries = Object.entries(registrationFilter);
+
+    let currentEntry = entries[0];
+
+    while (true) {
+        const currentKey = currentEntry[0];
+
+        switch (currentKey) {
+            case 'registrations':
+            case '$elemMatch':
+            case '$or':
+            case '$and':
+            case '$not':
+            {
+                break;
+            }
+            default: throw new Error(`Invalid registration filter (currentKey: ${currentKey}): ` + JSON.stringify(registrationFilter));
+        }
+
+        const currentValue = currentEntry[1];
+
+        if (StamhoofdFilterHelper.isRecordWithSingleEntry(currentValue)) {
+            currentEntry = Object.entries(currentValue)[0];
+        } else if (Array.isArray(currentValue)) {
+            return currentValue.map(item => getGroupIdsFromGroupFilters(item));
+        } else {
+            throw new Error('Invalid registration filter: ' + JSON.stringify(registrationFilter));
+        }
+    }
+}
+
+function getGroupIdsFromGroupFilters(filter: StamhoofdFilter) {
+    const groupId = (filter as { group?: { id?: { $eq?: string } } })?.group?.id?.$eq;
+    if (typeof groupId !== 'string') {
+        throw new Error('Invalid group filter: ' + JSON.stringify(filter));
+    }
+    return groupId;
+}
+
+function getGroupIdsFromFilter(filter: StamhoofdFilter): string[] {
+    if (!StamhoofdFilterHelper.isRecordOrArray(filter)) {
+        throw new Error('Invalid filter: ' + JSON.stringify(filter));
+    }
+
+    if (Array.isArray(filter)) {
+        return filter.flatMap(item => getGroupIdsFromFilter(item));
+    }
+
+    const all: string[] = [];
+
+    for (const [key, value] of Object.entries(filter)) {
+        if (key === 'registrations') {
+            all.push(...getGroupIdsFromRegistrationsFilter({ [key]: value }));
+            continue;
+        }
+        if (!StamhoofdFilterHelper.isRecordOrArray(value)) {
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                continue;
+            }
+
+            const isSomeRecordOrArray = value.some(item => StamhoofdFilterHelper.isRecordOrArray(item));
+
+            if (!isSomeRecordOrArray) {
+                continue;
+            }
+
+            for (const item of value) {
+                // ignore null
+                if (item === null) {
+                    continue;
+                }
+
+                const isRecordOrArray = StamhoofdFilterHelper.isRecordOrArray(item);
+                if (!isRecordOrArray) {
+                    throw new Error('Invalid filter: ' + JSON.stringify(filter));
+                }
+
+                all.push(...getGroupIdsFromFilter(item));
+            }
+            continue;
+        }
+
+        all.push(...getGroupIdsFromFilter(value));
+    }
+
+    return all;
+}
+
+async function makeGroupFiltersReadable(filter: StamhoofdFilter, groupMap: Map<string, Group>): Promise<void> {
+    async function getRelationName(group: Group | null | undefined) {
+        if (!group) {
+            return 'Verwijderde groep';
+        }
+
+        const groupName = group.settings.name.toString();
+
+        let period: RegistrationPeriodBase | undefined = undefined;
+
+        // fetch model if no cached period
+        const periodModel = (await RegistrationPeriod.getByID(group.periodId));
+        if (periodModel) {
+            period = periodModel.getBaseStructure();
+        }
+
+        if (period) {
+            return `${groupName} (${period.nameShort})`;
+        }
+
+        return groupName;
+    }
+
+    async function getRelationFilter(filter: StamhoofdFilter, groupMap: Map<string, Group>): Promise<StamhoofdMagicRelationFilter> {
+        const groupId = (filter as { group?: { id?: { $eq?: string } } })?.group?.id?.$eq;
+        if (typeof groupId !== 'string') {
+            throw new Error('Invalid group filter: ' + JSON.stringify(filter));
+        }
+
+        const group = groupMap.get(groupId);
+        if (!group) {
+            // double check if group exists, if not: set custom name
+            const existingGroup = await Group.getByID(groupId);
+            if (existingGroup) {
+                // should never happen
+                throw new Error(`Group with id ${groupId} exists but is not included in the groupMap`);
+            }
+        }
+
+        const relationFilter: StamhoofdMagicRelationFilter = {
+            $: '$rel',
+            value: groupId,
+            type: GroupType.Membership,
+            name: await getRelationName(group),
+        };
+
+        return relationFilter;
+    }
+
+    async function makeRegistrationFilterReadable(registrationFilter: { registrations: StamhoofdFilter }): Promise<void> {
+        if (!StamhoofdFilterHelper.isRecordWithSingleEntry(registrationFilter)) {
+            throw new Error('Invalid registration filter: ' + JSON.stringify(registrationFilter));
+        }
+
+        const entries = Object.entries(registrationFilter);
+
+        let parentFilter: StamhoofdFilter | null = null;
+        let currentEntry = entries[0];
+        const relationFilterArray: StamhoofdMagicRelationFilter[] = [];
+        let orParentFilter: StamhoofdFilter | null = null;
+
+        while (true) {
+            const currentKey = currentEntry[0];
+
+            switch (currentKey) {
+                case '$not':
+                case '$and': {
+                    throw new Error(`${currentKey} not supported`);
+                }
+                case 'registrations':
+                case '$elemMatch':
+                {
+                    break;
+                }
+                case '$or': {
+                    if (!parentFilter) {
+                        throw new Error('Not expected parentFilter to be null: ' + JSON.stringify(registrationFilter));
+                    }
+                    orParentFilter = parentFilter;
+                    break;
+                }
+                default: throw new Error(`Invalid registration filter (currentKey: ${currentKey}): ` + JSON.stringify(registrationFilter));
+            }
+
+            const currentValue = currentEntry[1];
+
+            if (StamhoofdFilterHelper.isRecordWithSingleEntry(currentValue)) {
+                parentFilter = currentEntry[1];
+                currentEntry = Object.entries(currentValue)[0];
+            } else if (Array.isArray(currentValue)) {
+                if (orParentFilter === null) {
+                    throw new Error('Not expected orParentFilter to be null');
+                }
+                for (const item of currentValue) {
+                    const relationFilter = await getRelationFilter(item, groupMap);
+                    relationFilterArray.push(relationFilter);
+                }
+                delete orParentFilter[currentKey];
+                (orParentFilter as any)['groupId'] = {
+                    $in: relationFilterArray,
+                };
+                return;
+            } else {
+                throw new Error('Invalid registration filter: ' + JSON.stringify(registrationFilter));
+            }
+        }
+    }
+
+    if (!StamhoofdFilterHelper.isRecordOrArray(filter)) {
+        throw new Error('Invalid filter: ' + JSON.stringify(filter));
+    }
+
+    if (Array.isArray(filter)) {
+        for (const item of filter) {
+            await makeGroupFiltersReadable(item, groupMap);
+        }
+        return;
+    }
+
+    for (const [key, value] of Object.entries(filter)) {
+        if (key === 'registrations') {
+            await makeRegistrationFilterReadable({ [key]: value });
+            continue;
+        }
+        if (!StamhoofdFilterHelper.isRecordOrArray(value)) {
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                continue;
+            }
+
+            const isSomeRecordOrArray = value.some(item => StamhoofdFilterHelper.isRecordOrArray(item));
+
+            if (!isSomeRecordOrArray) {
+                continue;
+            }
+
+            for (const item of value) {
+                // ignore null
+                if (item === null) {
+                    continue;
+                }
+
+                const isRecordOrArray = StamhoofdFilterHelper.isRecordOrArray(item);
+                if (!isRecordOrArray) {
+                    throw new Error('Invalid filter: ' + JSON.stringify(filter));
+                }
+
+                await makeGroupFiltersReadable(item, groupMap);
+            }
+            continue;
+        }
+
+        await makeGroupFiltersReadable(value, groupMap);
+    }
+}

package/src/services/InvoiceService.ts

@@ -302,6 +302,27 @@ export class InvoiceService {
         return model;
     }
 
+    /**
+     * Permanently delete an invoice.
+     *
+     * Deleting the invoice cascades on the database level:
+     * - the linked InvoicedBalanceItems are deleted (ON DELETE CASCADE)
+     * - payments linked to this invoice have their invoiceId reset (ON DELETE SET NULL), so they can be invoiced again
+     * - other invoices referencing this one via negativeInvoiceId have it reset (ON DELETE SET NULL)
+     *
+     * After deletion the invoiced cache of the affected balance items is recalculated.
+     */
+    static async delete(invoice: Invoice) {
+        // Collect the affected balance items before deleting, because the invoiced balance items are cascade deleted.
+        const { invoicedBalanceItems } = await Invoice.loadBalanceItems([invoice]);
+        const balanceItemIds = Formatter.uniqueArray(invoicedBalanceItems.map(i => i.balanceItemId));
+
+        await invoice.delete();
+
+        // Recalculate the invoiced amount cache of the balance items that were invoiced by this invoice.
+        await BalanceItemService.updateInvoiced(balanceItemIds);
+    }
+
     private static shouldForwardInvoice(invoice: Invoice, organization: Organization) {
         if (invoice.didSendPeppol) {
             return {

package/src/services/uitpas/searchUitpasEvents.ts

@@ -72,17 +72,19 @@ export async function searchUitpasEvents(clientId: string, uitpasOrganizerId: st
             human: $t(`%1BZ`),
         });
     }
-    const baseUrl = 'https://search-test.uitdatabank.be/events';
+    const baseUrl = STAMHOOFD.UITPAS_API_URL?.includes('test') ? 'https://search-test.uitdatabank.be/events' : 'https://search.uitdatabank.be/events';
     const params = new URLSearchParams();
     params.append('clientId', clientId);
     params.append('organizerId', uitpasOrganizerId);
     params.append('embed', 'true');
     params.append('uitpas', 'true');
+    params.append('disableDefaultFilters', 'true');
     params.append('start', '0');
     params.append('limit', '200');
     if (textQuery) {
         params.append('text', textQuery);
     }
+    params.append('sort[availableTo]', 'desc'); // last available first
     const url = `${baseUrl}?${params.toString()}`;
     const myHeaders = new Headers();
     myHeaders.append('Accept', 'application/json');

package/tests/helpers/MollieMocker.ts

@@ -53,6 +53,22 @@ export type MollieMockRefund = {
     metadata: Record<string, unknown> | null;
 };
 
+export type MollieMockSettlement = {
+    id: string;
+    reference: string;
+    status: 'open' | 'pending' | 'paidout' | 'failed';
+    amount: { currency: string; value: string };
+    createdAt: string;
+    /** null for the still-open settlement, a date once it has been paid out */
+    settledAt: string | null;
+    /** Mollie payment ids (tr_...) settled in this settlement */
+    paymentIds: string[];
+    /** Mollie refund ids (re_...) settled in this settlement */
+    refundIds: string[];
+    /** Mollie chargeback ids (chb_...) settled in this settlement */
+    chargebackIds: string[];
+};
+
 const MOLLIE_CHECKOUT_URL = 'https://molliecheckout/';
 
 /**
@@ -76,6 +92,7 @@ export class MollieMocker {
     mandates: MollieMockMandate[] = [];
     chargebacks: MollieMockChargeback[] = [];
     refunds: MollieMockRefund[] = [];
+    settlements: MollieMockSettlement[] = [];
 
     #forceFailure = false;
 
@@ -85,6 +102,7 @@ export class MollieMocker {
         this.mandates = [];
         this.chargebacks = [];
         this.refunds = [];
+        this.settlements = [];
         this.#forceFailure = false;
     }
 
@@ -206,6 +224,26 @@ export class MollieMocker {
             return this.#listResource('chargebacks', this.chargebacks.map(c => this.#chargebackResource(c)));
         }
 
+        // settlements + nested payments/refunds (drives the settlements cron)
+        if (parts[0] === 'settlements' && method === 'GET') {
+            if (parts.length === 1) {
+                return this.#listResource('settlements', this.settlements.map(s => this.#settlementResource(s)));
+            }
+            const settlement = this.settlements.find(s => s.id === parts[1]);
+            if (settlement && parts.length === 3 && parts[2] === 'payments') {
+                const items = this.payments.filter(p => settlement.paymentIds.includes(p.id));
+                return this.#listResource('payments', items.map(p => this.#paymentResource(p)));
+            }
+            if (settlement && parts.length === 3 && parts[2] === 'refunds') {
+                const items = this.refunds.filter(r => settlement.refundIds.includes(r.id));
+                return this.#listResource('refunds', items.map(r => this.#refundResource(r)));
+            }
+            if (settlement && parts.length === 3 && parts[2] === 'chargebacks') {
+                const items = this.chargebacks.filter(c => settlement.chargebackIds.includes(c.id));
+                return this.#listResource('chargebacks', items.map(c => this.#chargebackResource(c)));
+            }
+        }
+
         console.error('MollieMocker: unhandled request', method, uri);
         return [500, { detail: 'MollieMocker: unhandled request ' + method + ' ' + uri }];
     }
@@ -512,6 +550,41 @@ export class MollieMocker {
         };
     }
 
+    // ---- Settlements ------------------------------------------------------
+
+    /**
+     * Register a settled (paid out) settlement that groups the given payments and refunds.
+     * Used to drive the settlements cron (CheckSettlements).
+     */
+    createSettlement(options: { payments?: MollieMockPayment[]; refunds?: MollieMockRefund[]; chargebacks?: MollieMockChargeback[]; value?: string; settledAt?: Date } = {}): MollieMockSettlement {
+        const settlement: MollieMockSettlement = {
+            id: this.createId('stl'),
+            reference: '1234567.' + (this.settlements.length + 1).toString().padStart(4, '0') + '.01',
+            status: 'paidout',
+            amount: { currency: 'EUR', value: options.value ?? '0.00' },
+            createdAt: new Date().toISOString(),
+            settledAt: (options.settledAt ?? new Date()).toISOString(),
+            paymentIds: (options.payments ?? []).map(p => p.id),
+            refundIds: (options.refunds ?? []).map(r => r.id),
+            chargebackIds: (options.chargebacks ?? []).map(c => c.id),
+        };
+        this.settlements.push(settlement);
+        return settlement;
+    }
+
+    #settlementResource(settlement: MollieMockSettlement) {
+        return {
+            resource: 'settlement',
+            id: settlement.id,
+            reference: settlement.reference,
+            status: settlement.status,
+            amount: settlement.amount,
+            createdAt: settlement.createdAt,
+            settledAt: settlement.settledAt ?? null,
+            _links: { self: { href: 'https://api.mollie.com/v2/settlements/' + settlement.id, type: 'application/hal+json' } },
+        };
+    }
+
     // ---- List helper ------------------------------------------------------
 
     #listResource(binderName: string, items: unknown[]): [number, unknown] {