@stamhoofd/backend 2.131.0 → 2.132.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stamhoofd/backend",
-    "version": "2.131.0",
+    "version": "2.132.0",
     "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.0",
+        "@stamhoofd/backend-i18n": "2.132.0",
+        "@stamhoofd/backend-middleware": "2.132.0",
+        "@stamhoofd/crons": "2.132.0",
+        "@stamhoofd/email": "2.132.0",
+        "@stamhoofd/excel-writer": "2.132.0",
+        "@stamhoofd/logging": "2.132.0",
+        "@stamhoofd/models": "2.132.0",
+        "@stamhoofd/object-differ": "2.132.0",
+        "@stamhoofd/queues": "2.132.0",
+        "@stamhoofd/sql": "2.132.0",
+        "@stamhoofd/structures": "2.132.0",
+        "@stamhoofd/types": "2.132.0",
+        "@stamhoofd/utility": "2.132.0",
         "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.0",
         "@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": "f7143688bb7be0cd9f73c209f4b55c9bacdd59b8"
 }

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.ts

@@ -58,7 +58,7 @@ export class PatchInvoicesEndpoint extends Endpoint<Params, Query, Body, Respons
         }
 
         return new Response(
-            await AuthenticatedStructures.invoices(invoices),
+            await AuthenticatedStructures.invoices(invoices, true),
         );
     }
 }

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/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] {