@stamhoofd/backend 2.140.0 → 2.141.0

package/src/crons/settlement-sync.ts

@@ -0,0 +1,109 @@
+// Nightly settlement sync for all providers. Everything is an upsert and synced payouts are
+// skipped, so the windowed re-walk is cheap.
+import { registerCron } from '@stamhoofd/crons';
+import { Email } from '@stamhoofd/email';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { SettlementStatus } from '@stamhoofd/structures/settlements/SettlementStatus.js';
+import { Formatter } from '@stamhoofd/utility';
+
+import { SettlementSyncRunner } from '../helpers/SettlementSyncRunner.js';
+import { isApplicationFeeInvoicingEnabled } from './stripe-invoices.js';
+
+registerCron('settlement-sync', syncSettlements);
+
+/**
+ * How many days of settlements the nightly run re-walks.
+ */
+const SYNC_WINDOW_DAYS = 30;
+
+/**
+ * Fees received in a platform payout are billed by the monthly invoicer, so pendingFees taking a
+ * while to reach 0 is normal. Older than this it means the invoicer failed or skipped something.
+ */
+const MAXIMUM_PENDING_FEES_AGE_MS = 31 * 24 * 60 * 60 * 1000;
+
+let lastSettlementSync: Date | null = null;
+
+async function syncSettlements() {
+    if (STAMHOOFD.environment !== 'production') {
+        return;
+    }
+
+    // Between 5 and 6 AM Brussels time.
+    if (Formatter.luxon().hour !== 5) {
+        return;
+    }
+
+    // Wait for the next day before doing a new sync
+    const today = new Date();
+    if (lastSettlementSync && Formatter.dateIso(lastSettlementSync) === Formatter.dateIso(today)) {
+        console.log('Settlement sync done for this day');
+        return;
+    }
+
+    console.log('Syncing settlements...');
+
+    const start = new Date(today.getTime() - SYNC_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+
+    const runner = new SettlementSyncRunner();
+    await runner.run({
+        start,
+        providers: [PaymentProvider.Stripe, PaymentProvider.Mollie],
+        stripe: { retryUnsynced: true },
+    });
+
+    await reportProblemSettlements();
+
+    lastSettlementSync = new Date();
+}
+
+/**
+ * Every unsynced settlement or non-zero delta is a real question to answer, not noise.
+ *
+ * Exported for tests only.
+ */
+export async function reportProblemSettlements() {
+    // Only payouts that actually arrived: money that failed or was canceled holds no transactions
+    // to reconcile
+    const unexplained = await Settlement.select()
+        .where('status', SettlementStatus.Paid)
+        .where('unexplainedAmount', '!=', 0)
+        .limit(50)
+        .fetch();
+
+    const unsynced = await Settlement.select()
+        .where('status', SettlementStatus.Paid)
+        .where('syncedAt', null)
+        .limit(50)
+        .fetch();
+
+    // Fees only stop being pending once the invoicer bills them: while it is off, every platform
+    // payout would be reported forever
+    const stalePendingFees = isApplicationFeeInvoicingEnabled()
+        ? await Settlement.select()
+                .where('status', SettlementStatus.Paid)
+                .where('pendingFees', '!=', 0)
+                .where('settledAt', '<', new Date(Date.now() - MAXIMUM_PENDING_FEES_AGE_MS))
+                .limit(50)
+                .fetch()
+        : [];
+
+    if (unexplained.length === 0 && unsynced.length === 0 && stalePendingFees.length === 0) {
+        return;
+    }
+
+    const total = new Set([...unexplained, ...unsynced, ...stalePendingFees].map(s => s.id)).size;
+
+    const describe = (settlement: Settlement) => {
+        return settlement.provider + ' ' + settlement.externalId + ' (' + Formatter.dateIso(settlement.settledAt) + ', ' + Formatter.price(settlement.unexplainedAmount) + ' onverklaard, ' + Formatter.price(settlement.pendingFees) + ' niet-gefactureerde kosten, ' + settlement.syncFailureCount + ' mislukte pogingen)';
+    };
+
+    Email.sendWebmaster({
+        subject: 'Uitbetalingen met problemen: ' + total,
+        html: 'Deze uitbetalingen kloppen niet of konden niet gesynchroniseerd worden: <br><br>'
+            + 'Onverklaard verschil:<br>' + (unexplained.map(describe).join('<br>') || 'geen') + '<br><br>'
+            + 'Niet gesynchroniseerd:<br>' + (unsynced.map(describe).join('<br>') || 'geen') + '<br><br>'
+            + 'Kosten te lang niet gefactureerd:<br>' + (stalePendingFees.map(describe).join('<br>') || 'geen'),
+    });
+}

package/src/crons/stripe-invoices.ts

@@ -1,22 +1,28 @@
 import { registerCron } from '@stamhoofd/crons';
-import { Formatter } from '@stamhoofd/utility';
-import { StripeInvoicer } from '../helpers/StripeInvoicer.js';
 import { Organization, Platform } from '@stamhoofd/models';
+import { Formatter } from '@stamhoofd/utility';
+
+import { ApplicationFeeInvoicer } from '../helpers/ApplicationFeeInvoicer.js';
 
 registerCron('stripe-invoices', createStripeInvoices);
 
 let lastStripeInvoice: Date | null = null;
 
-async function createStripeInvoices() {
-    if (STAMHOOFD.environment !== 'production' && STAMHOOFD.environment !== 'development') {
-        return;
-    }
-
-    if (STAMHOOFD.userMode === 'platform') {
-        return;
-    }
+/**
+ * Whether application fees are billed automatically. The sync stores what we received either way,
+ * so anything that reports on uninvoiced fees has to ask this first: while it is off, fees staying
+ * uninvoiced is the expected state, not a problem.
+ *
+ * The settlements feature is not released yet: allow production at go-live.
+ */
+export function isApplicationFeeInvoicingEnabled(): boolean {
+    return (STAMHOOFD.environment as string) === 'development'
+        && STAMHOOFD.userMode !== 'platform'
+        && STAMHOOFD.STRIPE_CONNECT_METHOD !== 'standard';
+}
 
-    if (STAMHOOFD.STRIPE_CONNECT_METHOD === 'standard') {
+async function createStripeInvoices() {
+    if (!isApplicationFeeInvoicingEnabled()) {
         return;
     }
 
@@ -41,9 +47,9 @@ async function createStripeInvoices() {
 
     const membershipOrganization = await Organization.getByID(membershipOrganizationId, true);
 
-    const invoicer = new StripeInvoicer({
+    const invoicer = new ApplicationFeeInvoicer({
         secretKey: STAMHOOFD.STRIPE_SECRET_KEY,
     });
-    await invoicer.generateAllInvoices(membershipOrganization, { forceLast: Formatter.dateIso(today) === '2026-07-04' });
+    await invoicer.generateInvoices(membershipOrganization);
     lastStripeInvoice = new Date();
 }

package/src/crons.ts

@@ -3,7 +3,6 @@ import { registerCron } from '@stamhoofd/crons';
 import { Group, Organization, Payment, Registration, STPackage, Webshop } from '@stamhoofd/models';
 import { SQL } from '@stamhoofd/sql';
 import { PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
-import { checkSettlements } from './helpers/CheckSettlements.js';
 import { OrganizationDNSService } from './services/OrganizationDNSService.js';
 import { PaymentService } from './services/PaymentService.js';
 import { RegistrationService } from './services/RegistrationService.js';
@@ -193,7 +192,6 @@ async function checkOldPayments() {
 // 5 days - 10 days
 async function checkOldDirectDebitPayments() {
     let timeout = 60 * 1000 * 60 * 24 * 5;
-    const timeout2 = 60 * 1000 * 60 * 24 * 10;
 
     if (STAMHOOFD.environment === 'development') {
         // For Mollie, webhooks won't work, so we poll in the backend
@@ -207,8 +205,7 @@ async function checkOldDirectDebitPayments() {
                 PaymentMethod.DirectDebit,
             ])
                 .and('status', [PaymentStatus.Created, PaymentStatus.Pending])
-                .and('createdAt', '<', new Date(new Date().getTime() - timeout))
-                .and('createdAt', '>', new Date(new Date().getTime() - timeout2)),
+                .and('createdAt', '<', new Date(new Date().getTime() - timeout)),
         )
         .orderBy('createdAt', 'ASC')
         .limit(500)
@@ -357,7 +354,6 @@ async function checkReservedUntil() {
     }
 }
 
-registerCron('checkSettlements', checkSettlements);
 registerCron('checkExpirationEmails', checkExpirationEmails);
 registerCron('checkReservedUntil', checkReservedUntil);
 registerCron('checkDNS', checkDNS);

package/src/endpoints/organization/dashboard/balance-items/GetBalanceItemBreakdownEndpoint.test.ts

@@ -2,7 +2,7 @@ import { Request } from '@simonbackx/simple-endpoints';
 import type { BalanceItem, Organization, User } from '@stamhoofd/models';
 import { BalanceItemFactory, BalanceItemPayment, OrderFactory, OrganizationFactory, Payment, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
 import type { StamhoofdFilter } from '@stamhoofd/structures';
-import { BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, Cart, CartItem, CartItemOption, CartItemPrice, Customer, Option, OptionMenu, OrderData, PaymentMethod, PaymentProvider, PaymentStatus, PermissionLevel, Permissions, Product, ProductPrice, Settlement, TranslatedString } from '@stamhoofd/structures';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, Cart, CartItem, CartItemOption, CartItemPrice, Customer, Option, OptionMenu, OrderData, PaymentMethod, PaymentProvider, PaymentStatus, PermissionLevel, Permissions, Product, ProductPrice, SettlementReference, TranslatedString } from '@stamhoofd/structures';
 import { BreakdownRequest } from '@stamhoofd/structures/breakdown/BreakdownRequest.js';
 import type { BalanceItemBreakdown } from '@stamhoofd/structures/PaymentBreakdown.js';
 import { BreakdownAmountType, BreakdownObjectType, BreakdownPathItem, BreakdownTab } from '@stamhoofd/structures/PaymentBreakdown.js';
@@ -254,13 +254,13 @@ describe('Endpoint.GetBalanceItemBreakdownEndpoint', () => {
     });
 
     describe('Grouping by payout', () => {
-        const march = Settlement.create({ id: 'stl_march', reference: '1234567.0312.01', settledAt: new Date(2026, 2, 12), amount: 0 });
-        const april = Settlement.create({ id: 'stl_april', reference: '1234567.0409.01', settledAt: new Date(2026, 3, 9), amount: 0 });
+        const march = SettlementReference.create({ id: 'stl_march', reference: '1234567.0312.01', settledAt: new Date(2026, 2, 12), amount: 0 });
+        const april = SettlementReference.create({ id: 'stl_april', reference: '1234567.0409.01', settledAt: new Date(2026, 3, 9), amount: 0 });
 
         /**
          * Pays a part of a balance item, the way a payment provider settles it afterwards.
          */
-        const payItem = async (organization: Organization, balanceItem: BalanceItem, options: { price: number; settlement?: Settlement; status?: PaymentStatus; method?: PaymentMethod }) => {
+        const payItem = async (organization: Organization, balanceItem: BalanceItem, options: { price: number; settlement?: SettlementReference; status?: PaymentStatus; method?: PaymentMethod }) => {
             const payment = new Payment();
             payment.organizationId = organization.id;
             payment.method = options.method ?? PaymentMethod.Bancontact;

package/src/endpoints/organization/dashboard/mollie/ConnectMollieEndpoint.ts

@@ -7,8 +7,8 @@ import type { Organization as OrganizationStruct } from '@stamhoofd/structures';
 import { PermissionLevel } from '@stamhoofd/structures';
 
 import { AuthenticatedStructures } from '../../../../helpers/AuthenticatedStructures.js';
-import { checkMollieSettlementsFor } from '../../../../helpers/CheckSettlements.js';
 import { Context } from '../../../../helpers/Context.js';
+import { MollieSettlementSync } from '../../../../helpers/MollieSettlementSync.js';
 import { MollieService } from '../../../../services/MollieService.js';
 
 type Params = Record<string, never>;
@@ -53,7 +53,7 @@ export class ConnectMollieEndpoint extends Endpoint<Params, Query, Body, Respons
             await service.setupOnboarding();
 
             // Check settlements after linking (shouldn't block)
-            checkMollieSettlementsFor(mollieToken.accessToken, true).catch(console.error);
+            new MollieSettlementSync({ token: mollieToken }).syncSettlements({ start: organization.createdAt }).catch(console.error);
         }
 
         return new Response(await AuthenticatedStructures.organization(organization));

package/src/endpoints/organization/dashboard/organization/PatchOrganizationEndpoint.ts

@@ -667,7 +667,7 @@ export class PatchOrganizationEndpoint extends Endpoint<Params, Query, Body, Res
      * A custom PEPPOL endpoint id may only be set by full platform admins for now.
      */
     private requirePeppolPermission() {
-        if (!Context.auth.hasPlatformFullAccess()) {
+        if (!Context.auth.hasPlatformFullAccess() && STAMHOOFD.userMode === 'platform') {
             throw new SimpleError({
                 code: 'permission_denied',
                 message: 'Only platform admins can set a custom PEPPOL endpoint id',

package/src/endpoints/organization/dashboard/payments/GetPaymentBreakdownEndpoint.test.ts

@@ -2,7 +2,7 @@ import { Request } from '@simonbackx/simple-endpoints';
 import type { BalanceItem, Organization, User } from '@stamhoofd/models';
 import { BalanceItemFactory, BalanceItemPayment, OrderFactory, OrganizationFactory, Payment, StripeAccount, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
 import type { StamhoofdFilter } from '@stamhoofd/structures';
-import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, Cart, CartItem, CartItemOption, CartItemPrice, Customer, getBalanceItemTypeIcon, getPaymentProviderName, OptionMenu, OrderData, Option, PaymentMethod, PaymentMethodHelper, PaymentProvider, PaymentStatus, PermissionLevel, Permissions, Product, ProductPrice, Settlement, StripeBusinessProfile, StripeMetaData, TransferSettings, TranslatedString } from '@stamhoofd/structures';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, Cart, CartItem, CartItemOption, CartItemPrice, Customer, getBalanceItemTypeIcon, getPaymentProviderName, OptionMenu, OrderData, Option, PaymentMethod, PaymentMethodHelper, PaymentProvider, PaymentStatus, PermissionLevel, Permissions, Product, ProductPrice, SettlementReference, StripeBusinessProfile, StripeMetaData, TransferSettings, TranslatedString } from '@stamhoofd/structures';
 import { BreakdownRequest } from '@stamhoofd/structures/breakdown/BreakdownRequest.js';
 import type { PaymentBreakdown } from '@stamhoofd/structures/PaymentBreakdown.js';
 import { BreakdownGraphUnit, BreakdownObjectType, BreakdownPathItem, BreakdownTab } from '@stamhoofd/structures/PaymentBreakdown.js';
@@ -142,7 +142,7 @@ describe('Endpoint.GetPaymentBreakdownEndpoint', () => {
         iban?: string;
         transferDescription?: string;
         transferFee?: number;
-        settlement?: Settlement;
+        settlement?: SettlementReference;
         /**
          * What this payment rounded away, because a payment goes to the cent while what was charged
          * goes to four digits after the comma.
@@ -631,7 +631,7 @@ describe('Endpoint.GetPaymentBreakdownEndpoint', () => {
 
     describe('Grouping by payout', () => {
         const createSettlement = (reference: string, settledAt: Date) => {
-            return Settlement.create({ id: 'stl_' + reference, reference, settledAt, amount: 0 });
+            return SettlementReference.create({ id: 'stl_' + reference, reference, settledAt, amount: 0 });
         };
 
         test('per payout, with what is not online and what still has to be paid out apart', async () => {

package/src/endpoints/organization/dashboard/payments/GetPaymentsEndpoint.test.ts

@@ -1,9 +1,11 @@
 import { Request } from '@simonbackx/simple-endpoints';
 import type { Organization, User } from '@stamhoofd/models';
-import { BalanceItem, BalanceItemFactory, BalanceItemPayment, OrderFactory, OrganizationFactory, Payment, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemFactory, BalanceItemPayment, OrderFactory, OrganizationFactory, Payment, StripeAccount, Token, UserFactory, WebshopFactory } from '@stamhoofd/models';
 import type { PaginatedResponse, PaymentGeneral, StamhoofdFilter } from '@stamhoofd/structures';
-import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, LimitedFilteredRequest, PaymentMethod, PaymentStatus, PermissionLevel, Permissions, TranslatedString } from '@stamhoofd/structures';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, LimitedFilteredRequest, PaymentMethod, PaymentProvider, PaymentStatus, PermissionLevel, Permissions, TranslatedString } from '@stamhoofd/structures';
+import { v4 as uuidv4 } from 'uuid';
 import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { SettlementService } from '../../../../services/SettlementService.js';
 import { GetPaymentsEndpoint } from './GetPaymentsEndpoint.js';
 
 // These tests exercise the balance-item filters reused inside the payments query (balanceItemPayments ->
@@ -155,4 +157,150 @@ describe('Endpoint.GetPaymentsEndpoint', () => {
             expect(response.body.results.map(r => r.id)).toEqual([matchingPayment.id]);
         });
     });
+
+    describe('Settlements of a payment', () => {
+        const createSettledPayment = async (organization: Organization) => {
+            const payment = new Payment();
+            payment.method = PaymentMethod.Bancontact;
+            payment.provider = PaymentProvider.Stripe;
+            payment.status = PaymentStatus.Succeeded;
+            payment.organizationId = organization.id;
+            payment.price = 50_00_00;
+            payment.paidAt = new Date();
+            await payment.save();
+
+            const settlement = await SettlementService.upsertSettlement({
+                provider: PaymentProvider.Stripe,
+                externalId: 'po_' + payment.id,
+                organizationId: organization.id,
+                reference: 'STRIPE PAYOUT',
+                amount: 49_00_00,
+                settledAt: new Date(2026, 0, 15),
+            });
+            await SettlementService.upsertPaymentLine(settlement, {
+                paymentId: payment.id,
+                amount: 50_00_00,
+                externalId: 'txn_' + payment.id,
+                occurredAt: new Date(2026, 0, 14),
+            });
+
+            return { payment, settlement };
+        };
+
+        test('the m2m settlement filter selects only payments in a matching payout', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await createFinanceUser(organization);
+
+            const { payment, settlement } = await createSettledPayment(organization);
+
+            // Negative control: a payment without settlement rows
+            const other = new Payment();
+            other.method = PaymentMethod.Bancontact;
+            other.provider = PaymentProvider.Stripe;
+            other.status = PaymentStatus.Succeeded;
+            other.organizationId = organization.id;
+            other.price = 10_00_00;
+            await other.save();
+
+            const response = await getPayments({
+                filter: {
+                    settlements: {
+                        $elemMatch: {
+                            settlement: {
+                                externalId: settlement.externalId,
+                            },
+                        },
+                    },
+                },
+                organization,
+                user,
+            });
+
+            expect(response.status).toBe(200);
+            expect(response.body.results.map(r => r.id)).toEqual([payment.id]);
+        });
+
+        test('an admin of the organization receives the settlements of a payment', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await createFinanceUser(organization);
+
+            const { payment, settlement } = await createSettledPayment(organization);
+
+            const response = await getPayments({
+                filter: { id: payment.id },
+                organization,
+                user,
+            });
+
+            expect(response.status).toBe(200);
+            expect(response.body.results).toHaveLength(1);
+
+            const result = response.body.results[0];
+            expect(result.settlements).toHaveLength(1);
+            expect(result.settlements[0]).toMatchObject({
+                paymentId: payment.id,
+                amount: 50_00_00,
+                externalId: 'txn_' + payment.id,
+            });
+            expect(result.settlements[0].settlement).toMatchObject({
+                externalId: settlement.externalId,
+                reference: 'STRIPE PAYOUT',
+                amount: 49_00_00,
+            });
+        });
+
+        test('the platform payout of a destination charge is never returned to the organization', async () => {
+            const organization = await new OrganizationFactory({}).create();
+            const user = await createFinanceUser(organization);
+
+            const stripeAccount = new StripeAccount();
+            stripeAccount.organizationId = organization.id;
+            stripeAccount.accountId = 'acct_' + uuidv4();
+            await stripeAccount.save();
+
+            const payment = new Payment();
+            payment.method = PaymentMethod.Bancontact;
+            payment.provider = PaymentProvider.Stripe;
+            payment.status = PaymentStatus.Succeeded;
+            payment.organizationId = organization.id;
+            payment.stripeAccountId = stripeAccount.id;
+            payment.price = 50_00_00;
+            payment.paidAt = new Date();
+            await payment.save();
+
+            const organizationPayout = await SettlementService.upsertSettlement({
+                provider: PaymentProvider.Stripe,
+                externalId: 'po_org_' + payment.id,
+                stripeAccountId: stripeAccount.id,
+                organizationId: organization.id,
+                amount: 49_00_00,
+                settledAt: new Date(2026, 0, 15),
+            });
+            await SettlementService.upsertPaymentLine(organizationPayout, {
+                paymentId: payment.id, amount: 50_00_00, externalId: 'txn_org_' + payment.id, occurredAt: new Date(2026, 0, 14),
+            });
+
+            // The same gross charge also sits in our platform payout, owned by the membership
+            // organization
+            const membershipOrganization = await new OrganizationFactory({}).create();
+            const platformPayout = await SettlementService.upsertSettlement({
+                provider: PaymentProvider.Stripe,
+                externalId: 'po_platform_' + payment.id,
+                stripeAccountId: null,
+                organizationId: membershipOrganization.id,
+                amount: 1234_00_00,
+                settledAt: new Date(2026, 0, 12),
+            });
+            await SettlementService.upsertPaymentLine(platformPayout, {
+                paymentId: payment.id, amount: 50_00_00, externalId: 'txn_platform_' + payment.id, occurredAt: new Date(2026, 0, 11),
+            });
+
+            const response = await getPayments({ filter: { id: payment.id }, organization, user });
+
+            expect(response.status).toBe(200);
+            const result = response.body.results[0];
+            expect(result.settlements).toHaveLength(1);
+            expect(result.settlements[0].settlement.externalId).toBe(organizationPayout.externalId);
+        });
+    });
 });

package/src/endpoints/organization/dashboard/{stripe/GetStripePayoutsExportStatusEndpoint.ts → settlements/GetSettlementsSyncStatusEndpoint.ts}

@@ -1,20 +1,22 @@
 import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
 import { Endpoint, Response } from '@simonbackx/simple-endpoints';
 
-import { PayoutExportStatus, StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
+import { SettlementsSyncStatus } from '@stamhoofd/structures/settlements/SettlementsSyncStatus.js';
+
+import { SettlementsSyncEndpoint } from './SettlementsSyncEndpoint.js';
 
 type Params = Record<string, never>;
 type Body = undefined;
 type Query = undefined;
-type ResponseBody = PayoutExportStatus[];
+type ResponseBody = SettlementsSyncStatus[];
 
-export class GetStripePayoutsExportStatusEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+export class GetSettlementsSyncStatusEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
     protected doesMatch(request: Request): [true, Params] | [false] {
         if (request.method !== 'GET') {
             return [false];
         }
 
-        const params = Endpoint.parseParameters(request.url, '/stripe/payouts/status', {});
+        const params = Endpoint.parseParameters(request.url, '/settlements/sync/status', {});
 
         if (params) {
             return [true, params as Params];
@@ -23,10 +25,10 @@ export class GetStripePayoutsExportStatusEndpoint extends Endpoint<Params, Query
     }
 
     async handle(_: DecodedRequest<Params, Query, Body>) {
-        await StripePayoutsExportEndpoint.authenticate();
+        await SettlementsSyncEndpoint.authenticate();
 
-        return new Response(StripePayoutsExportEndpoint.queue.map((item) => {
-            return PayoutExportStatus.create(item);
+        return new Response(SettlementsSyncEndpoint.queue.map((item) => {
+            return SettlementsSyncStatus.create(item);
         }));
     }
 }

package/src/endpoints/organization/dashboard/settlements/SettlementsExportEndpoint.test.ts

@@ -0,0 +1,157 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import { EmailMocker } from '@stamhoofd/email';
+import type { Organization, Token, User } from '@stamhoofd/models';
+import { OrganizationFactory, Payment, Token as TokenModel, UserFactory } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentMethod, PaymentProvider, PaymentStatus, PermissionLevel, Permissions } from '@stamhoofd/structures';
+import { SettlementChargeType } from '@stamhoofd/structures/settlements/SettlementChargeType.js';
+import { STExpect } from '@stamhoofd/test-utils';
+import { v4 as uuidv4 } from 'uuid';
+
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
+import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
+import { SettlementService } from '../../../../services/SettlementService.js';
+import { SettlementsExportEndpoint } from './SettlementsExportEndpoint.js';
+
+describe('Endpoint.SettlementsExport', () => {
+    const endpoint = new SettlementsExportEndpoint();
+
+    let membershipOrganization: Organization;
+    let admin: User;
+    let adminToken: Token;
+
+    beforeAll(async () => {
+        membershipOrganization = await initMembershipOrganization();
+        membershipOrganization.privateMeta.featureFlags = ['settlements'];
+        await membershipOrganization.save();
+
+        ({ admin, adminToken } = await initPlatformAdmin());
+    });
+
+    const createFinanceAdmin = async (organization: Organization) => {
+        const user = await new UserFactory({
+            organization,
+            permissions: Permissions.create({ level: PermissionLevel.Full }),
+        }).create();
+        return { user, token: await TokenModel.createToken(user) };
+    };
+
+    const post = async (organization: Organization, token: Token, { start = new Date(2026, 0, 1), end = new Date(2026, 1, 1) } = {}) => {
+        const request = Request.buildJson('POST', '/settlements/export', organization.getApiHost(), {
+            start: start.getTime(),
+            end: end.getTime(),
+        });
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(endpoint, request);
+    };
+
+    const createSettledPayment = async () => {
+        const organization = await new OrganizationFactory({}).create();
+
+        const payment = new Payment();
+        payment.organizationId = organization.id;
+        payment.method = PaymentMethod.Bancontact;
+        payment.provider = PaymentProvider.Mollie;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = 50_00_00;
+        payment.paidAt = new Date(2026, 0, 10);
+        await payment.save();
+
+        const settlement = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Mollie,
+            externalId: 'stl_' + uuidv4(),
+            organizationId: organization.id,
+            reference: '1234567.2601.01',
+            amount: 49_63_70,
+            settledAt: new Date(2026, 0, 15),
+        });
+        await SettlementService.upsertPaymentLine(settlement, {
+            paymentId: payment.id,
+            amount: 50_00_00,
+            externalId: 'tr_' + uuidv4(),
+            occurredAt: new Date(2026, 0, 15),
+        });
+        await SettlementService.upsertCharge({
+            type: SettlementChargeType.ProviderTransactionFee,
+            externalId: settlement.externalId + ':cost:0',
+            amount: -30_00,
+            settlementId: settlement.id,
+            organizationId: settlement.organizationId,
+            providerInvoiceId: 'inv_123',
+            description: 'Transactiekosten',
+            occurredAt: new Date(2026, 0, 15),
+        });
+        await SettlementService.upsertCharge({
+            type: SettlementChargeType.Tax,
+            externalId: settlement.externalId + ':cost:0:tax',
+            amount: -6_30,
+            settlementId: settlement.id,
+            organizationId: settlement.organizationId,
+            providerInvoiceId: 'inv_123',
+            description: 'BTW op transactiekosten',
+            occurredAt: new Date(2026, 0, 15),
+        });
+        await SettlementService.finishSync(settlement, { transactionCount: 3 });
+
+        return { organization, payment, settlement };
+    };
+
+    test('A platform admin receives the report by email', async () => {
+        await createSettledPayment();
+
+        const response = await post(membershipOrganization, adminToken);
+        expect(response.status).toBe(200);
+
+        await QueueHandler.awaitAll();
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const reportEmail = emails.find(e => e.subject.startsWith('Uitbetalingen export'));
+        expect(reportEmail).toBeDefined();
+        expect(reportEmail!.attachments).toHaveLength(1);
+        expect(reportEmail!.attachments![0].filename).toContain('.xlsx');
+        expect(reportEmail!.to).toContain(admin.email);
+    });
+
+    test('A user without finance access cannot export settlements', async () => {
+        const user = await new UserFactory({ organization: membershipOrganization }).create();
+        const token = await TokenModel.createToken(user);
+
+        await expect(post(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+    });
+
+    test('A finance admin exports the settlements of their own organization', async () => {
+        const { organization } = await createSettledPayment();
+        organization.privateMeta.featureFlags = ['settlements'];
+        await organization.save();
+
+        const { user, token } = await createFinanceAdmin(organization);
+
+        const response = await post(organization, token);
+        expect(response.status).toBe(200);
+
+        await QueueHandler.awaitAll();
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const reportEmail = emails.filter(e => e.subject.startsWith('Uitbetalingen export')).at(-1);
+        expect(reportEmail).toBeDefined();
+        expect(reportEmail!.to).toContain(user.email);
+    });
+
+    test('Without the feature flag the export is not available', async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const { token } = await createFinanceAdmin(organization);
+
+        await expect(post(organization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'not_available' }),
+        );
+    });
+
+    test('An unbounded range is rejected', async () => {
+        await expect(post(membershipOrganization, adminToken, { start: new Date(2020, 0, 1), end: new Date(2026, 0, 1) })).rejects.toThrow(
+            STExpect.simpleError({ code: 'range_too_large' }),
+        );
+    });
+});