@oneuptime/common 13.0.4 → 13.0.6

package/Server/API/BillingInvoiceAPI.ts

@@ -3,8 +3,12 @@ import UserMiddleware from "../Middleware/UserAuthorization";
 import BillingInvoiceService, {
   Service as BillingInvoiceServiceType,
 } from "../Services/BillingInvoiceService";
-import BillingService, { Invoice } from "../Services/BillingService";
+import BillingService, {
+  Invoice,
+  PaymentIntentState,
+} from "../Services/BillingService";
 import ProjectService from "../Services/ProjectService";
+import logger, { LogAttributes } from "../Utils/Logger";
 import {
   ExpressRequest,
   ExpressResponse,
@@ -16,12 +20,113 @@ import BaseAPI from "./BaseAPI";
 import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import BadDataException from "../../Types/Exception/BadDataException";
 import { JSONObject } from "../../Types/JSON";
+import ObjectID from "../../Types/ObjectID";
 import Permission, { UserPermission } from "../../Types/Permission";
 import BillingInvoice, {
   InvoiceStatus,
 } from "../../Models/DatabaseModels/BillingInvoice";
 import Project from "../../Models/DatabaseModels/Project";
 
+/*
+ * What the customer should see after a pay attempt, once Stripe's view of the
+ * invoice has been read back.
+ */
+type PayInvoiceOutcome =
+  | { kind: "paid"; status: InvoiceStatus }
+  | { kind: "processing" }
+  | { kind: "requiresAction"; clientSecret: string };
+
+/*
+ * The only PaymentIntent states the browser can move forward: a 3-D Secure or
+ * bank authentication prompt, or a confirmation Stripe.js has to send. Handing
+ * out the client secret of a PaymentIntent in any other state only gets the
+ * customer an opaque Stripe.js error.
+ */
+const PAYMENT_INTENT_STATUSES_NEEDING_CUSTOMER: Array<
+  PaymentIntentState["status"]
+> = ["requires_action", "requires_confirmation"];
+
+/*
+ * Stripe's refusal of invoices.pay while an earlier debit has not cleared
+ * ("Invoices with pending payments waiting to clear cannot be paid, ..."). It
+ * arrives as a plain invalid_request_error with no dedicated code, so the
+ * message is the only signal.
+ */
+const PENDING_PAYMENT_REFUSAL: RegExp = /pending payments? waiting to clear/i;
+
+const ENDS_WITH_PUNCTUATION: RegExp = /[.!?]$/;
+
+interface PaymentProviderError {
+  type: string;
+  code?: string | undefined;
+  message?: string | undefined;
+}
+
+type IsPaymentProviderErrorFunction = (
+  err: unknown,
+) => err is PaymentProviderError;
+
+// Stripe SDK errors carry a type such as StripeCardError.
+const isPaymentProviderError: IsPaymentProviderErrorFunction = (
+  err: unknown,
+): err is PaymentProviderError => {
+  const type: unknown = (err as { type?: unknown } | null)?.type;
+
+  return typeof type === "string" && type.startsWith("Stripe");
+};
+
+type IsPendingPaymentRefusalFunction = (err: unknown) => boolean;
+
+const isPendingPaymentRefusal: IsPendingPaymentRefusalFunction = (
+  err: unknown,
+): boolean => {
+  return (
+    isPaymentProviderError(err) &&
+    PENDING_PAYMENT_REFUSAL.test(err.message || "")
+  );
+};
+
+interface ToPayInvoiceErrorData {
+  paymentError: unknown;
+  paymentIntent?: PaymentIntentState | null | undefined;
+  suggestNewPaymentMethod?: boolean | undefined;
+}
+
+type ToPayInvoiceErrorFunction = (data: ToPayInvoiceErrorData) => unknown;
+
+/*
+ * A raw StripeError reaching the error handler becomes an opaque 500
+ * "Server Error", so provider errors are turned into a message the customer
+ * can act on. Anything that is not a provider error is already one of ours
+ * (no payment method, provider unreachable) and is passed through untouched.
+ */
+const toPayInvoiceError: ToPayInvoiceErrorFunction = (
+  data: ToPayInvoiceErrorData,
+): unknown => {
+  if (!isPaymentProviderError(data.paymentError)) {
+    return data.paymentError;
+  }
+
+  const providerMessage: string =
+    (
+      data.paymentError.message ||
+      data.paymentIntent?.lastPaymentErrorMessage ||
+      ""
+    ).trim() || "The payment provider did not accept this payment.";
+
+  if (!data.suggestNewPaymentMethod) {
+    return new BadDataException(providerMessage);
+  }
+
+  const sentence: string = ENDS_WITH_PUNCTUATION.test(providerMessage)
+    ? providerMessage
+    : `${providerMessage}.`;
+
+  return new BadDataException(
+    `Your payment could not be completed: ${sentence} Please update your payment method in Project Settings > Billing and try again.`,
+  );
+};
+
 export default class UserAPI extends BaseAPI<
   BillingInvoice,
   BillingInvoiceServiceType
@@ -144,37 +249,56 @@ export default class UserAPI extends BaseAPI<
             throw new BadDataException("Invoice not found for this project");
           }
 
