@stamhoofd/backend 2.140.0 → 2.141.0

package/src/helpers/SettlementSyncRunner.test.ts

@@ -0,0 +1,165 @@
+import type { Organization } from '@stamhoofd/models';
+import { MolliePayment, OrganizationFactory, Payment } from '@stamhoofd/models';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
+import { v4 as uuidv4 } from 'uuid';
+import { vi } from 'vitest';
+
+import type { MollieMockPayment } from '../../tests/helpers/MollieMocker.js';
+import { MollieMocker } from '../../tests/helpers/MollieMocker.js';
+import { StripeMocker } from '../../tests/helpers/StripeMocker.js';
+import { initMembershipOrganization } from '../../tests/init/initMembershipOrganization.js';
+import { SettlementService } from '../services/SettlementService.js';
+import { SettlementSyncRunner } from './SettlementSyncRunner.js';
+import { StripeSettlementSyncRunner } from './StripeSettlementSyncRunner.js';
+
+describe('Helper.SettlementSyncRunner', () => {
+    const stripeMocker = new StripeMocker();
+    const mollieMocker = new MollieMocker();
+
+    beforeAll(async () => {
+        await initMembershipOrganization();
+        stripeMocker.start();
+        mollieMocker.start();
+    });
+
+    afterAll(() => {
+        // Both mockers are nock-based and stop() clears every interceptor, so stopping one is
+        // stopping both
+        stripeMocker.stop();
+    });
+
+    const createStripePayment = async (organization: Organization) => {
+        const payment = new Payment();
+        payment.organizationId = organization.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();
+        return payment;
+    };
+
+    const createMolliePayment = async (organization: Organization) => {
+        const payment = new Payment();
+        payment.organizationId = organization.id;
+        payment.method = PaymentMethod.Bancontact;
+        payment.provider = PaymentProvider.Mollie;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = 50_0000;
+        payment.paidAt = new Date(2026, 0, 15);
+        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 link = new MolliePayment();
+        link.paymentId = payment.id;
+        link.mollieId = mockPayment.id;
+        await link.save();
+
+        return { payment, mockPayment };
+    };
+
+    test('One run syncs the settlements of both providers', async () => {
+        // Stripe: a payment settled in a platform payout
+        const organization = await new OrganizationFactory({}).create();
+        const stripePayment = await createStripePayment(organization);
+
+        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: stripePayment.id } }),
+        });
+
+        // Mollie: a payment settled in a settlement of an organization token
+        const mollieOrganization = await new OrganizationFactory({}).create();
+        await mollieMocker.setupToken(mollieOrganization);
+        const { mockPayment } = await createMolliePayment(mollieOrganization);
+        const mollieSettlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            value: '50.00',
+            settledAt: new Date(2026, 0, 20),
+        });
+
+        const runner = new SettlementSyncRunner();
+        const summary = await runner.run({
+            start: new Date(2026, 0, 1),
+            end: new Date(2026, 0, 31),
+            providers: [PaymentProvider.Stripe, PaymentProvider.Mollie],
+        });
+
+        const stripeRow = await Settlement.select().where('externalId', payout.id).first(true);
+        expect(stripeRow.syncedAt).not.toBeNull();
+
+        const mollieRow = await Settlement.select().where('externalId', mollieSettlement.id).first(true);
+        expect(mollieRow.syncedAt).not.toBeNull();
+
+        expect(summary.synced).toBeGreaterThanOrEqual(2);
+    });
+
+    test('A hard Stripe failure does not block the Mollie walk', async () => {
+        const mollieOrganization = await new OrganizationFactory({}).create();
+        await mollieMocker.setupToken(mollieOrganization);
+        const { mockPayment } = await createMolliePayment(mollieOrganization);
+        const mollieSettlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            value: '50.00',
+            settledAt: new Date(2026, 0, 20),
+        });
+
+        const spy = vi.spyOn(StripeSettlementSyncRunner.prototype, 'run').mockRejectedValue(new Error('Stripe is down'));
+        try {
+            const summary = await new SettlementSyncRunner().run({
+                start: new Date(2026, 0, 1),
+                end: new Date(2026, 0, 31),
+                providers: [PaymentProvider.Stripe, PaymentProvider.Mollie],
+            });
+            expect(spy).toHaveBeenCalled();
+            expect(summary.failed).toBeGreaterThanOrEqual(1);
+        } finally {
+            spy.mockRestore();
+        }
+
+        const mollieRow = await Settlement.select().where('externalId', mollieSettlement.id).first(true);
+        expect(mollieRow.syncedAt).not.toBeNull();
+    });
+
+    test('The stripe retryUnsynced option flows through the run', async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const settlement = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Stripe,
+            externalId: 'po_' + uuidv4(),
+            organizationId: organization.id,
+            amount: 100_00_00,
+            settledAt: new Date(1991, 0, 5),
+        });
+
+        await new SettlementSyncRunner().run({
+            start: new Date(2026, 0, 1),
+            end: new Date(2026, 0, 31),
+            providers: [PaymentProvider.Stripe],
+            stripe: { retryUnsynced: true },
+        });
+
+        // The mocker has no payout with this id: the failed retry is counted on the settlement
+        const fresh = await Settlement.getByID(settlement.id);
+        expect(fresh!.syncFailureCount).toBe(1);
+        expect(fresh!.syncedAt).toBeNull();
+    });
+});

