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

Author: davidgrayston-paddle

CHANGELOG.md

@@ -12,6 +12,7 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 
 - Non-catalog discounts on Transactions, see [changelog](https://developer.paddle.com/changelog/2025/custom-discounts?utm_source=dx&utm_medium=paddle-php-sdk)
 - 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?utm_source=dx&utm_medium=paddle-php-sdk).
+- Support `retained_fee` field on totals objects to show the fees retained by Paddle for the adjustment.
 - `ApiError` will now have `retryAfter` property set for [too_many_requests](https://developer.paddle.com/errors/shared/too_many_requests) errors
 
 ## [1.11.0] - 2025-09-15

src/Entities/Shared/AdjustmentTotals.php

@@ -18,6 +18,7 @@ private function __construct(
         public string $tax,
         public string $total,
         public string $fee,
+        public string $retainedFee,
         public string $earnings,
         public CurrencyCode $currencyCode,
     ) {
@@ -30,6 +31,7 @@ public static function from(array $data): self
             tax: $data['tax'],
             total: $data['total'],
             fee: $data['fee'],
+            retainedFee: $data['retained_fee'],
             earnings: $data['earnings'],
             currencyCode: CurrencyCode::from($data['currency_code']),
         );

src/Entities/Shared/PayoutTotalsAdjustment.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $fee,
         public ChargebackFee|null $chargebackFee,
+        public string $retainedFee,
         public string $earnings,
         public CurrencyCodePayouts $currencyCode,
     ) {
@@ -32,6 +33,7 @@ public static function from(array $data): self
             total: $data['total'],
             fee: $data['fee'],
             chargebackFee: isset($data['chargeback_fee']) ? ChargebackFee::from($data['chargeback_fee']) : null,
+            retainedFee: $data['retained_fee'],
             earnings: $data['earnings'],
             currencyCode: CurrencyCodePayouts::from($data['currency_code']),
         );

src/Entities/Shared/TransactionPayoutTotalsAdjusted.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $fee,
         public ChargebackFee $chargebackFee,
+        public string $retainedFee,
         public string $earnings,
         public CurrencyCodePayouts $currencyCode,
         public string $exchangeRate,
@@ -33,6 +34,7 @@ public static function from(array $data): self
             $data['total'],
             $data['fee'],
             ChargebackFee::from($data['chargeback_fee']),
+            $data['retained_fee'],
             $data['earnings'],
             CurrencyCodePayouts::from($data['currency_code']),
             $data['exchange_rate'],

src/Entities/Shared/TransactionTotalsAdjusted.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $grandTotal,
         public string|null $fee,
+        public string $retainedFee,
         public string|null $earnings,
         public CurrencyCode $currencyCode,
     ) {
@@ -32,6 +33,7 @@ public static function from(array $data): self
             $data['total'],
             $data['grand_total'],
             $data['fee'] ?? null,
+            $data['retained_fee'],
             $data['earnings'] ?? null,
             CurrencyCode::from($data['currency_code']),
         );

src/Notifications/Entities/Shared/AdjustmentTotals.php

@@ -18,6 +18,7 @@ private function __construct(
         public string $tax,
         public string $total,
         public string $fee,
+        public string|null $retainedFee,
         public string $earnings,
         public CurrencyCode $currencyCode,
     ) {
@@ -30,6 +31,7 @@ public static function from(array $data): self
             tax: $data['tax'],
             total: $data['total'],
             fee: $data['fee'],
+            retainedFee: $data['retained_fee'] ?? null,
             earnings: $data['earnings'],
             currencyCode: CurrencyCode::from($data['currency_code']),
         );

src/Notifications/Entities/Shared/PayoutTotalsAdjustment.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $fee,
         public ChargebackFee|null $chargebackFee,
+        public string|null $retainedFee,
         public string $earnings,
         public CurrencyCodePayouts $currencyCode,
     ) {
@@ -32,6 +33,7 @@ public static function from(array $data): self
             total: $data['total'],
             fee: $data['fee'],
             chargebackFee: isset($data['chargeback_fee']) ? ChargebackFee::from($data['chargeback_fee']) : null,
+            retainedFee: $data['retained_fee'] ?? null,
             earnings: $data['earnings'],
             currencyCode: CurrencyCodePayouts::from($data['currency_code']),
         );

src/Notifications/Entities/Shared/TransactionPayoutTotalsAdjusted.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $fee,
         public ChargebackFee $chargebackFee,
+        public string|null $retainedFee,
         public string $earnings,
         public CurrencyCodePayouts $currencyCode,
         public string|null $exchangeRate,
@@ -33,6 +34,7 @@ public static function from(array $data): self
             $data['total'],
             $data['fee'],
             ChargebackFee::from($data['chargeback_fee']),
+            $data['retained_fee'] ?? null,
             $data['earnings'],
             CurrencyCodePayouts::from($data['currency_code']),
             $data['exchange_rate'] ?? null,

src/Notifications/Entities/Shared/TransactionTotalsAdjusted.php

@@ -19,6 +19,7 @@ private function __construct(
         public string $total,
         public string $grandTotal,
         public string|null $fee,
+        public string|null $retainedFee,
         public string|null $earnings,
         public CurrencyCode $currencyCode,
     ) {
@@ -32,6 +33,7 @@ public static function from(array $data): self
             $data['total'],
             $data['grand_total'],
             $data['fee'] ?? null,
+            $data['retained_fee'] ?? null,
             $data['earnings'] ?? null,
             CurrencyCode::from($data['currency_code']),
         );

tests/Functional/Resources/Adjustments/_fixtures/response/full_entity.json

@@ -40,6 +40,7 @@
             "tax": "8",
             "total": "100",
             "fee": "5",
+            "retained_fee": "0",
             "earnings": "87",
             "currency_code": "USD"
         },
@@ -48,6 +49,7 @@
             "tax": "163",
             "total": "2049",
             "fee": "20",
+            "retained_fee": "0",
             "earnings": "2029",
             "currency_code": "USD"
         },