[EWT-135] feat: adds support for X-Forwarded-For HTTP header in start auth flow for single payments (#195)

Author: dili91

build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'java-library'
     // to unleash the lombok magic
-    id "io.freefair.lombok" version "6.6.3"
+    id "io.freefair.lombok" version "8.0.1"
     // to make our tests output more fancy
     id 'com.adarshr.test-logger' version '3.2.0'
     // to publish packages
@@ -10,7 +10,7 @@ plugins {
     id "com.diffplug.spotless" version "6.17.0"
     //  test coverage
     id 'jacoco'
-    id 'com.github.kt3k.coveralls' version '2.12.0'
+    id 'com.github.kt3k.coveralls' version '2.12.2'
     // signing
     id "signing"
     // nexus publishing

gradle.properties

@@ -1,7 +1,7 @@
 # Main properties
 group=com.truelayer
 archivesBaseName=truelayer-java
-version=6.0.1
+version=6.1.0
 
 # Artifacts properties
 sonatype_repository_url=https://s01.oss.sonatype.org/service/local/

src/main/java/com/truelayer/java/Constants.java

@@ -28,6 +28,7 @@ public static final class HeaderNames {
         public static final String TL_SIGNATURE = "Tl-Signature";
         public static final String TL_AGENT = "TL-Agent";
         public static final String AUTHORIZATION = "Authorization";
+        public static final String X_FORWARDED_FOR = "X-Forwarded-For";
         public static final String COOKIE = "Cookie";
         public static final String TL_CORRELATION_ID = "X-Tl-Correlation-Id";
     }

src/main/java/com/truelayer/java/payments/IPaymentsApi.java

@@ -1,13 +1,12 @@
 package com.truelayer.java.payments;
 
+import static com.truelayer.java.Constants.HeaderNames.X_FORWARDED_FOR;
+
 import com.truelayer.java.http.entities.ApiResponse;
 import com.truelayer.java.payments.entities.*;
 import com.truelayer.java.payments.entities.paymentdetail.PaymentDetail;
 import java.util.concurrent.CompletableFuture;
-import retrofit2.http.Body;
-import retrofit2.http.GET;
-import retrofit2.http.POST;
-import retrofit2.http.Path;
+import retrofit2.http.*;
 
 /**
  * Exposes all the payments related capabilities of the library.
@@ -45,6 +44,21 @@ public interface IPaymentsApi {
     CompletableFuture<ApiResponse<AuthorizationFlowResponse>> startAuthorizationFlow(
             @Path("id") String paymentId, @Body StartAuthorizationFlowRequest request);
 
+    /**
+     * Starts an authorization flow for a given payment resource,
+     * including the <code>X-Forwarded-For</code> HTTP header field to record the end-user IP address.
+     * @param paymentId the payment identifier
+     * @param request a start authorization flow request payload
+     * @param xForwardedFor the end-user IP address
+     * @return the response of the <i>Start Authorization Flow</i> operation
+     * @see <a href="https://docs.truelayer.com/reference/start-payment-authorization-flow"><i>Start Authorization Flow</i> API reference</a>
+     */
+    @POST("/payments/{id}/authorization-flow")
+    CompletableFuture<ApiResponse<AuthorizationFlowResponse>> startAuthorizationFlow(
+            @Path("id") String paymentId,
+            @Body StartAuthorizationFlowRequest request,
+            @Header(X_FORWARDED_FOR) String xForwardedFor);
+
     /**
      * Submit the provider selection for a given payment resource.
      * @param paymentId the payment identifier

src/test/java/com/truelayer/java/TestUtils.java

@@ -105,6 +105,7 @@ public static class RequestStub {
         private int status;
         private String bodyFile;
         private Integer delayMilliseconds;
+        private String xForwardedForHeader;
 
         private RequestStub() {}
 
@@ -147,6 +148,11 @@ public RequestStub withSignature() {
             return this;
         }
 
+        public RequestStub withXForwardedForHeader(String ipAddress) {
+            this.xForwardedForHeader = ipAddress;
+            return this;
+        }
+
         public RequestStub delayMs(int delayMilliseconds) {
             this.delayMilliseconds = delayMilliseconds;
             return this;
@@ -167,6 +173,10 @@ public StubMapping build() {
                 request.withHeader(IDEMPOTENCY_KEY, matching(UUID_REGEX_PATTERN));
             }
 
+            if (!isEmpty(xForwardedForHeader)) {
+                request.withHeader(X_FORWARDED_FOR, equalTo(xForwardedForHeader));
+            }
+
             ResponseDefinitionBuilder response = aResponse()
                     .withHeader(TL_CORRELATION_ID, UUID.randomUUID().toString())
                     .withStatus(status);

src/test/java/com/truelayer/java/integration/PaymentsIntegrationTests.java

@@ -1,7 +1,6 @@
 package com.truelayer.java.integration;
 
-import static com.github.tomakehurst.wiremock.client.WireMock.urlPathEqualTo;
-import static com.github.tomakehurst.wiremock.client.WireMock.urlPathMatching;
+import static com.github.tomakehurst.wiremock.client.WireMock.*;
 import static com.truelayer.java.TestUtils.assertNotError;
 import static com.truelayer.java.payments.entities.paymentdetail.Status.*;
 import static com.truelayer.java.payments.entities.paymentmethod.PaymentMethod.Type.BANK_TRANSFER;
@@ -110,7 +109,7 @@ public void shouldReturnAPaymentDetail(PaymentMethod.Type paymentMethodType, Sta
                 .build();
         RequestStub.New()
                 .method("get")
-                .path(urlPathMatching("/payments/" + A_PAYMENT_ID))
+                .path(urlPathEqualTo("/payments/" + A_PAYMENT_ID))
                 .withAuthorization()
                 .status(200)
                 .bodyFile(jsonResponseFile)
@@ -207,7 +206,7 @@ public void shouldStartAnAuthorizationFlow(String status) {
                 .build();
         RequestStub.New()
                 .method("post")
-                .path(urlPathMatching("/payments/" + A_PAYMENT_ID + "/authorization-flow"))
+                .path(urlPathEqualTo("/payments/" + A_PAYMENT_ID + "/authorization-flow"))
                 .withAuthorization()
                 .withIdempotencyKey()
                 .status(200)
@@ -226,6 +225,40 @@ public void shouldStartAnAuthorizationFlow(String status) {
         assertEquals(expected, response.getData());
     }
 
+    @SneakyThrows
+    @Test
+    @DisplayName("It should start an authorization flow with custom X-Forwarded-For HTTP header")
+    public void shouldStartAnAuthorizationFlowWithXForwardedForHeader() {
+        String jsonResponseFile = "payments/200.start_authorization_flow.authorizing.wait.json";
+        String endUserIpAddress = "11.1.2.3";
+        RequestStub.New()
+                .method("post")
+                .path(urlPathEqualTo("/connect/token"))
+                .status(200)
+                .bodyFile("auth/200.access_token.json")
+                .build();
+        RequestStub.New()
+                .method("post")
+                .path(urlPathEqualTo("/payments/" + A_PAYMENT_ID + "/authorization-flow"))
+                .withAuthorization()
+                .withIdempotencyKey()
+                .withXForwardedForHeader(endUserIpAddress)
+                .status(200)
+                .bodyFile(jsonResponseFile)
+                .build();
+        StartAuthorizationFlowRequest request =
+                StartAuthorizationFlowRequest.builder().build();
+
+        ApiResponse<AuthorizationFlowResponse> response = tlClient.payments()
+                .startAuthorizationFlow(A_PAYMENT_ID, request, endUserIpAddress)
+                .get();
+
+        assertNotError(response);
+        AuthorizationFlowResponse expected =
+                TestUtils.deserializeJsonFileTo(jsonResponseFile, AuthorizationFlowResponse.class);
+        assertEquals(expected, response.getData());
+    }
+
     @SneakyThrows
     @ParameterizedTest(name = "and get a response of type {0}")
     @ValueSource(strings = {"AUTHORIZING", "FAILED"})