[ACL-290] Add sub_merchants support to Payments module (#360)

federico1525 · claude · dili91 · web-flow · commit 398daaeb4a49 · 2025-06-17T17:45:34.000+02:00
Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
Co-authored-by: Andrea Di Lisio &lt;andrea.dilisio91@gmail.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -10,5 +10,8 @@ build
 #OSX
 .DS_Store
 
+#Claude Code
+.claude/
+
 # Claude local configuration
 CLAUDE.local.md
diff --git a/gradle.properties b/gradle.properties
@@ -1,7 +1,7 @@
 # Main properties
 group=com.truelayer
 archivesBaseName=truelayer-java
-version=17.2.0
+version=17.3.0
 
 # Artifacts properties
 sonatype_repository_url=https://s01.oss.sonatype.org/service/local/
diff --git a/src/main/java/com/truelayer/java/payments/entities/CreatePaymentRequest.java b/src/main/java/com/truelayer/java/payments/entities/CreatePaymentRequest.java
@@ -4,6 +4,7 @@
 import com.truelayer.java.entities.RelatedProducts;
 import com.truelayer.java.entities.User;
 import com.truelayer.java.payments.entities.paymentmethod.PaymentMethod;
+import com.truelayer.java.payments.entities.submerchants.SubMerchants;
 import java.util.Map;
 import lombok.Builder;
 import lombok.EqualsAndHashCode;
@@ -34,4 +35,9 @@ public class CreatePaymentRequest {
      * Optional field for configuring risk assessment and the payment_creditable webhook
      */
     private RiskAssessment riskAssessment;
+
+    /**
+     * Optional field for sub-merchant details
+     */
+    private SubMerchants subMerchants;
 }
diff --git a/src/main/java/com/truelayer/java/payments/entities/paymentdetail/PaymentDetail.java b/src/main/java/com/truelayer/java/payments/entities/paymentdetail/PaymentDetail.java
@@ -7,6 +7,7 @@
 import com.truelayer.java.commonapi.entities.UserDetail;
 import com.truelayer.java.entities.CurrencyCode;
 import com.truelayer.java.payments.entities.paymentmethod.PaymentMethod;
+import com.truelayer.java.payments.entities.submerchants.SubMerchants;
 import java.time.ZonedDateTime;
 import java.util.Map;
 import lombok.*;
@@ -37,6 +38,11 @@ public abstract class PaymentDetail {
 
     private Map<String, String> metadata;
 
+    /**
+     * Optional sub-merchants information for payment processing.
+     */
+    private SubMerchants subMerchants;
+
     @JsonIgnore
     public abstract Status getStatus();
 
diff --git a/src/main/java/com/truelayer/java/payments/entities/submerchants/BusinessClient.java b/src/main/java/com/truelayer/java/payments/entities/submerchants/BusinessClient.java
@@ -0,0 +1,21 @@
+package com.truelayer.java.payments.entities.submerchants;
+
+import com.truelayer.java.entities.Address;
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+
+@Builder
+@Getter
+@ToString
+@EqualsAndHashCode(callSuper = false)
+public class BusinessClient extends UltimateCounterparty {
+    private final Type type = Type.BUSINESS_CLIENT;
+    private String tradingName;
+    private String commercialName;
+    private String url;
+    private String mcc;
+    private String registrationNumber;
+    private Address address;
+}
diff --git a/src/main/java/com/truelayer/java/payments/entities/submerchants/BusinessDivision.java b/src/main/java/com/truelayer/java/payments/entities/submerchants/BusinessDivision.java
@@ -0,0 +1,16 @@
+package com.truelayer.java.payments.entities.submerchants;
+
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+
+@Builder
+@Getter
+@ToString
+@EqualsAndHashCode(callSuper = false)
+public class BusinessDivision extends UltimateCounterparty {
+    private final Type type = Type.BUSINESS_DIVISION;
+    private String id;
+    private String name;
+}
diff --git a/src/main/java/com/truelayer/java/payments/entities/submerchants/SubMerchants.java b/src/main/java/com/truelayer/java/payments/entities/submerchants/SubMerchants.java
@@ -0,0 +1,14 @@
+package com.truelayer.java.payments.entities.submerchants;
+
+import lombok.Builder;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.ToString;
+
+@Builder
+@Getter
+@ToString
+@EqualsAndHashCode
+public class SubMerchants {
+    private UltimateCounterparty ultimateCounterparty;
+}
diff --git a/src/main/java/com/truelayer/java/payments/entities/submerchants/UltimateCounterparty.java b/src/main/java/com/truelayer/java/payments/entities/submerchants/UltimateCounterparty.java
@@ -0,0 +1,65 @@
+package com.truelayer.java.payments.entities.submerchants;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.annotation.JsonValue;
+import com.truelayer.java.TrueLayerException;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type", defaultImpl = BusinessClient.class)
+@JsonSubTypes({
+    @JsonSubTypes.Type(value = BusinessClient.class, name = "business_client"),
+    @JsonSubTypes.Type(value = BusinessDivision.class, name = "business_division")
+})
+public abstract class UltimateCounterparty {
+
+    @JsonIgnore
+    public abstract Type getType();
+
+    @JsonIgnore
+    public boolean isBusinessClient() {
+        return this instanceof BusinessClient;
+    }
+
+    @JsonIgnore
+    public boolean isBusinessDivision() {
+        return this instanceof BusinessDivision;
+    }
+
+    @JsonIgnore
+    public BusinessClient asBusinessClient() {
+        if (!isBusinessClient()) throw new TrueLayerException(buildErrorMessage());
+        return (BusinessClient) this;
+    }
+
+    @JsonIgnore
+    public BusinessDivision asBusinessDivision() {
+        if (!isBusinessDivision()) throw new TrueLayerException(buildErrorMessage());
+        return (BusinessDivision) this;
+    }
+
+    public static BusinessClient.BusinessClientBuilder businessClient() {
+        return new BusinessClient.BusinessClientBuilder();
+    }
+
+    public static BusinessDivision.BusinessDivisionBuilder businessDivision() {
+        return new BusinessDivision.BusinessDivisionBuilder();
+    }
+
+    private String buildErrorMessage() {
+        return String.format(
+                "UltimateCounterparty is of type %s.", this.getClass().getSimpleName());
+    }
+
+    @Getter
+    @RequiredArgsConstructor
+    public enum Type {
+        BUSINESS_CLIENT("business_client"),
+        BUSINESS_DIVISION("business_division");
+
+        @JsonValue
+        private final String type;
+    }
+}
diff --git a/src/test/java/com/truelayer/java/acceptance/PaymentsAcceptanceTests.java b/src/test/java/com/truelayer/java/acceptance/PaymentsAcceptanceTests.java
@@ -34,6 +34,10 @@
 import com.truelayer.java.payments.entities.providerselection.ProviderSelection;
 import com.truelayer.java.payments.entities.providerselection.UserSelectedProviderSelection;
 import com.truelayer.java.payments.entities.schemeselection.preselected.SchemeSelection;
+import com.truelayer.java.payments.entities.submerchants.BusinessClient;
+import com.truelayer.java.payments.entities.submerchants.BusinessDivision;
+import com.truelayer.java.payments.entities.submerchants.SubMerchants;
+import com.truelayer.java.payments.entities.submerchants.UltimateCounterparty;
 import com.truelayer.java.payments.entities.verification.AutomatedVerification;
 import com.truelayer.java.payments.entities.verification.Verification;
 import com.truelayer.java.versioninfo.LibraryInfoLoader;
@@ -861,4 +865,109 @@ private static Stream<Arguments> provideAutomatedVerifications() {
                         .withRemitterDateOfBirth()
                         .build()));
     }