-          let invoice: Invoice | null = null;
+          const customerId: string = project.paymentProviderCustomerId;
+          const invoiceId: string = item.paymentProviderInvoiceId;
+
+          let outcome: PayInvoiceOutcome;
 
           try {
-            invoice = await BillingService.payInvoice(
-              project.paymentProviderCustomerId,
-              item.paymentProviderInvoiceId,
+            /*
+             * The cardholder is on the other end of this request, so a card
+             * that asks for authentication is answered with the client secret
+             * below rather than by quietly charging one of their other cards.
+             */
+            const invoice: Invoice = await BillingService.payInvoice(
+              customerId,
+              invoiceId,
+              { canSurfaceAuthenticationPrompt: true },
             );
+
+            outcome = await this.getOutcomeOfSuccessfulPayment({
+              customerId: customerId,
+              invoice: invoice,
+            });
           } catch (err) {
-            invoice = await BillingService.getInvoice(
-              project.paymentProviderCustomerId,
-              item.paymentProviderInvoiceId,
-            );
+            outcome = await this.getOutcomeOfFailedPayment({
+              customerId: customerId,
+              invoiceId: invoiceId,
+              paymentError: err,
+            });
+          }
 
-            // check if this invoice needs more authentication like 3ds secure.
-            if (
-              invoice.status === InvoiceStatus.Open &&
-              invoice.paymentIntentId
-            ) {
-              const paymentIntentId: string = invoice.paymentIntentId;
+          if (outcome.kind === "processing") {
+            /*
+             * The bank already has a payment for this invoice. Charging again
+             * is either refused by Stripe or takes the money twice once the
+             * first debit clears, so the browser is only told to wait.
+             */
+            await this.moveAutopayToCustomerDefault({
+              customerId: customerId,
+              projectId: project.id!,
+            });
 
-              const clientSecret: string =
-                await BillingService.getPaymentIntentClientSecret(
-                  paymentIntentId,
-                );
+            return Response.sendJsonObjectResponse(req, res, {
+              paymentProcessing: true,
+            });
+          }
 
-              return Response.sendJsonObjectResponse(req, res, {
-                clientSecret: clientSecret,
-              });
-            }
-            // otherwise we have no idea what went wrong and throw an error.
-            throw err;
+          if (outcome.kind === "requiresAction") {
+            // 3-D Secure or a bank prompt the cardholder finishes in the browser.
+            return Response.sendJsonObjectResponse(req, res, {
+              clientSecret: outcome.clientSecret,
+            });
           }
 
           // save updated status.
@@ -182,20 +306,33 @@ export default class UserAPI extends BaseAPI<
           await this.service.updateOneBy({
             query: {
               projectId: project.id!,
-              paymentProviderInvoiceId: invoice.id!,
+              paymentProviderInvoiceId: invoiceId,
             },
             props: {
               isRoot: true,
               ignoreHooks: true,
             },
             data: {
-              status: invoice.status as InvoiceStatus,
+              status: outcome.status,
             },
           });
 
-          await BillingInvoiceService.refreshSubscriptionStatus({
-            projectId: project.id!,
-          });
+          try {
+            await BillingInvoiceService.refreshSubscriptionStatus({
+              projectId: project.id!,
+            });
+          } finally {
+            /*
+             * After the refresh: reactivating a subscription recreates it, and
+             * the new one must not keep a stale pinned card either.
+             */
+            if (outcome.status === InvoiceStatus.Paid) {
+              await this.moveAutopayToCustomerDefault({
+                customerId: customerId,
+                projectId: project.id!,
+              });
+            }
+          }
 
           return Response.sendEmptySuccessResponse(req, res);
         } catch (err) {
@@ -204,4 +341,180 @@ export default class UserAPI extends BaseAPI<
       },
     );
   }
