@stamhoofd/backend 2.140.0 → 2.142.0

package/src/helpers/MollieSettlementSync.test.ts

@@ -0,0 +1,361 @@
+import type { MollieToken } from '@stamhoofd/models';
+import { MolliePayment, OrganizationFactory, Payment } from '@stamhoofd/models';
+import { PaymentSettlement } from '@stamhoofd/models/models/PaymentSettlement.js';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { SettlementCharge } from '@stamhoofd/models/models/SettlementCharge.js';
+import { PaymentMethod, PaymentProvider, PaymentStatus, PaymentType } from '@stamhoofd/structures';
+import { SettlementChargeType } from '@stamhoofd/structures/settlements/SettlementChargeType.js';
+import type { MollieMockPayment, MollieMockRefund } from '../../tests/helpers/MollieMocker.js';
+import { MollieMocker } from '../../tests/helpers/MollieMocker.js';
+import { MollieSettlementSync } from './MollieSettlementSync.js';
+import type { SettlementSyncSummary } from './ProviderSettlementSyncRunner.js';
+
+describe('Helper.MollieSettlementSync', () => {
+    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: MollieToken, options: { start?: Date; end?: Date; summary?: SettlementSyncSummary } = {}) => {
+        await new MollieSettlementSync({ token }).syncSettlements({
+            start: options.start ?? new Date(2020, 0, 1),
+            end: options.end,
+            summary: options.summary,
+        });
+    };
+
+    /**
+     * 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,
+        });
+    });
+
+    describe('Settlement rows', () => {
+        const getSettlementRow = async (externalId: string) => {
+            return await Settlement.select().where('externalId', externalId).first(true);
+        };
+
+        test('legacy JSON and new rows agree, and the settlement reconciles to zero', async () => {
+            const { organization, token, payment, refundPayment, mockPayment, mockRefund } = await init();
+
+            // 50.00 - 20.00 in entries, minus 0.30 costs + 0.06 VAT
+            const settlement = mollieMocker.createSettlement({
+                payments: [mockPayment],
+                refunds: [mockRefund],
+                value: '29.64',
+                invoiceId: 'inv_123',
+                periods: {
+                    2026: {
+                        '01': {
+                            costs: [{
+                                description: 'Bancontact betalingen',
+                                method: 'bancontact',
+                                amountNet: { currency: 'EUR', value: '0.30' },
+                                amountVat: { currency: 'EUR', value: '0.06' },
+                            }],
+                        },
+                    },
+                },
+            });
+
+            await runCron(token);
+
+            const row = await getSettlementRow(settlement.id);
+            expect(row).toMatchObject({
+                provider: PaymentProvider.Mollie,
+                organizationId: organization.id,
+                reference: settlement.reference,
+                amount: 29_6400,
+                unexplainedAmount: 0,
+            });
+            expect(row.syncedAt).not.toBeNull();
+
+            const lines = await PaymentSettlement.select().where('settlementId', row.id).fetch();
+            expect(lines.map(l => [l.externalId, l.paymentId, l.amount]).sort()).toEqual([
+                [mockPayment.id, payment.id, 50_0000],
+                [mockRefund.id, refundPayment.id, -20_0000],
+            ].sort());
+
+            const charges = await SettlementCharge.select().where('settlementId', row.id).fetch();
+            expect(charges.map(c => ({ type: c.type, amount: c.amount, providerInvoiceId: c.providerInvoiceId, occurredAt: c.occurredAt })).sort((a, b) => a.amount - b.amount)).toEqual([
+                { type: SettlementChargeType.ProviderTransactionFee, amount: -30_00, providerInvoiceId: 'inv_123', occurredAt: new Date(2026, 0, 1) },
+                { type: SettlementChargeType.Tax, amount: -6_00, providerInvoiceId: 'inv_123', occurredAt: new Date(2026, 0, 1) },
+            ]);
+
+            // The legacy blob agrees with the new settlement row
+            const updatedPayment = await Payment.getByID(payment.id);
+            expect(updatedPayment!.settlement!.id).toBe(row.externalId);
+            expect(updatedPayment!.settlement!.amount).toBe(row.amount);
+        });
+
+        test('the invoiceId is filled in on a later re-walk', async () => {
+            const { token, mockPayment } = await init();
+            const settlement = mollieMocker.createSettlement({
+                payments: [mockPayment],
+                value: '49.70',
+                periods: {
+                    2026: {
+                        '01': {
+                            costs: [{
+                                description: 'Bancontact betalingen',
+                                method: 'bancontact',
+                                amountNet: { currency: 'EUR', value: '0.30' },
+                                amountVat: { currency: 'EUR', value: '0.00' },
+                            }],
+                        },
+                    },
+                },
+            });
+
+            await runCron(token);
+            const row = await getSettlementRow(settlement.id);
+            const costs = await SettlementCharge.select().where('settlementId', row.id).fetch();
+            expect(costs).toHaveLength(1);
+            expect(costs[0].providerInvoiceId).toBeNull();
+
+            // Mollie created the invoice since the last walk
+            settlement.invoiceId = 'inv_later';
+            await runCron(token);
+
+            const updated = await SettlementCharge.getByID(costs[0].id);
+            expect(updated!.providerInvoiceId).toBe('inv_later');
+        });
+
+        test('re-running stores identical rows', async () => {
+            const { token, mockPayment, mockRefund } = await init();
+            const settlement = mollieMocker.createSettlement({ payments: [mockPayment], refunds: [mockRefund], value: '30.00' });
+
+            await runCron(token);
+            const row = await getSettlementRow(settlement.id);
+            const before = (await PaymentSettlement.select().where('settlementId', row.id).fetch()).map(l => l.id).sort();
+
+            await runCron(token);
+            const after = (await PaymentSettlement.select().where('settlementId', row.id).fetch()).map(l => l.id).sort();
+            expect(after).toEqual(before);
+            expect(await Settlement.select().where('externalId', settlement.id).count()).toBe(1);
+        });
+    });
+
+    test('A settlement settled before the window start is not walked', async () => {
+        const { token, mockPayment } = await init();
+
+        // The list is newest-first: the walk must sync the recent settlement, then stop at the old one
+        const oldSettlement = mollieMocker.createSettlement({ payments: [mockPayment], value: '10.00', settledAt: new Date(2019, 5, 1) });
+        const recentSettlement = mollieMocker.createSettlement({ payments: [mockPayment], value: '50.00' });
+
+        await runCron(token);
+
+        expect(await Settlement.select().where('externalId', recentSettlement.id).count()).toBe(1);
+        expect(await Settlement.select().where('externalId', oldSettlement.id).count()).toBe(0);
+    });
+
+    test('A settlement settled after the window end is skipped, older ones are still walked', async () => {
+        const { token, mockPayment } = await init();
+
+        const afterEnd = mollieMocker.createSettlement({ payments: [mockPayment], value: '50.00', settledAt: new Date(2026, 5, 1) });
+        const inWindow = mollieMocker.createSettlement({ payments: [mockPayment], value: '20.00', settledAt: new Date(2026, 1, 1) });
+
+        await runCron(token, { start: new Date(2026, 0, 1), end: new Date(2026, 2, 1) });
+
+        expect(await Settlement.select().where('externalId', inWindow.id).count()).toBe(1);
+        expect(await Settlement.select().where('externalId', afterEnd.id).count()).toBe(0);
+    });
+
+    test('The walk follows pagination until it reaches the window start', async () => {
+        const { token, mockPayment } = await init();
+        mollieMocker.settlementsPageSize = 2;
+
+        // Two pages: [first, second] and [third, beforeWindow] — the third settlement only syncs
+        // if the walk follows the next link, and the pre-window one proves it still stops
+        const first = mollieMocker.createSettlement({ payments: [mockPayment], value: '50.00', settledAt: new Date(2026, 2, 3) });
+        const second = mollieMocker.createSettlement({ payments: [mockPayment], value: '20.00', settledAt: new Date(2026, 2, 2) });
+        const third = mollieMocker.createSettlement({ payments: [mockPayment], value: '10.00', settledAt: new Date(2026, 2, 1) });
+        const beforeWindow = mollieMocker.createSettlement({ payments: [mockPayment], value: '5.00', settledAt: new Date(2019, 0, 1) });
+
+        await runCron(token);
+
+        for (const settlement of [first, second, third]) {
+            expect(await Settlement.select().where('externalId', settlement.id).count()).toBe(1);
+        }
+        expect(await Settlement.select().where('externalId', beforeWindow.id).count()).toBe(0);
+    });
+
+    test('The summary counts synced settlements', async () => {
+        const { token, mockPayment } = await init();
+        mollieMocker.createSettlement({ payments: [mockPayment], value: '50.00' });
+
+        const summary: SettlementSyncSummary = { feeMonths: 0, failedFeeMonths: 0, synced: 0, skipped: 0, failed: 0 };
+        await runCron(token, { summary });
+
+        expect(summary.synced).toBe(1);
+        expect(summary.failed).toBe(0);
+    });
+
+    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/MollieSettlementSync.ts

@@ -0,0 +1,323 @@
+import type { MollieToken } from '@stamhoofd/models';
+import { MolliePayment, Payment } from '@stamhoofd/models';
+import type { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { SettlementChargeType } from '@stamhoofd/structures/settlements/SettlementChargeType.js';
+import { SettlementStatus } from '@stamhoofd/structures/settlements/SettlementStatus.js';
+import axios from 'axios';
+import { createHash } from 'crypto';
+
+import { ReportedRows, SettlementService } from '../services/SettlementService.js';
+import type { SettlementSyncSummary } from './ProviderSettlementSyncRunner.js';
+
+type MollieSettlementCost = {
+    description: string;
+    method: string | null;
+    amountNet: {
+        currency: string;
+        value: string;
+    };
+    amountVat: {
+        currency: string;
+        value: string;
+    } | null;
+};
+
+type MollieSettlement = {
+    id: string;
+    reference: string;
+    createdAt: string;
+    settledAt: string;
+    status: 'open' | 'pending' | 'paidout' | 'failed';
+    amount: {
+        currency: string;
+        value: string;
+    };
+    /**
+     * "The ID of the oldest invoice created for all the periods": null until Mollie created it,
+     * filled in by the regular re-walk of recent settlements.
+     */
+    invoiceId?: string | null;
+    periods?: Record<string, Record<string, { costs?: MollieSettlementCost[]; invoiceId?: string | null }>>;
+};
+
+/**
+ * Everything one settlement walk needs to share between the resource pages.
+ */
+type SettlementSyncState = {
+    settlementRow: Settlement;
+    reported: ReportedRows;
+};
+
+/**
+ * Same expression as the legacy blob write, so the two can never disagree (euros → 4-decimal
+ * platform units).
+ */
+function mollieAmountToUnits(value: string): number {
+    return Math.round(parseFloat(value) * 100) * 100;
+}
+
+function getMollieSettlementStatus(status: MollieSettlement['status']): SettlementStatus {
+    switch (status) {
+        case 'paidout': return SettlementStatus.Paid;
+        case 'failed': return SettlementStatus.Failed;
+        default: return SettlementStatus.Pending;
+    }
+}
+
+/**
+ * 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;
+};
+
+/**
+ * Walks the settlements of one Mollie account and stores every entry in them: payments, refunds
+ * and chargebacks become payment_settlements rows, Mollie's own costs become settlement_charges
+ * rows, and the legacy blob is written in the same pass. Every settlement row written belongs to
+ * the organization that owns the token's account.
+ */
+export class MollieSettlementSync {
+    private token: MollieToken;
+
+    constructor({ token }: { token: MollieToken }) {
+        this.token = token;
+    }
+
+    /**
+     * Walk the settlements newest first, until they settle before `start`.
+     */
+    async syncSettlements({ start, end = new Date(), summary }: {
+        start: Date;
+        end?: Date;
+        summary?: SettlementSyncSummary;
+    }): Promise<void> {
+        let url: string | null = 'https://api.mollie.com/v2/settlements?limit=250';
+
+        while (url) {
+            const request = await this.#get(url);
+
+            if (request.status !== 200) {
+                console.error('Failed to fetch settlements');
+                console.error(request.data);
+                return;
+            }
+
+            const settlements = request.data._embedded?.settlements as MollieSettlement[] | undefined;
+            if (!settlements) {
+                console.error('Unreadable settlements');
+                return;
+            }
+
+            for (const settlement of settlements) {
+                if (settlement.settledAt === null) {
+                    // Skip: this is the open settlement
+                    continue;
+                }
+
+                const settledAt = new Date(settlement.settledAt);
+
+                if (isNaN(settledAt.getTime())) {
+                    console.error('Received an invalid settledAt from Mollie', settlement, 'for organization', this.token.organizationId);
+                    continue;
+                }
+
+                if (settledAt.getTime() > end.getTime()) {
+                    continue;
+                }
+
+                if (settledAt.getTime() < start.getTime()) {
+                    // The list is newest-first: everything from here on settled before the window
+                    return;
+                }
+
+                try {
+                    await SettlementService.lock(PaymentProvider.Mollie, settlement.id, () => this.#syncSettlement(settlement));
+                    if (summary) {
+                        summary.synced += 1;
+                    }
+                } catch (e) {
+                    console.error('Sync of Mollie settlement ' + settlement.id + ' failed', e);
+                    if (summary) {
+                        summary.failed += 1;
+                    }
+                }
+            }
+
+            const next = request.data._links?.next?.href as string | undefined;
+            url = (settlements.length > 0 && next) ? next : null;
+        }
+    }
+
+    /**
+     * The token can expire during a long walk: refresh it (if needed) before every request.
+     */
+    async #get(url: string) {
+        await this.token.refreshIfNeeded();
+        return await axios.get(url, {
+            headers: {
+                Authorization: 'Bearer ' + this.token.accessToken,
+            },
+        });
+    }
+
+    async #syncSettlement(settlement: MollieSettlement) {
+        const settlementRow = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Mollie,
+            externalId: settlement.id,
+            stripeAccountId: null,
+            organizationId: this.token.organizationId,
+            reference: settlement.reference,
+            amount: mollieAmountToUnits(settlement.amount.value),
+            status: getMollieSettlementStatus(settlement.status),
+            settledAt: new Date(settlement.settledAt),
+        });
+
+        const state: SettlementSyncState = {
+            settlementRow,
+            reported: new ReportedRows(),
+        };
+
+        try {
+            // Regular payments settled in this settlement
+            await this.#syncResource(settlement, 'payments', state);
+
+            // 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 this.#syncResource(settlement, 'refunds', state);
+
+            // Chargebacks settled in this settlement. Like refunds, these are negative entries linked to a
+            // chargeback payment (created by the mollie-chargebacks cron).
+            await this.#syncResource(settlement, 'chargebacks', state);
+
+            // Mollie's own costs, so the settlement reconciles to 0 like a Stripe one
+            await this.#storeMollieCosts(settlement, state);
+
+            await SettlementService.sweepSettlement(settlementRow, state.reported);
+            await SettlementService.finishSync(settlementRow, {
+                transactionCount: state.reported.paymentLineExternalIds.size + state.reported.chargeExternalIds.size,
+            });
+        } catch (e) {
+            await SettlementService.markSyncFailed(settlementRow);
+            throw e;
+        }
+    }
+
+    /**
+     * Mollie invoices its costs per period: every cost line becomes a ProviderTransactionFee row plus
+     * a Tax row for its VAT, carrying the settlement's invoiceId so they can be matched against the
+     * invoice document.
+     */
+    async #storeMollieCosts(settlement: MollieSettlement, state: SettlementSyncState) {
+        for (const [year, months] of Object.entries(settlement.periods ?? {})) {
+            for (const [month, period] of Object.entries(months)) {
+                // Mollie states the period explicitly: that month is the cost's date, so the monthly
+                // grouping stays derivable from occurredAt alone
+                const occurredAt = new Date(parseInt(year), parseInt(month) - 1, 1);
+
+                // A settlement can straddle a month boundary: each period can be billed on its own
+                // invoice, the settlement-level id is only "the oldest invoice of all the periods"
+                const invoiceId = period.invoiceId ?? settlement.invoiceId;
+
+                for (const cost of period.costs ?? []) {
+                    // Mollie aggregates cost lines per description + method, so that pair identifies
+                    // the line within the period (hashed to keep the externalId short)
+                    const hash = createHash('sha256').update(cost.description + ':' + (cost.method ?? '')).digest('hex').slice(0, 16);
+                    const externalId = settlement.id + ':' + year + '-' + month + ':cost:' + hash;
+                    const description = cost.description + (cost.method ? ' (' + cost.method + ')' : '');
+
+                    const rows = [
+                        { type: SettlementChargeType.ProviderTransactionFee, externalId, amount: -mollieAmountToUnits(cost.amountNet.value) },
+                        ...(cost.amountVat && mollieAmountToUnits(cost.amountVat.value) !== 0
+                            ? [{ type: SettlementChargeType.Tax, externalId: externalId + ':tax', amount: -mollieAmountToUnits(cost.amountVat.value) }]
+                            : []),
+                    ];
+
+                    for (const row of rows) {
+                        const charge = await SettlementService.upsertCharge({
+                            ...row,
+                            settlementId: state.settlementRow.id,
+                            organizationId: state.settlementRow.organizationId,
+                            ...(invoiceId ? { providerInvoiceId: invoiceId } : {}),
+                            description,
+                            occurredAt,
+                        });
+                        state.reported.charge(charge);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 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 #syncResource(settlement: MollieSettlement, resource: 'payments' | 'refunds' | 'chargebacks', state: SettlementSyncState, fromId?: string) {
+        const limit = 250;
+
+        const request = await this.#get('https://api.mollie.com/v2/settlements/' + settlement.id + '/' + resource + '?limit=' + limit + (fromId ? ('&from=' + encodeURIComponent(fromId)) : ''));
+
+        if (request.status === 200) {
+            const entries = request.data._embedded[resource] as MollieSettlementEntryJSON[];
+
+            for (const entry of entries) {
+                await this.#applySettlementToPayment(settlement, entry.id, state);
+            }
+
+            // Check next page
+            if (request.data._links.next && entries.length > 0) {
+                await this.#syncResource(settlement, resource, state, 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.
+     * Entries without a local payment belong to a different system on the same Mollie account: they are
+     * skipped, and the settlement's unexplainedAmount shows the gap.
+     */
+    async #applySettlementToPayment(settlement: MollieSettlement, mollieId: string, state: SettlementSyncState) {
+        // 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) {
+                // A payment is only ever settled by the payouts of its own organization. The
+                // platform's own Mollie account can reach payments of other systems on the same
+                // token, and those may not be linked here
+                if (payment.organizationId !== state.settlementRow.organizationId) {
+                    console.log('Skipped payment ' + payment.id + ' of another organization in Mollie settlement ' + settlement.id);
+                    return;
+                }
+
+                state.reported.paymentLine(await SettlementService.upsertPaymentLine(state.settlementRow, {
+                    paymentId: payment.id,
+                    amount: payment.price,
+                    externalId: mollieId,
+                    occurredAt: new Date(settlement.settledAt),
+                }));
+
+                // The blob is written from the stored rows, so it stays deterministic across
+                // re-syncs and keeps its scoping rules in one place
+                await SettlementService.updateLegacySettlementReference(payment);
+
+                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)
+        }
+    }
+}