feat: Added support for retained_fee in adjustment totals (#190)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -25,6 +25,7 @@ adding additional type guards.
 ### Added
 
 - Added support for new payment methods `blik`, `mb_way`, `pix` and `upi`. See [related changelog](https://developer.paddle.com/changelog/2025/blik-mbway-payment-methods).
+- Support `retained_fee` field on totals objects to show the fees retained by Paddle for the adjustment.
 
 ### Changed
 

src/__tests__/mocks/notifications/adjustment-created.mock.ts

@@ -27,12 +27,28 @@ export const AdjustmentCreatedMock: IEventsResponse<IAdjustmentResponse> = {
     type: 'partial',
     reason: 'error',
     status: 'pending_approval',
-    totals: { fee: '5', tax: '8', total: '100', earnings: '87', subtotal: '92', currency_code: 'USD' },
+    totals: {
+      fee: '5',
+      tax: '8',
+      total: '100',
+      earnings: '87',
+      subtotal: '92',
+      currency_code: 'USD',
+      retained_fee: '2',
+    },
     created_at: '2023-08-21T14:08:43.297512Z',
     updated_at: '0001-01-01T00:00:00Z',
     customer_id: 'ctm_01h8441jn5pcwrfhwh78jqt8hk',
     currency_code: 'USD',
-    payout_totals: { fee: '5', tax: '8', total: '100', earnings: '87', subtotal: '92', currency_code: 'USD' },
+    payout_totals: {
+      fee: '5',
+      tax: '8',
+      total: '100',
+      earnings: '87',
+      subtotal: '92',
+      currency_code: 'USD',
+      retained_fee: '2',
+    },
     transaction_id: 'txn_01h8bxpvx398a7zbawb77y0kp5',
     subscription_id: 'sub_01h8bxswamxysj44zt5n48njwh',
     credit_applied_to_balance: true,
@@ -70,6 +86,7 @@ export const AdjustmentCreatedMockExpectation = {
       subtotal: '92',
       tax: '8',
       total: '100',
+      retainedFee: '2',
     },
     reason: 'error',
     status: 'pending_approval',
@@ -81,6 +98,7 @@ export const AdjustmentCreatedMockExpectation = {
       subtotal: '92',
       tax: '8',
       total: '100',
+      retainedFee: '2',
     },
     transactionId: 'txn_01h8bxpvx398a7zbawb77y0kp5',
     updatedAt: '0001-01-01T00:00:00Z',

src/__tests__/mocks/notifications/adjustment-updated.mock.ts

@@ -27,12 +27,28 @@ export const AdjustmentUpdatedMock: IEventsResponse<IAdjustmentResponse> = {
     type: 'partial',
     reason: 'error',
     status: 'approved',
-    totals: { fee: '5', tax: '8', total: '100', earnings: '87', subtotal: '92', currency_code: 'USD' },
+    totals: {
+      fee: '5',
+      tax: '8',
+      total: '100',
+      earnings: '87',
+      subtotal: '92',
+      currency_code: 'USD',
+      retained_fee: '2',
+    },
     created_at: '2023-08-21T14:08:43.297512Z',
     updated_at: '2023-08-21T14:10:08.42549Z',
     customer_id: 'ctm_01h8441jn5pcwrfhwh78jqt8hk',
     currency_code: 'USD',
-    payout_totals: { fee: '5', tax: '8', total: '100', earnings: '87', subtotal: '92', currency_code: 'USD' },
+    payout_totals: {
+      fee: '5',
+      tax: '8',
+      total: '100',
+      earnings: '87',
+      subtotal: '92',
+      currency_code: 'USD',
+      retained_fee: '2',
+    },
     transaction_id: 'txn_01h8bxpvx398a7zbawb77y0kp5',
     subscription_id: 'sub_01h8bxswamxysj44zt5n48njwh',
     credit_applied_to_balance: true,
@@ -70,6 +86,7 @@ export const AdjustmentUpdatedMockExpectation = {
       subtotal: '92',
       tax: '8',
       total: '100',
+      retainedFee: '2',
     },
     reason: 'error',
     status: 'approved',
@@ -81,6 +98,7 @@ export const AdjustmentUpdatedMockExpectation = {
       subtotal: '92',
       tax: '8',
       total: '100',
+      retainedFee: '2',
     },
     transactionId: 'txn_01h8bxpvx398a7zbawb77y0kp5',
     updatedAt: '2023-08-21T14:10:08.42549Z',

src/__tests__/mocks/notifications/transaction-billed.mock.ts

@@ -160,6 +160,7 @@ export const TransactionBilledMock: IEventsResponse<ITransactionNotificationResp
         subtotal: '1319900',
         grand_total: '1437041',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: null,
     },
@@ -225,6 +226,7 @@ export const TransactionBilledMockExpectation = {
         subtotal: '1319900',
         tax: '117141',
         total: '1437041',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-canceled.mock.ts

@@ -160,6 +160,7 @@ export const TransactionCanceledMock: IEventsResponse<ITransactionNotificationRe
         subtotal: '1319900',
         grand_total: '1437041',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: null,
     },
@@ -225,6 +226,7 @@ export const TransactionCanceledMockExpectation = {
         subtotal: '1319900',
         tax: '117141',
         total: '1437041',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-completed.mock.ts

@@ -173,6 +173,7 @@ export const TransactionCompletedMock: IEventsResponse<ITransactionNotificationR
         subtotal: '59900',
         grand_total: '65215',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: {
         fee: '3311',
@@ -183,6 +184,7 @@ export const TransactionCompletedMock: IEventsResponse<ITransactionNotificationR
         currency_code: 'USD',
         chargeback_fee: { amount: '0', original: null },
         exchange_rate: '1',
+        retained_fee: '2',
       },
     },
     checkout: {
@@ -265,6 +267,7 @@ export const TransactionCompletedMockExpectation = {
         tax: '5315',
         total: '65215',
         exchangeRate: '1',
+        retainedFee: '2',
       },
       adjustedTotals: {
         currencyCode: 'USD',
@@ -274,6 +277,7 @@ export const TransactionCompletedMockExpectation = {
         subtotal: '59900',
         tax: '5315',
         total: '65215',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-paid.mock.ts

@@ -89,6 +89,7 @@ export const TransactionPaidMock: IEventsResponse<ITransactionNotificationRespon
         earnings: '69226',
         subtotal: '74900',
         currency_code: 'GBP',
+        retained_fee: '2',
       },
       line_items: [
         {
@@ -220,6 +221,7 @@ export const TransactionPaidMockExpectation = {
         subtotal: '74900',
         tax: '14980',
         total: '89880',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-past-due.mock.ts

@@ -122,6 +122,7 @@ export const TransactionPastDueMock: IEventsResponse<ITransactionNotificationRes
         subtotal: '40000',
         grand_total: '43549',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: null,
     },
@@ -191,6 +192,7 @@ export const TransactionPastDueMockExpectation = {
         subtotal: '40000',
         tax: '3549',
         total: '43549',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-payment-failed.mock.ts

@@ -160,6 +160,7 @@ export const TransactionPaymentFailedMock: IEventsResponse<ITransactionNotificat
         subtotal: '59900',
         grand_total: '65215',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: null,
     },
@@ -226,6 +227,7 @@ export const TransactionPaymentFailedMockExpectation = {
         subtotal: '59900',
         tax: '5315',
         total: '65215',
+        retainedFee: '2',
       },
       lineItems: [
         {

src/__tests__/mocks/notifications/transaction-ready.mock.ts

@@ -159,6 +159,7 @@ export const TransactionReadyMock: IEventsResponse<ITransactionNotificationRespo
         subtotal: '59900',
         grand_total: '65215',
         currency_code: 'USD',
+        retained_fee: '2',
       },
       adjusted_payout_totals: null,
     },
@@ -210,6 +211,7 @@ export const TransactionReadyMockExpectation = {
         subtotal: '59900',
         tax: '5315',
         total: '65215',
+        retainedFee: '2',
       },
       lineItems: [
         {