+
+  /*
+   * invoices.pay resolving does not always mean the money arrived. A card
+   * debit the bank confirms later (India e-mandate cards sit in "processing"
+   * for about a day) comes back as a still-open invoice, and reporting that as
+   * paid invites the customer to pay again once the page reloads.
+   */
+  private async getOutcomeOfSuccessfulPayment(data: {
+    customerId: string;
+    invoice: Invoice;
+  }): Promise<PayInvoiceOutcome> {
+    const settledOutcome: PayInvoiceOutcome = {
+      kind: "paid",
+      status: data.invoice.status as InvoiceStatus,
+    };
+
+    if (data.invoice.status !== InvoiceStatus.Open) {
+      return settledOutcome;
+    }
+
+    try {
+      // payInvoice does not return the PaymentIntent, so read the invoice again.
+      const invoice: Invoice = await BillingService.getInvoice(
+        data.customerId,
+        data.invoice.id,
+      );
+
+      if (!invoice.paymentIntentId) {
+        return settledOutcome;
+      }
+
+      const paymentIntent: PaymentIntentState =
+        await BillingService.getPaymentIntent(invoice.paymentIntentId);
+
+      if (paymentIntent.status === "processing") {
+        return { kind: "processing" };
+      }
+
+      if (
+        PAYMENT_INTENT_STATUSES_NEEDING_CUSTOMER.includes(
+          paymentIntent.status,
+        ) &&
+        paymentIntent.clientSecret
+      ) {
+        return {
+          kind: "requiresAction",
+          clientSecret: paymentIntent.clientSecret,
+        };
+      }
+    } catch (err) {
+      /*
+       * Stripe accepted the payment. Failing the request because a follow-up
+       * read failed would tell the customer the payment failed when it did not.
+       */
+      logger.error(err, {
+        paymentProviderInvoiceId: data.invoice.id,
+      } as LogAttributes);
+    }
+
+    return settledOutcome;
+  }
+
+  /*
+   * A failed invoices.pay call says little on its own: the same 400 can mean
+   * "declined", "a payment is already on its way" or "this invoice cannot be
+   * paid any more". Stripe's view of the invoice and its PaymentIntent is read
+   * back before deciding what the customer sees, instead of handing the
+   * browser a client secret for whatever state the PaymentIntent is in.
+   */
+  private async getOutcomeOfFailedPayment(data: {
+    customerId: string;
+    invoiceId: string;
+    paymentError: unknown;
+  }): Promise<PayInvoiceOutcome> {
+    let invoice: Invoice;
+
+    try {
+      invoice = await BillingService.getInvoice(
+        data.customerId,
+        data.invoiceId,
+      );
+    } catch (lookupError) {
+      logger.error(lookupError, {
+        paymentProviderInvoiceId: data.invoiceId,
+      } as LogAttributes);
+
+      // The payment error is the one the customer needs to hear about.
+      throw toPayInvoiceError({ paymentError: data.paymentError });
+    }
+
+    // Paid between the page loading and the click, or by the attempt itself.
+    if (invoice.status === InvoiceStatus.Paid) {
+      return { kind: "paid", status: InvoiceStatus.Paid };
+    }
+
+    if (invoice.status !== InvoiceStatus.Open) {
+      // void, uncollectible, draft: nothing to confirm and nothing to wait for.
+      throw toPayInvoiceError({ paymentError: data.paymentError });
+    }
+
+    let paymentIntent: PaymentIntentState | null = null;
+
+    if (invoice.paymentIntentId) {
+      try {
+        paymentIntent = await BillingService.getPaymentIntent(
+          invoice.paymentIntentId,
+        );
+      } catch (lookupError) {
+        logger.error(lookupError, {
+          paymentProviderInvoiceId: data.invoiceId,
+        } as LogAttributes);
+      }
+    }
+
+    if (paymentIntent?.status === "processing") {
+      return { kind: "processing" };
+    }
+
+    if (
+      paymentIntent &&
+      PAYMENT_INTENT_STATUSES_NEEDING_CUSTOMER.includes(paymentIntent.status)
+    ) {
+      if (!paymentIntent.clientSecret) {
+        throw new BadDataException(
+          "This payment needs to be confirmed with your bank, but the payment provider did not return the details needed to do that. Please try again later.",
+        );
+      }
+
+      return {
+        kind: "requiresAction",
+        clientSecret: paymentIntent.clientSecret,
+      };
+    }
+
+    if (paymentIntent?.status === "succeeded") {
+      // The money cleared; Stripe marks the invoice paid right behind it.
+      return { kind: "paid", status: InvoiceStatus.Paid };
+    }
+
+    /*
+     * Stripe refused because a payment is pending, even though the invoice's
+     * PaymentIntent could not be read or is not the pending one. Stripe is
+     * authoritative about that payment, so the customer is told to wait.
+     */
+    if (isPendingPaymentRefusal(data.paymentError)) {
+      return { kind: "processing" };
+    }
+
+    throw toPayInvoiceError({
+      paymentError: data.paymentError,
+      paymentIntent: paymentIntent,
+      suggestNewPaymentMethod: true,
+    });
+  }
+
+  /*
+   * A subscription pinned to an old card keeps charging that card whichever
+   * card the customer pays with by hand. Existing pins are only cleaned up
+   * lazily, so whenever an invoice ends paid or processing the pin is cleared
+   * and the next autopay charges the customer's default card. It must never
+   * fail a payment that already went through, so errors are only logged.
+   */
+  private async moveAutopayToCustomerDefault(data: {
+    customerId: string;
+    projectId: ObjectID;
+  }): Promise<void> {
+    try {
+      await BillingService.syncSubscriptionPaymentMethodsWithCustomerDefault(
+        data.customerId,
+      );
+    } catch (err) {
+      logger.error(err, {
+        projectId: data.projectId.toString(),
+      } as LogAttributes);
+    }
+  }
 }