package/src/helpers/SettlementSyncRunner.ts

@@ -0,0 +1,64 @@
+import { PaymentProvider } from '@stamhoofd/structures';
+
+import { MollieSettlementSyncRunner } from './MollieSettlementSyncRunner.js';
+import type { SettlementSyncSummary } from './ProviderSettlementSyncRunner.js';
+import type { StripeSyncOptions } from './StripeSettlementSyncRunner.js';
+import { StripeSettlementSyncRunner } from './StripeSettlementSyncRunner.js';
+import { WebmasterReport } from './WebmasterReport.js';
+
+/**
+ * Runs a full settlement sync over a period by wiring up one runner per provider, all sharing one
+ * summary, one progress callback and one problem report. Provider-specific configuration is opaque
+ * here: the `stripe` options go to the StripeSettlementSyncRunner constructor verbatim; Mollie
+ * needs none. Everything is an upsert, so re-running (the nightly cron and a manual backfill) is
+ * cheap.
+ */
+export class SettlementSyncRunner {
+    /**
+     * Called after every processed unit of work, to report progress.
+     */
+    callback: ((summary: SettlementSyncSummary) => void) | null = null;
+
+    async run({ start = new Date(2025, 0, 1), end, providers, stripe }: {
+        start?: Date;
+        end?: Date | null;
+        providers?: PaymentProvider[] | null;
+        stripe?: StripeSyncOptions;
+    } = {}): Promise<SettlementSyncSummary> {
+        const summary: SettlementSyncSummary = { feeMonths: 0, failedFeeMonths: 0, synced: 0, skipped: 0, failed: 0 };
+        const rangeEnd = end ?? new Date();
+        const onProgress = () => this.callback?.(summary);
+
+        const includeStripe = !providers || providers.includes(PaymentProvider.Stripe);
+        const includeMollie = !providers || providers.includes(PaymentProvider.Mollie);
+
+        // A single cause (a first sync, a bug) fails every payout it touches: report all of them in
+        // one email instead of one per payout
+        return await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            // One provider's outage must not starve the others (or the caller's follow-up
+            // reporting): unsynced settlements stay behind with syncedAt null, so the next run picks
+            // them up
+            if (includeStripe && STAMHOOFD.STRIPE_SECRET_KEY) {
+                const runner = new StripeSettlementSyncRunner({ secretKey: STAMHOOFD.STRIPE_SECRET_KEY, ...stripe });
+                try {
+                    await runner.run({ start, end: rangeEnd, summary, onProgress });
+                } catch (e) {
+                    console.error('Stripe settlement sync failed', e);
+                    summary.failed += 1;
+                }
+            }
+
+            if (includeMollie) {
+                const runner = new MollieSettlementSyncRunner();
+                try {
+                    await runner.run({ start, end: rangeEnd, summary, onProgress });
+                } catch (e) {
+                    console.error('Mollie settlement sync failed', e);
+                    summary.failed += 1;
+                }
+            }
+
+            return summary;
+        });
+    }
+}

package/src/helpers/StripeHelper.ts

@@ -38,7 +38,8 @@ export class StripeHelper {
                 // This is a direct charge
 
                 if (charge.balance_transaction !== null && typeof charge.balance_transaction !== 'string') {
-                    const fees = charge.balance_transaction.fee;
+                    // Stripe counts in cents, we count in 1/10000
+                    const fees = charge.balance_transaction.fee * 100;
                     payment.transferFee = fees - payment.serviceFeePayout;
                 }
             }