handling case where payout failed and webhook event not received

2026-01-08 15:27:02 -05:00
parent 65b7574be2
commit 5248c3dc39
7 changed files with 1237 additions and 29 deletions
--- a/backend/utils/payoutErrors.js
+++ b/backend/utils/payoutErrors.js
@@ -0,0 +1,102 @@
+/**
+ * Payout Error Handling Utility
+ *
+ * Maps Stripe payout failure codes to user-friendly messages for owners.
+ * These codes indicate why a bank deposit failed.
+ */
+
+const PAYOUT_FAILURE_MESSAGES = {
+  account_closed: {
+    message: "Your bank account has been closed.",
+    action: "Please update your bank account in your payout settings.",
+    requiresBankUpdate: true,
+  },
+  account_frozen: {
+    message: "Your bank account is frozen.",
+    action: "Please contact your bank to resolve this issue.",
+    requiresBankUpdate: false,
+  },
+  bank_account_restricted: {
+    message: "Your bank account has restrictions that prevent deposits.",
+    action: "Please contact your bank or add a different account.",
+    requiresBankUpdate: true,
+  },
+  bank_ownership_changed: {
+    message: "The ownership of your bank account has changed.",
+    action: "Please re-verify your bank account in your payout settings.",
+    requiresBankUpdate: true,
+  },
+  could_not_process: {
+    message: "Your bank could not process the deposit.",
+    action: "This is usually temporary. We'll retry automatically.",
+    requiresBankUpdate: false,
+  },
+  debit_not_authorized: {
+    message: "Your bank account is not authorized to receive deposits.",
+    action: "Please contact your bank to enable incoming transfers.",
+    requiresBankUpdate: false,
+  },
+  declined: {
+    message: "Your bank declined the deposit.",
+    action: "Please contact your bank for more information.",
+    requiresBankUpdate: false,
+  },
+  insufficient_funds: {
+    message: "The deposit was returned.",
+    action:
+      "This can happen with some account types. Please verify your account details.",
+    requiresBankUpdate: true,
+  },
+  invalid_account_number: {
+    message: "Your bank account number appears to be invalid.",
+    action: "Please verify and update your bank account details.",
+    requiresBankUpdate: true,
+  },
+  incorrect_account_holder_name: {
+    message: "The name on your bank account doesn't match your profile.",
+    action: "Please update your bank account or profile information.",
+    requiresBankUpdate: true,
+  },
+  incorrect_account_holder_type: {
+    message: "Your bank account type doesn't match what was expected.",
+    action: "Please verify your account type (individual vs business).",
+    requiresBankUpdate: true,
+  },
+  invalid_currency: {
+    message: "Your bank account doesn't support this currency.",
+    action: "Please add a bank account that supports USD deposits.",
+    requiresBankUpdate: true,
+  },
+  no_account: {
+    message: "The bank account could not be found.",
+    action: "Please verify your account number and routing number.",
+    requiresBankUpdate: true,
+  },
+  unsupported_card: {
+    message: "The debit card used for payouts is not supported.",
+    action: "Please update to a supported debit card or bank account.",
+    requiresBankUpdate: true,
+  },
+};
+
+// Default message for unknown failure codes
+const DEFAULT_PAYOUT_FAILURE = {
+  message: "There was an issue depositing funds to your bank.",
+  action: "Please check your bank account details or contact support.",
+  requiresBankUpdate: true,
+};
+
+/**
+ * Get user-friendly payout failure message
+ * @param {string} failureCode - The Stripe payout failure code
+ * @returns {Object} - { message, action, requiresBankUpdate }
+ */
+function getPayoutFailureMessage(failureCode) {
+  return PAYOUT_FAILURE_MESSAGES[failureCode] || DEFAULT_PAYOUT_FAILURE;
+}
+
+module.exports = {
+  PAYOUT_FAILURE_MESSAGES,
+  DEFAULT_PAYOUT_FAILURE,
+  getPayoutFailureMessage,
+};