package/Server/API/BillingPaymentMethodAPI.ts

@@ -4,19 +4,36 @@ import BillingPaymentMethodService, {
   Service as BillingPaymentMethodServiceType,
 } from "../Services/BillingPaymentMethodService";
 import BillingService from "../Services/BillingService";
+import PayAsYouGoBillingService from "../Services/PayAsYouGoBillingService";
 import ProjectService from "../Services/ProjectService";
 import {
   ExpressRequest,
   ExpressResponse,
   NextFunction,
+  OneUptimeRequest,
 } from "../Utils/Express";
 import Response from "../Utils/Response";
 import BaseAPI from "./BaseAPI";
 import BadDataException from "../../Types/Exception/BadDataException";
+import { JSONObject } from "../../Types/JSON";
+import ObjectID from "../../Types/ObjectID";
 import Permission, { UserPermission } from "../../Types/Permission";
 import BillingPaymentMethod from "../../Models/DatabaseModels/BillingPaymentMethod";
 import Project from "../../Models/DatabaseModels/Project";
 
+/*
+ * Who may add a card, and so who may make one the default: the dashboard makes
+ * a newly added card the default straight after adding it, so anyone allowed
+ * to add one has to be allowed to finish that flow. Editing a payment method
+ * is what choosing the default is, so that permission is accepted too.
+ */
+const MANAGE_PAYMENT_METHOD_PERMISSIONS: Array<Permission> = [
+  Permission.ProjectOwner,
+  Permission.ManageProjectBilling,
+  Permission.CreateBillingPaymentMethod,
+  Permission.EditBillingPaymentMethod,
+];
+
 export default class UserAPI extends BaseAPI<
   BillingPaymentMethod,
   BillingPaymentMethodServiceType
