@stamhoofd/backend 2.140.0 → 2.142.0

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' }),
+        );
+    });
+});

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

@@ -0,0 +1,140 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { AutoEncoder, DateDecoder, EnumDecoder, field } from '@simonbackx/simple-encoding';
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { Email } from '@stamhoofd/email';
+import { Organization, Platform } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+
+import { Context } from '../../../../helpers/Context.js';
+import { SettlementExporter } from '../../../../helpers/SettlementExporter.js';
+
+/**
+ * payment_settlements grows like payments, so an export can't span an unbounded range.
+ */
+const MAXIMUM_RANGE_MS = 1100 * 24 * 60 * 60 * 1000;
+
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+
+    @field({ decoder: DateDecoder })
+    end: Date;
+
+    @field({ decoder: new EnumDecoder(PaymentProvider), nullable: true, optional: true })
+    provider: PaymentProvider | null = null;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+
+/**
+ * Build the settlements reconciliation report (from the stored tables only, no provider API calls)
+ * and email it to the requesting admin.
+ *
+ * An export always covers exactly the payouts of the organization in context, for any finance
+ * admin of that organization. The platform's own payouts belong to the membership organization, so
+ * platform admins export those by scoping to the membership organization like any other.
+ */
+export class SettlementsExportEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+
+        const params = Endpoint.parseParameters(request.url, '/settlements/export', {});
+
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    static async authenticate() {
+        const organization = await Context.setOrganizationScope();
+        const { user } = await Context.authenticate();
+
+        if (!await Context.auth.canManageFinances(organization.id)) {
+            throw Context.auth.error();
+        }
+
+        const platform = await Platform.getSharedStruct();
+        const enabled = platform.config.featureFlags.includes('settlements')
+            || organization.privateMeta.featureFlags.includes('settlements');
+
+        if (!enabled) {
+            throw new SimpleError({
+                code: 'not_available',
+                message: 'Settlements are not enabled for this organization',
+                statusCode: 400,
+            });
+        }
+
+        return { organization, user, platform };
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const { organization, user, platform } = await SettlementsExportEndpoint.authenticate();
+
+        const { start, end, provider } = request.body;
+
+        if (end.getTime() < start.getTime()) {
+            throw new SimpleError({
+                code: 'invalid_range',
+                message: 'The export ends before it starts',
+                statusCode: 400,
+            });
+        }
+
+        if (end.getTime() - start.getTime() > MAXIMUM_RANGE_MS) {
+            throw new SimpleError({
+                code: 'range_too_large',
+                message: 'The requested export range is too large',
+                statusCode: 400,
+            });
+        }
+
+        // The membership organization sells the platform's fee invoices
+        const membershipOrganization = platform.membershipOrganizationId ? await Organization.getByID(platform.membershipOrganizationId) : null;
+        if (!membershipOrganization) {
+            throw new SimpleError({
+                code: 'missing_membership_organization',
+                message: 'Platform has no membership organization configured',
+                statusCode: 400,
+            });
+        }
+
+        // Serialized so concurrent exports can't compete for memory; the result arrives by email
+        QueueHandler.schedule('settlements-export', async () => {
+            const exporter = new SettlementExporter({
+                start,
+                end,
+                provider,
+                organization,
+                sellingOrganization: membershipOrganization,
+            });
+
+            await exporter.sendEmail({
+                to: [{ email: user.email, name: user.name }],
+            });
+        }).catch((e) => {
+            // The request already returned: without this the export just never arrives
+            console.error('Settlements export failed', e);
+
+            Email.send({
+                from: Email.getWebmasterFromEmail(),
+                to: [{ email: user.email, name: user.name }],
+                subject: 'Uitbetalingen export mislukt',
+                text: 'Het maken van de export van ' + Formatter.dateTime(start) + ' tot ' + Formatter.dateTime(end) + ' is mislukt. Probeer een kortere periode of neem contact op.\n',
+                type: 'transactional',
+            });
+        });
+
+        return new Response(undefined);
+    }
+}

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

@@ -0,0 +1,110 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import type { Organization, Token, User } from '@stamhoofd/models';
+import { OrganizationFactory, Payment, Token as TokenModel, UserFactory } from '@stamhoofd/models';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+
+import { StripeMocker } from '../../../../../tests/helpers/StripeMocker.js';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
+import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
+import { GetSettlementsSyncStatusEndpoint } from './GetSettlementsSyncStatusEndpoint.js';
+import { SettlementsSyncEndpoint } from './SettlementsSyncEndpoint.js';
+
+describe('Endpoint.SettlementsSync', () => {
+    const endpoint = new SettlementsSyncEndpoint();
+    const statusEndpoint = new GetSettlementsSyncStatusEndpoint();
+    const stripeMocker = new StripeMocker();
+
+    let membershipOrganization: Organization;
+    let admin: User;
+    let adminToken: Token;
+
+    beforeAll(async () => {
+        membershipOrganization = await initMembershipOrganization();
+        ({ admin, adminToken } = await initPlatformAdmin());
+        stripeMocker.start();
+    });
+
+    afterAll(() => {
+        stripeMocker.stop();
+    });
+
+    beforeEach(() => {
+        stripeMocker.clear();
+    });
+
+    const post = async (organization: Organization, token: Token, body: Record<string, unknown> = {}) => {
+        const request = Request.buildJson('POST', '/settlements/sync', organization.getApiHost(), {
+            start: new Date(2026, 0, 1).getTime(),
+            end: new Date(2026, 0, 31).getTime(),
+            providers: [PaymentProvider.Stripe],
+            ...body,
+        });
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(endpoint, request);
+    };
+
+    const getStatus = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('GET', '/settlements/sync/status', organization.getApiHost());
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(statusEndpoint, request);
+    };
+
+    test('A platform admin can run the sync, which stores the payouts', async () => {
+        // A payment on our own platform account: a connected organization's payment only passes
+        // through our balance and is settled by its own payout
+        const payment = new Payment();
+        payment.organizationId = membershipOrganization.id;
+        payment.method = PaymentMethod.Bancontact;
+        payment.provider = PaymentProvider.Stripe;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = 100_00_00;
+        payment.paidAt = new Date(2026, 0, 15);
+        await payment.save();
+
+        const payout = stripeMocker.createPayout({ amount: 10000, arrivalDate: new Date(2026, 0, 20) });
+        stripeMocker.createBalanceTransaction({
+            type: 'charge',
+            amount: 10000,
+            created: new Date(2026, 0, 15),
+            payout: payout.id,
+            source: stripeMocker.createChargeObject({ metadata: { payment: payment.id } }),
+        });
+
+        const response = await post(membershipOrganization, adminToken);
+        expect(response.status).toBe(200);
+
+        await QueueHandler.awaitAll();
+
+        const settlement = await Settlement.select().where('externalId', payout.id).first(true);
+        expect(settlement.syncedAt).not.toBeNull();
+        expect(settlement.unexplainedAmount).toBe(0);
+
+        // The queue is empty again
+        const statusResponse = await getStatus(membershipOrganization, adminToken);
+        expect(statusResponse.body).toEqual([]);
+    });
+
+    test('A user without platform full access cannot run the sync', 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' }),
+        );
+        await expect(getStatus(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+    });
+
+    test('The sync is not available for other organizations', async () => {
+        const otherOrganization = await new OrganizationFactory({}).create();
+
+        await expect(post(otherOrganization, adminToken)).rejects.toThrow(
+            STExpect.simpleError({ code: 'not_available' }),
+        );
+    });
+});