[ACL-253] Add scheme_id field to Payout and Refund transactions (#366)

Co-authored-by: Claude <[email protected]>
Co-authored-by: Andrea Di Lisio <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [17.4.0] - TBD
+### Added
+* Add support for `scheme_id` field in merchant account transaction responses for Payout and Refund transactions
+* The `scheme_id` field provides information about the payment scheme used (e.g., "faster_payments_service", "sepa_credit_transfer", "internal_transfer")
+
+## [17.3.0] - 2025-04-16
+### Added
+* Add sub_merchants support to Payments module
+
 ## [17.2.0] - 2025-04-16
 ### Added
 * Add support for `deprecated_at` property to GET payment API response

gradle.properties

@@ -1,7 +1,7 @@
 # Main properties
 group=com.truelayer
 archivesBaseName=truelayer-java
-version=17.3.1
+version=17.4.0
 
 # Artifacts properties
 project_name=TrueLayer Java

src/main/java/com/truelayer/java/merchantaccounts/entities/transactions/Payout.java

@@ -4,6 +4,7 @@
 import com.fasterxml.jackson.annotation.JsonValue;
 import com.truelayer.java.entities.CurrencyCode;
 import com.truelayer.java.entities.beneficiary.Beneficiary;
+import com.truelayer.java.payouts.entities.SchemeId;
 import java.time.ZonedDateTime;
 import java.util.Map;
 import java.util.Optional;
@@ -47,6 +48,8 @@ public class Payout extends Transaction {
 
     String payoutId;
 
+    SchemeId schemeId;
+
     Map<String, String> metadata;
 
     @JsonGetter
@@ -59,6 +62,11 @@ public Optional<ZonedDateTime> getExecutedAt() {
         return Optional.ofNullable(executedAt);
     }
 
+    @JsonGetter
+    public Optional<SchemeId> getSchemeId() {
+        return Optional.ofNullable(schemeId);
+    }
+
     @RequiredArgsConstructor
     @Getter
     public enum ContextCode {

src/main/java/com/truelayer/java/merchantaccounts/entities/transactions/Refund.java

@@ -3,6 +3,7 @@
 import com.fasterxml.jackson.annotation.JsonGetter;
 import com.truelayer.java.entities.CurrencyCode;
 import com.truelayer.java.entities.beneficiary.PaymentSource;
+import com.truelayer.java.payouts.entities.SchemeId;
 import java.time.ZonedDateTime;
 import java.util.Map;
 import java.util.Optional;
@@ -37,6 +38,8 @@ public class Refund extends Transaction {
 
     String paymentId;
 
+    SchemeId schemeId;
+
     Map<String, String> metadata;
 
     @JsonGetter
@@ -48,4 +51,9 @@ public Optional<Map<String, String>> getMetadata() {
     public Optional<ZonedDateTime> getExecutedAt() {
         return Optional.ofNullable(executedAt);
     }
+
+    @JsonGetter
+    public Optional<SchemeId> getSchemeId() {
+        return Optional.ofNullable(schemeId);
+    }
 }

src/test/java/com/truelayer/java/merchantaccounts/entities/transactions/TransactionTests.java

@@ -103,6 +103,7 @@ public void shouldYieldTrueIfPayout() {
                 null,
                 Payout.ContextCode.INTERNAL,
                 UUID.randomUUID().toString(),
+                null,
                 null);
 
         assertTrue(sut.isPayout());
@@ -121,6 +122,7 @@ public void shouldConvertToPayout() {
                 null,
                 Payout.ContextCode.INTERNAL,
                 UUID.randomUUID().toString(),
+                null,
                 null);
 
         assertDoesNotThrow(sut::asPayout);
@@ -157,6 +159,7 @@ public void shouldYieldTrueIfRefund() {
                 Payout.ContextCode.INTERNAL,
                 UUID.randomUUID().toString(),
                 UUID.randomUUID().toString(),
+                null,
                 null);
 
         assertTrue(sut.isRefund());
@@ -176,6 +179,7 @@ public void shouldConvertToRefund() {
                 Payout.ContextCode.INTERNAL,
                 UUID.randomUUID().toString(),
                 UUID.randomUUID().toString(),
+                null,
                 null);
 
         assertDoesNotThrow(sut::asRefund);

src/test/resources/__files/merchant_accounts/200.get_transactions.json

@@ -75,7 +75,8 @@
         ]
       },
       "context_code":"withdrawal",
-      "payout_id":"string"
+      "payout_id":"string",
+      "scheme_id":"faster_payments_service"
     },
     {
       "type":"payout",
@@ -104,7 +105,8 @@
         "payout_id": "an-id"
       },
       "context_code":"withdrawal",
-      "payout_id":"string"
+      "payout_id":"string",
+      "scheme_id":"sepa_credit_transfer"
     },
     {
       "type":"payout",
@@ -131,7 +133,8 @@
         ]
       },
       "context_code":"withdrawal",
-      "payout_id":"string"
+      "payout_id":"string",
+      "scheme_id":"internal_transfer"
     },
     {
       "type":"refund",
@@ -162,7 +165,8 @@
       },
       "context_code":"withdrawal",
       "refund_id":"an-id",
-      "payment_id":"another-id"
+      "payment_id":"another-id",
+      "scheme_id":"faster_payments_service"
     }
   ],
   "pagination": {