@@ -36,7 +53,9 @@ export default class UserAPI extends BaseAPI<
           }
 
           if (req.body["projectId"]) {
-            throw new BadDataException("projectId is required in request body");
+            throw new BadDataException(
+              "projectId should not be passed in the request body. The project is resolved from the tenantid header.",
+            );
           }
 
           const userPermissions: Array<UserPermission> = (
@@ -70,10 +89,6 @@ export default class UserAPI extends BaseAPI<
             throw new BadDataException("Project not found");
           }
 
-          if (!project) {
-            throw new BadDataException("Project not found");
-          }
-
           if (!project.paymentProviderCustomerId) {
             throw new BadDataException("Payment Provider customer not found");
           }
@@ -90,5 +105,111 @@ export default class UserAPI extends BaseAPI<
         }
       },
     );
+
+    /*
+     * Makes one of the project's payment methods the default, and moves
+     * autopay onto it.
+     *
+     * Autopay does not follow the customer's default on its own: a
+     * subscription carrying its own default_payment_method keeps charging that
+     * card. A customer whose card started declining could add a new card and
+     * still see every renewal fail against the old one, because nothing in
+     * OneUptime ever changed which card the subscription charged.
+     * BillingService.makePaymentMethodDefault sets the default and clears
+     * those stale subscription pins together.
+     */
+    this.router.post(
+      `${new this.entityType().getCrudApiPath()?.toString()}/set-default`,
+      UserMiddleware.getUserMiddleware,
+      async (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => {
+        try {
+          if (!IsBillingEnabled) {
+            throw new BadDataException(
+              "Billing is not enabled for this server",
+            );
+          }
+
+          if (req.body["projectId"]) {
+            throw new BadDataException(
+              "projectId should not be passed in the request body. The project is resolved from the tenantid header.",
+            );
+          }
+
+          const userPermissions: Array<UserPermission> = (
+            await this.getPermissionsForTenant(req)
+          ).filter((permission: UserPermission) => {
+            return MANAGE_PAYMENT_METHOD_PERMISSIONS.includes(
+              permission.permission,
+            );
+          });
+
+          if (
+            userPermissions.length === 0 &&
+            !(req as OneUptimeRequest).userAuthorization?.isMasterAdmin
+          ) {
+            throw new BadDataException(
+              "Only project owners or members with Manage Billing access can change the default payment method.",
+            );
+          }
+
+          const tenantId: ObjectID | null = this.getTenantId(req);
+
+          if (!tenantId) {
+            throw new BadDataException("Project not found");
+          }
+
+          const project: Project | null = await ProjectService.findOneById({
+            id: tenantId,
+            props: {
+              isRoot: true,
+            },
+            select: {
+              _id: true,
+              paymentProviderCustomerId: true,
+            },
+          });
+
+          if (!project || !project.id) {
+            throw new BadDataException("Project not found");
+          }
+
+          if (!project.paymentProviderCustomerId) {
+            throw new BadDataException("Payment Provider customer not found");
+          }
+
+          const data: JSONObject | undefined = req.body?.["data"] as
+            | JSONObject
+            | undefined;
+
+          const paymentMethodId: unknown =
+            data?.["paymentProviderPaymentMethodId"];
+
+          if (typeof paymentMethodId !== "string" || !paymentMethodId.trim()) {
+            throw new BadDataException("Payment method ID not found");
+          }
+
+          /*
+           * Always the project's own customer. The service refuses a payment
+           * method that is not attached to it, so an id belonging to another
+           * project's customer cannot be made default here.
+           */
+          await BillingService.makePaymentMethodDefault(
+            project.paymentProviderCustomerId,
+            paymentMethodId.trim(),
+          );
+
+          /*
+           * The cached pay-as-you-go authorization is derived from the
+           * project's payment setup, which just changed. Drop it so the next
+           * check reads the setup fresh, as the payment method sync does.
+           */
+          PayAsYouGoBillingService.invalidate(project.id);
+
+          return Response.sendEmptySuccessResponse(req, res);
+        } catch (err) {
+          next(err);
+        }
+      },
+    );
   }
 }