WIP: Handle partial expense refunds

Author: Benjamin Piouffle

config/default.json

@@ -237,8 +237,8 @@
   },
   "ledger": {
     "fastBalance": true,
-    "separatePaymentProcessorFees": false,
-    "separateTaxes": false,
+    "separatePaymentProcessorFees": true,
+    "separateTaxes": true,
     "orderedTransactions": false
   },
   "timeline": {

cron/disabled/reject-contributions.js

@@ -107,7 +107,7 @@ async function run({ dryRun, limit, force } = {}) {
             if (paymentMethodProvider.refundTransaction) {
               await refundTransaction(transaction, null, 'Contribution rejected');
             } else if (force) {
-              await createRefundTransaction(transaction, 0, null);
+              await createRefundTransaction(transaction, { refundedPaymentProcessorFeeInHostCurrency: 0 });
             } else {
               if (order.status === 'PAID' || order.status === 'CANCELLED') {
                 shouldNotifyContributor = false;

scripts/paypal/mark-double-transactions-as-refunded.ts

@@ -53,12 +53,10 @@ const main = async (): Promise<void> => {
     } else {
       await Promise.all(
         transactionsToRefund.map(async transaction => {
-          await createRefundTransaction(
-            transaction,
-            transaction.paymentProcessorFeeInHostCurrency,
-            { refundedFromDoubleTransactionsScript: true },
-            null,
-          );
+          await createRefundTransaction(transaction, {
+            refundedPaymentProcessorFeeInHostCurrency: transaction.paymentProcessorFeeInHostCurrency,
+            data: { refundedFromDoubleTransactionsScript: true },
+          });
         }),
       );
     }

server/graphql/common/expenses.ts

@@ -42,6 +42,7 @@ import { EXPENSE_PERMISSION_ERROR_CODES } from '../../constants/permissions';
 import PlatformConstants from '../../constants/platform';
 import POLICIES from '../../constants/policies';
 import { TransactionKind } from '../../constants/transaction-kind';
+import { TransactionTypes } from '../../constants/transactions';
 import { checkFeatureAccess, hasFeature } from '../../lib/allowed-features';
 import cache from '../../lib/cache';
 import { convertToCurrency, getDate, getFxRate, loadFxRatesMap } from '../../lib/currency';
@@ -3774,7 +3775,7 @@ export async function payExpense(req: express.Request, args: PayExpenseArgs): Pr
 export async function markExpenseAsUnpaid(
   req: express.Request,
   expenseId: number,
-  shouldRefundPaymentProcessorFee: boolean,
+  amountRefundedInHostCurrency?: number,
   markAsUnPaidStatus: ExpenseStatus.APPROVED | ExpenseStatus.ERROR | ExpenseStatus.INCOMPLETE = ExpenseStatus.APPROVED,
 ): Promise<Expense> {
   const newExpenseStatus = markAsUnPaidStatus || ExpenseStatus.APPROVED;
@@ -3813,22 +3814,38 @@ export async function markExpenseAsUnpaid(
         RefundTransactionId: null,
         kind: TransactionKind.EXPENSE,
         isRefund: false,
+        type: TransactionTypes.DEBIT,
       },
       include: [{ model: models.Expense }],
     });
 
-    // Load payment processor fee amount, either from the column or from the related transaction
-    let refundedPaymentProcessorFeeAmount = 0;
-    if (shouldRefundPaymentProcessorFee) {
-      refundedPaymentProcessorFeeAmount = transaction.paymentProcessorFeeInHostCurrency;
-      if (!refundedPaymentProcessorFeeAmount) {
-        refundedPaymentProcessorFeeAmount = Math.abs(
-          (await transaction.getPaymentProcessorFeeTransaction().then(t => t?.amountInHostCurrency)) || 0,
-        );
-      }
+    // Check amounts
+    const originalBaseAmountInHostCurrency = Math.abs(transaction.amountInHostCurrency || 0);
+    const originalProcessorFeeAmount =
+      transaction.paymentProcessorFeeInHostCurrency ||
+      Math.abs((await transaction.getPaymentProcessorFeeTransaction())?.amountInHostCurrency || 0);
+    const originalTotalAmountInHostCurrency = originalBaseAmountInHostCurrency + originalProcessorFeeAmount;
+
+    if (!amountRefundedInHostCurrency || amountRefundedInHostCurrency <= 0) {
+      throw new ValidationFailed('The refunded amount cannot be 0');
+    } else if (amountRefundedInHostCurrency > originalTotalAmountInHostCurrency) {
+      throw new ValidationFailed('The refunded amount cannot exceed the total amount paid');
     }
 
-    await createRefundTransaction(transaction, refundedPaymentProcessorFeeAmount, null, expense.User);
+    // If refunding more than the original gross amount, refund the difference as payment processor fee (full or partial)
+    let refundedPaymentProcessorFee = 0;
+    let baseAmountToRefund = originalBaseAmountInHostCurrency;
+    if (amountRefundedInHostCurrency >= originalBaseAmountInHostCurrency) {
+      refundedPaymentProcessorFee = amountRefundedInHostCurrency - originalBaseAmountInHostCurrency;
+    } else {
+      baseAmountToRefund = originalBaseAmountInHostCurrency - amountRefundedInHostCurrency;
+    }
+
+    await createRefundTransaction(transaction, {
+      user: expense.User,
+      refundedPaymentProcessorFeeInHostCurrency: refundedPaymentProcessorFee,
+      amountRefundedInHostCurrency: baseAmountToRefund,
+    });
 
     await expense.update({ status: newExpenseStatus, lastEditedById: remoteUser.id, PaymentMethodId: null });
     return { expense, transaction };

server/graphql/schemaV2.graphql

@@ -2657,6 +2657,11 @@ type Expense {
   """
   paidAt: DateTime
 
+  """
+  Payment information for this expense. Only available when the expense status is PAID.
+  """
+  paymentInfo: ExpensePaymentInformationField
+
   """
   Whether this expense is on hold
   """
@@ -4371,6 +4376,11 @@ type Host implements Account & AccountWithContributions & AccountWithPlatformSub
     Only return accounts that expended within this amount range
     """
     totalExpended: AmountRangeInput
+
+    """
+    Order of the results
+    """
+    orderBy: OrderByInput
   ): VendorCollection!
 
   """
@@ -5203,6 +5213,7 @@ enum OrderByFieldType {
   BALANCE
   MEMBER_COUNT
   TOTAL_CONTRIBUTED
+  TOTAL_EXPENDED
   NAME
 
   """
@@ -5687,6 +5698,7 @@ enum ActivityType {
   COLLECTIVE_EDITED
   COLLECTIVE_DELETED
   COLLECTIVE_UNHOSTED
+  COLLECTIVE_BALANCE_TRANSFERRED
   COLLECTIVE_CONVERTED_TO_ORGANIZATION
   ORGANIZATION_COLLECTIVE_CREATED
   ORGANIZATION_CONVERTED_TO_COLLECTIVE
@@ -6148,6 +6160,16 @@ type PayoutMethod {
   Whether this payout method can be archived
   """
   canBeArchived: Boolean
+
+  """
+  The date and time this payout method was created
+  """
+  createdAt: DateTime!
+
+  """
+  The date and time this payout method was updated
+  """
+  updatedAt: DateTime!
 }
 
 """
@@ -6156,6 +6178,16 @@ PaymentMethod model
 type PaymentMethod {
   id: String
   legacyId: Int
+
+  """
+  The date and time this payout method was created
+  """
+  createdAt: DateTime!
+
+  """
+  The date and time this payout method was updated
+  """
+  updatedAt: DateTime!
   name: String
   service: PaymentMethodService
   type: PaymentMethodType
@@ -6178,7 +6210,6 @@ type PaymentMethod {
   data: JSON
   limitedToHosts: [Host]
   expiryDate: DateTime
-  createdAt: DateTime
 
   """
   For monthly gift cards, this field will return the monthly limit
@@ -8654,6 +8685,16 @@ enum ExpenseStatus {
   INVITE_DECLINED
 }
 
+"""
+Payment information for a paid expense
+"""
+type ExpensePaymentInformationField {
+  """
+  The payment processor fee for this expense (in host currency)
+  """
+  processorFee: Amount
+}
+
 """
 Fields for an expense's attached file
 """
@@ -19604,6 +19645,7 @@ enum ActivityAndClassesType {
   COLLECTIVE_EDITED
   COLLECTIVE_DELETED
   COLLECTIVE_UNHOSTED
+  COLLECTIVE_BALANCE_TRANSFERRED
   COLLECTIVE_CONVERTED_TO_ORGANIZATION
   ORGANIZATION_COLLECTIVE_CREATED
   ORGANIZATION_CONVERTED_TO_COLLECTIVE
@@ -24098,6 +24140,16 @@ type Mutation {
   Remove the given payout method. Scope: "expenses".
   """
   removePayoutMethod(payoutMethodId: String!): PayoutMethod!
+
+  """
+  Restore the given payout method. Scope: "expenses".
+  """
+  restorePayoutMethod(
+    """
+    Payout Method reference
+    """
+    payoutMethod: PayoutMethodReferenceInput!
+  ): PayoutMethod! @deprecated(reason: "2025-02-10: Payout methods cannot be restored.")
   editPayoutMethod(
     """
     Payout Method reference
@@ -25981,6 +26033,11 @@ input ProcessExpensePaymentParams {
   """
   shouldRefundPaymentProcessorFee: Boolean
 
+  """
+  Amount refunded when triggering MARK_AS_UNPAID. Must be > 0 and <= total amount paid. If omitted, full refund is performed. The difference (total paid - refunded) is recorded as payment processor fee.
+  """
+  amountRefunded: AmountInput
+
   """
   New expense status when triggering MARK_AS_UNPAID
   """

server/graphql/v2/mutation/ExpenseMutations.ts

@@ -65,6 +65,7 @@ import { GraphQLPaymentMethodService } from '../enum/PaymentMethodService';
 import { idDecode, IDENTIFIER_TYPES } from '../identifiers';
 import { fetchAccountingCategoryWithReference } from '../input/AccountingCategoryInput';
 import { fetchAccountWithReference, GraphQLAccountReferenceInput } from '../input/AccountReferenceInput';
+import { getValueInCentsFromAmountInput, GraphQLAmountInput } from '../input/AmountInput';
 import { GraphQLExpenseCreateInput } from '../input/ExpenseCreateInput';
 import { GraphQLExpenseInviteDraftInput } from '../input/ExpenseInviteDraftInput';
 import {
@@ -398,9 +399,10 @@ const expenseMutations = {
               type: GraphQLInt,
               description: 'The total amount paid in host currency',
             },
-            shouldRefundPaymentProcessorFee: {
-              type: GraphQLBoolean,
-              description: 'Whether the payment processor fees should be refunded when triggering MARK_AS_UNPAID',
+            amountRefunded: {
+              type: GraphQLAmountInput,
+              description:
+                'Amount refunded when triggering MARK_AS_UNPAID. Must be > 0 and <= total amount paid. If omitted, full refund is performed. The difference (total paid - refunded) is recorded as payment processor fee.',
             },
             markAsUnPaidStatus: {
               type: new GraphQLEnumType({
@@ -490,14 +492,24 @@ const expenseMutations = {
         case 'MARK_AS_SPAM':
           expense = await markExpenseAsSpam(req, expense);
           break;
-        case 'MARK_AS_UNPAID':
+        case 'MARK_AS_UNPAID': {
+          if (!args.paymentParams?.amountRefunded) {
+            throw new ValidationFailed('amountRefunded is required when triggering MARK_AS_UNPAID');
+          }
+
+          const amountRefundedInHostCurrency = getValueInCentsFromAmountInput(args.paymentParams.amountRefunded, {
+            expectedCurrency: expense.collective.host.currency,
+            allowNilCurrency: false,
+          });
+
           expense = await markExpenseAsUnpaid(
             req,
             expense.id,
-            args.paymentParams?.shouldRefundPaymentProcessorFee || args.paymentParams?.paymentProcessorFee,
+            amountRefundedInHostCurrency,
             args.paymentParams?.markAsUnPaidStatus,
           );
           break;
+        }
         case 'SCHEDULE_FOR_PAYMENT':
           expense = await scheduleExpenseForPayment(req, expense, {
             feesPayer: args.paymentParams?.feesPayer,

server/graphql/v2/object/Expense.ts

@@ -54,6 +54,7 @@ import { GraphQLActivity } from './Activity';
 import { GraphQLAmount } from './Amount';
 import GraphQLExpenseAttachedFile from './ExpenseAttachedFile';
 import GraphQLExpenseItem from './ExpenseItem';
+import { GraphQLExpensePaymentInformationField } from './ExpensePaymentInformationField';
 import GraphQLExpensePermissions from './ExpensePermissions';
 import GraphQLExpenseQuote from './ExpenseQuote';
 import { GraphQLExpenseValuesByRole } from './ExpenseValuesByRole';
@@ -302,6 +303,15 @@ export const GraphQLExpense = new GraphQLObjectType<ExpenseModel, Express.Reques
           return transaction?.clearedAt || transaction?.createdAt || null;
         },
       },
+      paymentInfo: {
+        type: GraphQLExpensePaymentInformationField,
+        description: 'Payment information for this expense. Only available when the expense status is PAID.',
+        resolve(expense) {
+          if (expense.status === expenseStatus.PAID) {
+            return expense;
+          }
+        },
+      },
       onHold: {
         type: GraphQLBoolean,
         description: 'Whether this expense is on hold',

server/graphql/v2/object/ExpensePaymentInformationField.ts

@@ -0,0 +1,44 @@
+import type Express from 'express';
+import { GraphQLObjectType } from 'graphql';
+import { find } from 'lodash';
+
+import expenseStatus from '../../../constants/expense-status';
+import { TransactionKind } from '../../../constants/transaction-kind';
+import { TransactionTypes } from '../../../constants/transactions';
+import ExpenseModel from '../../../models/Expense';
+
+import { GraphQLAmount } from './Amount';
+
+export const GraphQLExpensePaymentInformationField = new GraphQLObjectType<ExpenseModel, Express.Request>({
+  name: 'ExpensePaymentInformationField',
+  description: 'Payment information for a paid expense',
+  fields: () => ({
+    processorFee: {
+      type: GraphQLAmount,
+      description: 'The payment processor fee for this expense (in host currency)',
+      async resolve(expense, _, req) {
+        if (expense.status !== expenseStatus.PAID) {
+          return null;
+        }
+
+        const transactions = await req.loaders.Transaction.byExpenseId.load(expense.id);
+        const transaction = find(transactions, {
+          kind: TransactionKind.PAYMENT_PROCESSOR_FEE,
+          isRefund: false,
+          type: TransactionTypes.DEBIT,
+          RefundTransactionId: null,
+        });
+
+        if (!transaction) {
+          return null;
+        }
+
+        return {
+          value: Math.abs(transaction.amountInHostCurrency || 0),
+          currency: transaction.hostCurrency,
+          exchangeRate: null,
+        };
+      },
+    },
+  }),
+});