@stamhoofd/backend 2.141.0 → 2.142.0

package/src/services/ApplicationFeeService.ts

@@ -31,10 +31,11 @@ export type ApplicationFeeData = {
      */
     organizationId: string;
 
-    payingOrganizationId: string;
-    payingStripeAccountId: string;
+    payingOrganizationId?: string | null;
+    payingStripeAccountId?: string | null;
     payingPaymentId?: string | null;
-    settlementChargeId: string;
+
+    settlementChargeId?: string | null;
     settlementId?: string | null;
     occurredAt: Date;
 };
@@ -85,17 +86,28 @@ export class ApplicationFeeService {
         fee.type = data.type;
         fee.amount = data.amount;
         fee.organizationId = data.organizationId;
-        fee.payingOrganizationId = data.payingOrganizationId;
-        fee.payingStripeAccountId = data.payingStripeAccountId;
-        fee.settlementChargeId = data.settlementChargeId;
         fee.occurredAt = data.occurredAt;
 
         if (data.settlementId !== undefined) {
             fee.settlementId = data.settlementId;
         }
+
         if (data.payingPaymentId !== undefined) {
             fee.payingPaymentId = data.payingPaymentId;
         }
+
+        if (data.settlementChargeId !== undefined) {
+            fee.settlementChargeId = data.settlementChargeId;
+        }
+
+        if (data.payingOrganizationId !== undefined) {
+            fee.payingOrganizationId = data.payingOrganizationId;
+        }
+
+        if (data.payingStripeAccountId !== undefined) {
+            fee.payingStripeAccountId = data.payingStripeAccountId;
+        }
+
         await fee.save();
 
         if (fee.balanceItemId === null) {
@@ -162,7 +174,7 @@ export class ApplicationFeeService {
      * from being billed twice.
      */
     private static async linkLegacyInvoicedFee(fee: ApplicationFee) {
-        if (!fee.payingStripeAccountId) {
+        if (!fee.payingStripeAccountId || !fee.payingOrganizationId) {
             return;
         }
 
@@ -217,7 +229,9 @@ export class ApplicationFeeService {
             .where('id', balanceItemPayments.map(b => b.balanceItemId))
             .fetch();
         const balanceItemType = type === ApplicationFeeType.Service ? BalanceItemType.ServiceFee : BalanceItemType.TransferFee;
-        return balanceItems.find(item => item.type === balanceItemType) ?? null;
+
+        // In legacy migrations, the type has been set to 'Other' - fallback to that (contains both service fees and transfer fees in one balance item)
+        return balanceItems.find(item => item.type === balanceItemType) ?? (balanceItems.length === 1 ? balanceItems.find(item => item.type === BalanceItemType.Other) : null) ?? null;
     }
 
     /**
@@ -226,6 +240,10 @@ export class ApplicationFeeService {
      * no stamp: stampInvoicedPayments runs when the invoice is created later.
      */
     private static async stampProviderInvoiceId(fee: ApplicationFee, { payment }: { payment?: Payment } = {}) {
+        if (!fee.settlementChargeId) {
+            return;
+        }
+
         if (!payment) {
             if (!fee.balanceItemId) {
                 return;
@@ -275,7 +293,7 @@ export class ApplicationFeeService {
             .where('balanceItemId', balanceItemPayments.map(b => b.balanceItemId))
             .limit(FEE_BATCH_SIZE)
             .allBatched()) {
-            settlementChargeIds.push(...fees.map(fee => fee.settlementChargeId));
+            settlementChargeIds.push(...fees.map(fee => fee.settlementChargeId).filter((id): id is string => id !== null));
         }
 
         await SettlementService.setChargeProviderInvoiceIds(settlementChargeIds, invoice?.number ?? null);

package/src/services/SettlementService.test.ts

@@ -13,9 +13,11 @@ import { ReportedRows, SettlementService } from './SettlementService.js';
 
 describe('SettlementService', () => {
     let organization: Organization;
+    let stripeAccount: StripeAccount;
 
     beforeAll(async () => {
         organization = await new OrganizationFactory({}).create();
+        stripeAccount = await createStripeAccount();
     });
 
     async function createPayment(price = 50_00_00, method = PaymentMethod.Bancontact, organizationId = organization.id) {
@@ -30,25 +32,25 @@ describe('SettlementService', () => {
         return payment;
     }
 
-    async function createStripeAccount() {
-        const stripeAccount = new StripeAccount();
-        stripeAccount.organizationId = organization.id;
-        stripeAccount.accountId = 'acct_' + uuidv4();
-        await stripeAccount.save();
-        return stripeAccount;
+    async function createStripeAccount(organizationId = organization.id) {
+        const account = new StripeAccount();
+        account.organizationId = organizationId;
+        account.accountId = 'acct_' + uuidv4();
+        await account.save();
+        return account;
     }
 
     /**
      * A fee with its deduction charge, as the sync stores them.
      */
-    async function createApplicationFee({ amount = 1_00_00, type = ApplicationFeeType.Service, settlement = null as SettlementModel | null, balanceItemId = null as string | null, occurredAt = new Date(2026, 0, 14) } = {}) {
+    async function createApplicationFee({ amount = 1_00_00, type = ApplicationFeeType.Service, settlement = null as SettlementModel | null, balanceItemId = null as string | null, occurredAt = new Date(2026, 0, 14), payingOrganizationId = organization.id, payingStripeAccountId = null as string | null } = {}) {
         const externalId = 'fee_' + uuidv4();
         const charge = await SettlementService.upsertCharge({
             type: type === ApplicationFeeType.Service ? SettlementChargeType.ApplicationFeeService : SettlementChargeType.ApplicationFeeTransfer,
             externalId: externalId + ':' + type,
             amount: -amount,
             applicationFeeId: externalId,
-            organizationId: organization.id,
+            organizationId: payingOrganizationId,
             occurredAt,
         });
 
@@ -57,7 +59,8 @@ describe('SettlementService', () => {
         fee.type = type;
         fee.amount = amount;
         fee.organizationId = organization.id;
-        fee.payingOrganizationId = organization.id;
+        fee.payingOrganizationId = payingOrganizationId;
+        fee.payingStripeAccountId = payingStripeAccountId ?? stripeAccount.id;
         fee.settlementChargeId = charge.id;
         fee.settlementId = settlement?.id ?? null;
         fee.balanceItemId = balanceItemId;
@@ -66,6 +69,22 @@ describe('SettlementService', () => {
         return { fee, charge };
     }
 
+    /**
+     * A fee the invoicer will never bill: its payer is gone, so there is no payout of theirs to
+     * deduct it from either.
+     */
+    async function createUncollectibleApplicationFee({ amount = 1_00_00, settlement = null as SettlementModel | null, occurredAt = new Date(2026, 0, 14) } = {}) {
+        const fee = new ApplicationFee();
+        fee.externalId = 'fee_' + uuidv4();
+        fee.type = ApplicationFeeType.Service;
+        fee.amount = amount;
+        fee.organizationId = organization.id;
+        fee.settlementId = settlement?.id ?? null;
+        fee.occurredAt = occurredAt;
+        await fee.save();
+        return fee;
+    }
+
     /**
      * A fee payment with one balance item, like the invoicer creates.
      */
@@ -471,6 +490,60 @@ describe('SettlementService', () => {
             expect(unlinked!.pendingFees).toBe(0);
             expect(unlinked!.unexplainedAmount).toBe(1_00_00);
         });
+
+        test('fees the invoicer will never bill explain the payout without ever being invoiced', async () => {
+            const settlement = await SettlementService.upsertSettlement(settlementData({ amount: 3_00_00 }));
+            await createApplicationFee({ settlement, amount: 1_00_00 });
+            await createUncollectibleApplicationFee({ settlement, amount: 1_00_00 });
+
+            // A payer we know, but not the account the fee was deducted from: the invoicer skips it
+            const accountless = await createApplicationFee({ settlement, amount: 1_00_00 });
+            accountless.fee.payingStripeAccountId = null;
+            await accountless.fee.save();
+
+            await SettlementService.finishSync(settlement, { transactionCount: 3 });
+
+            // Only the fee that can still be billed is worth waiting for
+            expect(settlement.pendingFees).toBe(1_00_00);
+            expect(settlement.uncollectibleFees).toBe(2_00_00);
+            expect(settlement.unexplainedAmount).toBe(0);
+        });
+    });
+
+    describe('getApplicationFeeSettlementIdsForPayingOrganization', () => {
+        test('deleting the paying organization keeps its fees as uncollectible income', async () => {
+            const payer = await new OrganizationFactory({}).create();
+            const payerAccount = await createStripeAccount(payer.id);
+            const settlement = await SettlementService.upsertSettlement(settlementData({ amount: 1_00_00 }));
+            const { fee, charge } = await createApplicationFee({ settlement, amount: 1_00_00, payingOrganizationId: payer.id, payingStripeAccountId: payerAccount.id });
+
+            // An organization that took Stripe payments is the only kind that owes fees: its
+            // payments reference the account the delete has to cascade through
+            const payerPayment = await createPayment(10_00_00, PaymentMethod.Bancontact, payer.id);
+            payerPayment.stripeAccountId = payerAccount.id;
+            await payerPayment.save();
+
+            await SettlementService.finishSync(settlement, { transactionCount: 1 });
+            expect(settlement.pendingFees).toBe(1_00_00);
+
+            const settlementIds = await SettlementService.getApplicationFeeSettlementIdsForPayingOrganization(payer.id);
+            expect(settlementIds).toEqual([settlement.id]);
+
+            await payer.delete();
+            await SettlementService.refreshTotalsForIds(settlementIds);
+
+            // The deduction charge went with the organization; the fee itself is our income and stays
+            expect(await SettlementCharge.getByID(charge.id)).toBeUndefined();
+            const stored = await ApplicationFee.getByID(fee.id);
+            expect(stored).toBeDefined();
+            expect(stored!.payingOrganizationId).toBeNull();
+            expect(stored!.settlementChargeId).toBeNull();
+
+            const after = await Settlement.getByID(settlement.id);
+            expect(after!.pendingFees).toBe(0);
+            expect(after!.uncollectibleFees).toBe(1_00_00);
+            expect(after!.unexplainedAmount).toBe(0);
+        });
     });
 
     describe('updateLegacySettlementReference', () => {

package/src/services/SettlementService.ts

@@ -62,6 +62,11 @@ export type ChargeData = {
  */
 const CHARGE_UPDATE_BATCH_SIZE = 500;
 
+/**
+ * Fees read per batch when a whole organization's fees are walked.
+ */
+const FEE_BATCH_SIZE = 500;
+
 /**
  * Collects which rows the provider still reports in a settlement while a sync walks it. A stored
  * row of the settlement that is not in here after the walk has moved or disappeared at the
@@ -306,7 +311,7 @@ export class SettlementService {
      * settlement (a transaction can move to another payout). Rows that only exist because of the
      * payout are deleted; rows that outlive the payout link are only unlinked: derived fee lines
      * (owned by updatePaymentSettlementsForAccountDeductionPayment), deduction charges referenced
-     * by an application fee (RESTRICT FK), and the application fee rows themselves.
+     * by an application fee, and the application fee rows themselves.
      *
      * Returns the fees unlinked from this settlement, so the caller can refresh the derived lines
      * of their fee payments.
@@ -376,7 +381,9 @@ export class SettlementService {
      * Recomputes the cached reconciliation columns from the stored rows: `unexplainedAmount` should
      * be 0 — a non-zero value is a real question to answer — and `pendingFees` holds what is
      * received but not invoiced yet, which takes up to a month and only becomes a problem when it
-     * stays non-zero too long.
+     * stays non-zero too long. Fees the invoicer can never bill land in `uncollectibleFees`
+     * instead: they explain their part of the payout, but waiting for them to be invoiced is
+     * waiting forever.
      *
      * Every write that changes what a payout holds ends here, or the export and the problem report
      * keep reading numbers from the last sync.
@@ -405,10 +412,46 @@ export class SettlementService {
         const pendingFees = await ApplicationFee.select()
             .where('settlementId', settlement.id)
             .where('balanceItemId', null)
+            .where('payingOrganizationId', '!=', null)
+            .where('payingStripeAccountId', '!=', null)
+            .sum(SQL.column('amount')) ?? 0;
+
+        // The negation of what the invoicer bills (ApplicationFeeInvoicer#selectBillableFees), so
+        // every uninvoiced fee sits in exactly one of the two sums
+        const uncollectibleFees = await ApplicationFee.select()
+            .where('settlementId', settlement.id)
+            .where('balanceItemId', null)
+            .where(
+                SQL.where('payingOrganizationId', null)
+                    .or('payingStripeAccountId', null),
+            )
             .sum(SQL.column('amount')) ?? 0;
 
         settlement.pendingFees = pendingFees;
-        settlement.unexplainedAmount = settlement.amount - paymentSum - chargeSum - pendingFees;
+        settlement.uncollectibleFees = uncollectibleFees;
+        settlement.unexplainedAmount = settlement.amount - paymentSum - chargeSum - pendingFees - uncollectibleFees;
+    }
+
+    /**
+     * The payouts holding application fees this organization paid: after deleting it, they have to
+     * recount, because those fees moved from pending to uncollectible.
+     */
+    static async getApplicationFeeSettlementIdsForPayingOrganization(organizationId: string): Promise<string[]> {
+        // An organization has one fee row per payment per type, so they are never all loaded at
+        // once just to collect the handful of payouts behind them
+        const settlementIds = new Set<string>();
+
+        for await (const fees of ApplicationFee.select()
+            .where('payingOrganizationId', organizationId)
+            .where('settlementId', '!=', null)
+            .limit(FEE_BATCH_SIZE)
+            .allBatched()) {
+            for (const fee of fees) {
+                settlementIds.add(fee.settlementId!);
+            }
+        }
+
+        return [...settlementIds];
     }
 
     /**