feat: coverFees optional and return breakdown of fees

README.md

@@ -27,8 +27,13 @@ calculateStripeFee(
   // Bank card Alpha-2 country code
   cardCountryCode: string,
   // Your applicationFee in percents, default to 0
-  applicationFee: number = 0
-): number // Returns resulting fee amount in cents
+  applicationFee: number = 0,
+  coverFees: boolean = true,
+): {
+  totalFeeAmount: number,
+  applicationFeeAmount: number,
+  providerFeeAmount: number
+} // Returns resulting fee amounts in cents: total, provider and application
 ```
 
 E.g. transaction from UK card to US account:

src/stripe-fees.ts

@@ -158,15 +158,39 @@ const calculateStripeFee = (
   amount: number,
   accountCountryCode: string,
   cardCountryCode: string,
-  applicationFee: number = 0
+  applicationFee: number = 0,
+  coverFees: boolean = true
 ) => {
   if (!amount) {
-    return 0
+    return {
+      totalFeeAmount: 0,
+      applicationFeeAmount: 0,
+      providerFeeAmount: 0
+    }
   }
   const result = _calculateFees(accountCountryCode, cardCountryCode)
-  return Math.round(
-    (amount + result.fixedFee) / (1 - result.percentFee / 100 - applicationFee / 100) - amount
-  )
+  if (coverFees) {
+    // Final donation amount that is needed to cover the fees
+    // @see https://support.stripe.com/questions/passing-the-stripe-fee-on-to-customers
+    const grossAmount =
+      (amount + result.fixedFee) / (1 - (result.percentFee + applicationFee) / 100)
+    const totalFeeAmount = grossAmount - amount
+    const applicationFeeAmount = grossAmount * (applicationFee / 100)
+    const providerFeeAmount = totalFeeAmount - applicationFeeAmount
+    return {
+      totalFeeAmount: Math.round(totalFeeAmount),
+      applicationFeeAmount: Math.round(applicationFeeAmount),
+      providerFeeAmount: Math.round(providerFeeAmount)
+    }
+  }
+  const totalFeeAmount = amount * ((result.percentFee + applicationFee) / 100) + result.fixedFee
+  const applicationFeeAmount = amount * (applicationFee / 100)
+  const providerFeeAmount = totalFeeAmount - applicationFeeAmount
+  return {
+    totalFeeAmount: Math.round(totalFeeAmount),
+    applicationFeeAmount: Math.round(applicationFeeAmount),
+    providerFeeAmount: Math.round(providerFeeAmount)
+  }
 }
 
 export default calculateStripeFee

test/stripe-fees.test.ts

@@ -1,15 +1,47 @@
 import calculateStripeFee, { _calculateFees } from '../src/stripe-fees'
 
+test('Throws on bad country code', () => {
+  expect(() => calculateStripeFee(10, 'ZZ', 'ZZ')).toThrow(
+    'Given country code "ZZ" is not supported by Stripe'
+  )
+})
+
 test('0 amount yields 0 fee', () => {
-  expect(calculateStripeFee(0, 'GB', 'GB', 0)).toBe(0)
+  expect(calculateStripeFee(0, 'GB', 'GB', 0)).toEqual({
+    totalFeeAmount: 0,
+    applicationFeeAmount: 0,
+    providerFeeAmount: 0
+  })
 })
 
 test('Integrational GB => US', () => {
-  expect(calculateStripeFee(10000, 'US', 'GB', 0)).toBe(437)
+  expect(calculateStripeFee(10000, 'US', 'GB', 0)).toEqual({
+    applicationFeeAmount: 0,
+    providerFeeAmount: 437,
+    totalFeeAmount: 437
+  })
+})
+test('Integrational GB => US, don\t cover fees', () => {
+  expect(calculateStripeFee(10000, 'US', 'GB', 0, false)).toEqual({
+    applicationFeeAmount: 0,
+    providerFeeAmount: 420,
+    totalFeeAmount: 420
+  })
 })
 
 test('Integrational US => GB', () => {
-  expect(calculateStripeFee(10000, 'GB', 'US', 0)).toBe(547)
+  expect(calculateStripeFee(10000, 'GB', 'US', 0)).toEqual({
+    applicationFeeAmount: 0,
+    providerFeeAmount: 547,
+    totalFeeAmount: 547
+  })
+})
+test('Integrational US => GB, don\t cover fees', () => {
+  expect(calculateStripeFee(10000, 'GB', 'US', 0, false)).toEqual({
+    applicationFeeAmount: 0,
+    providerFeeAmount: 520,
+    totalFeeAmount: 520
+  })
 })
 
 test('US => US', () => {