@stamhoofd/backend 2.130.0 → 2.132.0

package/src/endpoints/global/registration/RegisterMembersEndpoint.ts

@@ -5,7 +5,7 @@ import { Endpoint, Response } from '@simonbackx/simple-endpoints';
 import { SimpleError } from '@simonbackx/simple-errors';
 import { Email } from '@stamhoofd/email';
 import type { MemberWithUsersRegistrationsAndGroups, Organization, Payment } from '@stamhoofd/models';
-import { BalanceItem, CachedBalance, Group, Member, Platform, RateLimiter, Registration } from '@stamhoofd/models';
+import { BalanceItem, CachedBalance, Group, Member, Platform, RateLimiter, Registration, RegistrationPeriod } from '@stamhoofd/models';
 import type { BalanceItem as BalanceItemStruct, PlatformMember, RegisterItem } from '@stamhoofd/structures';
 import { BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, IDRegisterCheckout, Payment as PaymentStruct, PermissionLevel, PlatformFamily, ReceivableBalanceType, RegisterResponse, TranslatedString } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
@@ -516,7 +516,26 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             deactivatedRegistrationGroupIds.push(existingRegistration.groupId);
         }
 
-        async function createBalanceItem({ registration, skipZero, amount, unitPrice, description, type, relations }: { amount?: number; skipZero?: boolean; registration: { id: string; payingOrganizationId: string | null; memberId: string; trialUntil: Date | null }; unitPrice: number; description: string; relations: Map<BalanceItemRelationType, BalanceItemRelation>; type: BalanceItemType }) {
+        // Cache the registration period relation per periodId, so we only load each period once.
+        const periodRelationCache = new Map<string, BalanceItemRelation | null>();
+        async function getPeriodRelation(periodId: string): Promise<BalanceItemRelation | null> {
+            if (periodRelationCache.has(periodId)) {
+                return periodRelationCache.get(periodId)!;
+            }
+
+            const period = await RegistrationPeriod.getByID(periodId);
+            const relation = period
+                ? BalanceItemRelation.create({
+                        id: period.id,
+                        name: new TranslatedString(period.getBaseStructure().name),
+                    })
+                : null;
+
+            periodRelationCache.set(periodId, relation);
+            return relation;
+        }
+
+        async function createBalanceItem({ registration, periodId, skipZero, amount, unitPrice, description, type, relations }: { amount?: number; skipZero?: boolean; registration: { id: string; payingOrganizationId: string | null; memberId: string; trialUntil: Date | null }; periodId: string; unitPrice: number; description: string; relations: Map<BalanceItemRelationType, BalanceItemRelation>; type: BalanceItemType }) {
             // NOTE: We also need to save zero-price balance items because for online payments, we need to know which registrations to activate after payment
             if (skipZero === true) {
                 if (unitPrice === 0 || amount === 0) {
@@ -524,6 +543,12 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
                 }
             }
 
+            // Add the registration period (working year) relation so it is visible in the item description.
+            const periodRelation = await getPeriodRelation(periodId);
+            if (periodRelation) {
+                relations.set(BalanceItemRelationType.RegistrationPeriod, periodRelation);
+            }
+
             // Create balance item
             const balanceItem = new BalanceItem();
             balanceItem.registrationId = registration.id;
@@ -608,6 +633,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             // Base price
             await createBalanceItem({
                 registration,
+                periodId: item.group.periodId,
                 unitPrice: item.groupPrice.price.forMember(item.member),
                 type: BalanceItemType.Registration,
                 skipZero: false, // Always create at least one balance item for each registration - even when the price is zero
@@ -621,6 +647,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             for (const option of item.options) {
                 await createBalanceItem({
                     registration,
+                    periodId: item.group.periodId,
                     amount: option.amount,
                     unitPrice: option.option.price.forMember(item.member),
                     skipZero: true, // Do not create for zero option prices
@@ -654,6 +681,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
                     // Base price
                     await createBalanceItem({
                         registration,
+                        periodId: item.group.periodId,
                         unitPrice: -discountValue,
                         type: BalanceItemType.RegistrationBundleDiscount,
                         description: discount.name,
@@ -722,6 +750,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
 
                 await createBalanceItem({
                     registration: registration.registration,
+                    periodId: registration.group.periodId,
                     unitPrice: -difference,
                     type: BalanceItemType.RegistrationBundleDiscount,
                     description: discount.name,

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/endpoints/organization/dashboard/stripe/GetStripePayoutsExportStatusEndpoint.ts

@@ -0,0 +1,32 @@
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+
+import { PayoutExportStatus, StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
+
+type Params = Record<string, never>;
+type Body = undefined;
+type Query = undefined;
+type ResponseBody = PayoutExportStatus[];
+
+export class GetStripePayoutsExportStatusEndpoint 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', {});
+
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(_: DecodedRequest<Params, Query, Body>) {
+        await StripePayoutsExportEndpoint.authenticate();
+
+        return new Response(StripePayoutsExportEndpoint.queue.map((item) => {
+            return PayoutExportStatus.create(item);
+        }));
+    }
+}

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.test.ts

@@ -0,0 +1,103 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import { EmailMocker } from '@stamhoofd/email';
+import type { Organization, Token, User } from '@stamhoofd/models';
+import { OrganizationFactory, UserFactory } from '@stamhoofd/models';
+import { Token as TokenModel } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { Company } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+import nock from 'nock';
+
+import { resetNock } from '../../../../../tests/helpers/resetNock.js';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
+import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
+import { GetStripePayoutsExportStatusEndpoint } from './GetStripePayoutsExportStatusEndpoint.js';
+import { StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
+
+describe('Endpoint.StripePayoutsExport', () => {
+    const endpoint = new StripePayoutsExportEndpoint();
+    const statusEndpoint = new GetStripePayoutsExportStatusEndpoint();
+
+    let membershipOrganization: Organization;
+    let admin: User;
+    let adminToken: Token;
+
+    beforeAll(async () => {
+        membershipOrganization = await initMembershipOrganization();
+        membershipOrganization.meta.companies = [
+            Company.create({
+                name: 'Platform BV',
+                companyNumber: '0700000000',
+                VATNumber: 'BE0700000000',
+            }),
+        ];
+        await membershipOrganization.save();
+
+        ({ admin, adminToken } = await initPlatformAdmin());
+    });
+
+    afterEach(() => {
+        resetNock();
+    });
+
+    const post = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('POST', '/stripe/payouts', organization.getApiHost(), {
+            start: new Date(2026, 2, 1).getTime(),
+            end: new Date(2026, 3, 1).getTime() - 1000,
+        });
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(endpoint, request);
+    };
+
+    const getStatus = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('GET', '/stripe/payouts/status', organization.getApiHost());
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(statusEndpoint, request);
+    };
+
+    test('A platform admin can export payout reports for the membership organization', async () => {
+        nock('https://api.stripe.com')
+            .get('/v1/payouts')
+            .query(true)
+            .reply(200, { object: 'list', data: [], has_more: false, url: '/v1/payouts' });
+
+        const response = await post(membershipOrganization, adminToken);
+        expect(response.status).toBe(200);
+
+        // Wait for the scheduled report to complete
+        await QueueHandler.awaitAll();
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const reportEmail = emails.find(e => e.subject.startsWith('Stripe Uitbetalingen'));
+        expect(reportEmail).toBeDefined();
+        expect(reportEmail!.attachments).toHaveLength(1);
+
+        // The report is sent to the user that requested it
+        expect(reportEmail!.to).toContain(admin.email);
+
+        // The queue is empty again
+        const statusResponse = await getStatus(membershipOrganization, adminToken);
+        expect(statusResponse.body).toEqual([]);
+    });
+
+    test('A user without platform full access cannot export payout reports', 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('Payout reports are not available for other organizations', async () => {
+        const otherOrganization = await new OrganizationFactory({}).create();
+
+        await expect(post(otherOrganization, adminToken)).rejects.toThrow(
+            STExpect.simpleError({ code: 'not_available' }),
+        );
+    });
+});

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.ts

@@ -0,0 +1,125 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { AutoEncoder, DateDecoder, field, IntegerDecoder } 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 { Platform } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+
+import { Context } from '../../../../helpers/Context.js';
+import { StripePayoutReporter } from '../../../../helpers/StripePayoutReporter.js';
+
+export class PayoutExportStatus extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+
+    @field({ decoder: DateDecoder })
+    end: Date;
+
+    @field({ decoder: IntegerDecoder })
+    count = 0;
+}
+
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+
+    @field({ decoder: DateDecoder })
+    end: Date;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+
+/**
+ * Manually build a Stripe payout report for a given period and email it (to check whether
+ * everything we charged via Stripe application fees was invoiced correctly).
+ */
+export class StripePayoutsExportEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+
+    static queue: PayoutExportStatus[] = [];
+
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+
+        const params = Endpoint.parseParameters(request.url, '/stripe/payouts', {});
+
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    static async authenticate() {
+        const organization = await Context.setOrganizationScope();
+        const { user } = await Context.authenticate();
+
+        if (!Context.auth.hasPlatformFullAccess()) {
+            throw Context.auth.error();
+        }
+
+        const platform = await Platform.getShared();
+        if (!platform.membershipOrganizationId || platform.membershipOrganizationId !== organization.id) {
+            throw new SimpleError({
+                code: 'not_available',
+                message: 'Stripe payout exports are only available for the platform membership organization',
+                statusCode: 400,
+            });
+        }
+
+        return { organization, user };
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const { organization, user } = await StripePayoutsExportEndpoint.authenticate();
+
+        if (!STAMHOOFD.STRIPE_SECRET_KEY) {
+            throw new SimpleError({
+                code: 'not_configured',
+                message: 'Stripe is not configured',
+                statusCode: 400,
+            });
+        }
+        const secretKey = STAMHOOFD.STRIPE_SECRET_KEY;
+
+        const start = request.body.start;
+        const end = request.body.end;
+
+        const item = PayoutExportStatus.create({
+            start,
+            end,
+            count: 0,
+        });
+        StripePayoutsExportEndpoint.queue.push(item);
+
+        // Schedule
+        QueueHandler.schedule('stripe-payout-export', async () => {
+            try {
+                const reporter = new StripePayoutReporter({
+                    secretKey,
+                    sellingOrganization: organization,
+                });
+                let count = 0;
+                reporter.callback = () => {
+                    count++;
+                    item.count = count;
+                };
+
+                await reporter.build(start, end);
+
+                // Send the report to the user that requested it
+                await reporter.sendEmail({
+                    to: [{ email: user.email, name: user.name }],
+                });
+            } finally {
+                // Remove from queue
+                StripePayoutsExportEndpoint.queue.splice(StripePayoutsExportEndpoint.queue.indexOf(item), 1);
+            }
+        }).catch(console.error);
+
+        return new Response(undefined);
+    }
+}

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