+
+    private static Stream<Arguments> provideSubMerchantsScenarios() {
+        return Stream.of(
+                Arguments.of(
+                        "BusinessClient",
+                        BusinessClient.builder()
+                                .tradingName("Test Trading Ltd")
+                                .commercialName("Test Commercial Name")
+                                .url("https://example.com")
+                                .mcc("5999")
+                                .registrationNumber("12345678")
+                                .address(Address.builder()
+                                        .addressLine1("123 Test Street")
+                                        .city("London")
+                                        .state("Greater London")
+                                        .zip("EC1R 4RB")
+                                        .countryCode("GB")
+                                        .build())
+                                .build()),
+                Arguments.of(
+                        "BusinessDivision",
+                        BusinessDivision.builder()
+                                .id("division-123")
+                                .name("Test Division")
+                                .build()));
+    }
+
+    @ParameterizedTest
+    @MethodSource("provideSubMerchantsScenarios")
+    @DisplayName("It should create and get a payment with sub-merchants information")
+    @SneakyThrows
+    public void shouldCreateAPaymentWithSubMerchants(
+            String counterpartyType, UltimateCounterparty ultimateCounterparty) {
+        // create payment with sub-merchants
+        SubMerchants subMerchants = SubMerchants.builder()
+                .ultimateCounterparty(ultimateCounterparty)
+                .build();
+
+        CreatePaymentRequest paymentRequest = buildPaymentRequestWithSubMerchants(
+                buildPreselectedProviderSelection(), CurrencyCode.GBP, subMerchants);
+
+        ApiResponse<CreatePaymentResponse> createPaymentResponse =
+                tlClient.payments().createPayment(paymentRequest).get();
+
+        assertNotError(createPaymentResponse);
+        assertTrue(createPaymentResponse.getData().isAuthorizationRequired());
+
+        // get it by id and verify sub-merchants are preserved
+        ApiResponse<PaymentDetail> getPaymentByIdResponse = tlClient.payments()
+                .getPayment(createPaymentResponse.getData().getId())
+                .get();
+
+        assertNotError(getPaymentByIdResponse);
+
+        // Verify the sub-merchants information is returned correctly
+        PaymentDetail paymentDetail = getPaymentByIdResponse.getData();
+        assertNotNull(paymentDetail.getSubMerchants(), "Sub-merchants should not be null");
+        assertEquals(
+                subMerchants.getUltimateCounterparty().getType(),
+                paymentDetail.getSubMerchants().getUltimateCounterparty().getType(),
+                "Ultimate counterparty type should match");
+
+        // Verify type-specific fields
+        if (ultimateCounterparty instanceof BusinessClient) {
+            BusinessClient original = (BusinessClient) ultimateCounterparty;
+            BusinessClient returned =
+                    (BusinessClient) paymentDetail.getSubMerchants().getUltimateCounterparty();
+            assertEquals(original.getTradingName(), returned.getTradingName(), "Trading name should match");
+            assertEquals(original.getCommercialName(), returned.getCommercialName(), "Commercial name should match");
+            assertEquals(original.getMcc(), returned.getMcc(), "MCC should match");
+        } else if (ultimateCounterparty instanceof BusinessDivision) {
+            BusinessDivision original = (BusinessDivision) ultimateCounterparty;
+            BusinessDivision returned =
+                    (BusinessDivision) paymentDetail.getSubMerchants().getUltimateCounterparty();
+            assertEquals(original.getId(), returned.getId(), "Division ID should match");
+            assertEquals(original.getName(), returned.getName(), "Division name should match");
+        }
+    }
+
+    @SneakyThrows
+    private CreatePaymentRequest buildPaymentRequestWithSubMerchants(
+            ProviderSelection providerSelection, CurrencyCode currencyCode, SubMerchants subMerchants) {
+        return CreatePaymentRequest.builder()
+                .amountInMinor(ThreadLocalRandom.current().nextInt(50, 500))
+                .currency(currencyCode)
+                .paymentMethod(PaymentMethod.bankTransfer()
+                        .providerSelection(providerSelection)
+                        .beneficiary(buildBeneficiary(currencyCode))
+                        .build())
+                .user(User.builder()
+                        .name("John Smith")
+                        .email("john.smith@example.com")
+                        .dateOfBirth(LocalDate.now())
+                        .address(Address.builder()
+                                .addressLine1("123 Main Street")
+                                .city("London")
+                                .state("Greater London")
+                                .zip("EC1R 4RB")
+                                .countryCode("GB")
+                                .build())
+                        .build())
+                .metadata(Collections.singletonMap("a_custom_key", "a-custom-value"))
+                .subMerchants(subMerchants)
+                .build();
+    }
 }
diff --git a/src/test/java/com/truelayer/java/integration/PaymentSubMerchantsIntegrationTest.java b/src/test/java/com/truelayer/java/integration/PaymentSubMerchantsIntegrationTest.java
diff --git a/src/test/java/com/truelayer/java/payments/entities/CreatePaymentRequestSubMerchantsTest.java b/src/test/java/com/truelayer/java/payments/entities/CreatePaymentRequestSubMerchantsTest.java
diff --git a/src/test/java/com/truelayer/java/payments/entities/submerchants/SubMerchantsTest.java b/src/test/java/com/truelayer/java/payments/entities/submerchants/SubMerchantsTest.java
diff --git a/src/test/resources/__files/payments/200.get_payment_by_id.with_submerchants.json b/src/test/resources/__files/payments/200.get_payment_by_id.with_submerchants.json
