[PAY-5475] Support for $card_bin_metadata field in Events API (#117)

Author: ademianenko-sift

CHANGES.MD

@@ -1,3 +1,7 @@
+3.18.0 (2025-03-28)
+=================
+- Added support for `$card_bin_metadata` complex field to `$payment_method`
+
 3.17.1 (2024-12-31)
 =================
 - Included HTTP Status codes into `SiftException` message when possible

README.md

@@ -13,13 +13,13 @@ Java 1.7 or later.
 <dependency>
     <groupId>com.siftscience</groupId>
     <artifactId>sift-java</artifactId>
-    <version>3.17.1</version>
+    <version>3.18.0</version>
 </dependency>
 ```
 ### Gradle
 ```
 dependencies {
-    compile 'com.siftscience:sift-java:3.17.1'
+    compile 'com.siftscience:sift-java:3.18.0'
 }
 ```
 ### Other

build.gradle

@@ -5,7 +5,7 @@ apply plugin: 'signing'
 apply plugin: 'java-library-distribution'
 
 group = 'com.siftscience'
-version = '3.17.1'
+version = '3.18.0'
 
 repositories {
     mavenCentral()

src/main/java/com/siftscience/Constants.java

@@ -3,6 +3,6 @@
 public class Constants {
 
     public static final String API_VERSION = "v205";
-    public static final String LIB_VERSION = "3.17.1";
+    public static final String LIB_VERSION = "3.18.0";
     public static final String USER_AGENT_HEADER = String.format("SiftScience/%s sift-java/%s", API_VERSION, LIB_VERSION);
 }

src/main/java/com/siftscience/model/CardBinMetadata.java

@@ -0,0 +1,57 @@
+package com.siftscience.model;
+
+import com.google.gson.annotations.Expose;
+import com.google.gson.annotations.SerializedName;
+
+public class CardBinMetadata {
+    @Expose @SerializedName("$bank") private String bank;
+    @Expose @SerializedName("$brand") private String brand;
+    @Expose @SerializedName("$country") private String country;
+    @Expose @SerializedName("$level") private String level;
+    @Expose @SerializedName("$type") private String type;
+
+    public String getBank() {
+        return bank;
+    }
+
+    public CardBinMetadata setBank(String bank) {
+        this.bank = bank;
+        return this;
+    }
+
+    public String getBrand() {
+        return brand;
+    }
+
+    public CardBinMetadata setBrand(String brand) {
+        this.brand = brand;
+        return this;
+    }
+
+    public String getCountry() {
+        return country;
+    }
+
+    public CardBinMetadata setCountry(String country) {
+        this.country = country;
+        return this;
+    }
+
+    public String getLevel() {
+        return level;
+    }
+
+    public CardBinMetadata setLevel(String level) {
+        this.level = level;
+        return this;
+    }
+
+    public String getType() {
+        return type;
+    }
+
+    public CardBinMetadata setType(String type) {
+        this.type = type;
+        return this;
+    }
+}

src/main/java/com/siftscience/model/PaymentMethod.java

@@ -35,6 +35,7 @@ public class PaymentMethod {
     @Expose @SerializedName("$sepa_direct_debit_mandate") private Boolean sepaDirectDebitMandate;
     @Expose @SerializedName("$wallet_address") private String walletAddress;
     @Expose @SerializedName("$wallet_type") private String walletType;
+    @Expose @SerializedName("$card_bin_metadata") private CardBinMetadata cardBinMetadata;
 
     public String getPaymentType() {
         return paymentType;
@@ -305,4 +306,13 @@ public PaymentMethod setWalletType(String walletType) {
         this.walletType = walletType;
         return this;
     }
+
+    public CardBinMetadata getCardBinMetadata() {
+        return cardBinMetadata;
+    }
+
+    public PaymentMethod setCardBinMetadata(CardBinMetadata cardBinMetadata) {
+        this.cardBinMetadata = cardBinMetadata;
+        return this;
+    }
 }

src/test/java/com/siftscience/SiftRequestTest.java

@@ -29,7 +29,7 @@ public void testUserAgentHeader() throws Exception {
 
         // then
         RecordedRequest recordedRequest = server.takeRequest();
-        assertEquals("SiftScience/v205 sift-java/3.17.1",
+        assertEquals("SiftScience/v205 sift-java/3.18.0",
             recordedRequest.getHeader("User-Agent"));
     }
 

src/test/java/com/siftscience/TransactionEventTest.java

@@ -5,7 +5,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import com.siftscience.model.CardBinMetadata;
 import com.siftscience.model.DigitalOrder;
+import com.siftscience.model.PaymentMethod;
 import com.siftscience.model.TransactionFieldSet;
 import okhttp3.OkHttpClient;
 import okhttp3.mockwebserver.MockResponse;
@@ -794,4 +796,84 @@ public void testTransactionEventWithExtraWithdrawalFields() throws Exception {
 
         server.shutdown();
     }
+
+    @Test
+    public void testTransactionEventWithBinMetadata() throws Exception {
+        String expectedRequestBody = "{\n" +
+            "  \"$type\"             : \"$transaction\",\n" +
+            "  \"$api_key\"          : \"YOUR_API_KEY\",\n" +
+            "  \"$user_id\"          : \"billy_jones_301\",\n" +
+            "  \"$amount\"           : 506790000,\n" +
+            "  \"$currency_code\"    : \"EUR\",\n" +
+            "\n" +
+            "  \"$user_email\"       : \"bill@gmail.com\",\n" +
+            "  \"$transaction_type\" : \"$buy\",\n" +
+            "  \"$transaction_id\"   : \"719637215\",\n" +
+            "\n" +
+            "  \"$payment_method\"   : {\n" +
+            "      \"$payment_type\"     : \"$credit_card\",\n" +
+            "      \"$payment_gateway\"  : \"$braintree\",\n" +
+            "      \"$card_bin\"         : \"542486\",\n" +
+            "      \"$card_last4\"       : \"4444\",\n" +
+            "      \"$card_bin_metadata\": {\n" +
+            "          \"$country\": \"US\",\n" +
+            "          \"$level\"  : \"Gold\",\n" +
+            "          \"$type\"   : \"CREDIT\",\n" +
+            "          \"$brand\"  : \"VISA\",\n" +
+            "          \"$bank\"   : \"Chase\"\n" +
+            "      },\n" +
+            "  },\n" +
+            "}";
+
+        // Start a new mock server and enqueue a mock response.
+        MockWebServer server = new MockWebServer();
+        MockResponse response = new MockResponse();
+        response.setResponseCode(HTTP_OK);
+        response.setBody("{\n" +
+            "    \"status\" : 0,\n" +
+            "    \"error_message\" : \"OK\",\n" +
+            "    \"time\" : 1327604222,\n" +
+            "    \"request\" : \"" + TestUtils.unescapeJson(expectedRequestBody) + "\"\n" +
+            "}");
+        server.enqueue(response);
+        server.start();
+
+        // Create a new client and link it to the mock server.
+        SiftClient client = new SiftClient("YOUR_API_KEY", "YOUR_ACCOUNT_ID",
+            new OkHttpClient.Builder()
+                .addInterceptor(OkHttpUtils.urlRewritingInterceptor(server))
+                .build());
+
+        // Build and execute the request against the mock server.
+        PaymentMethod paymentMethod = TestUtils.samplePaymentMethod1()
+            .setCardBinMetadata(new CardBinMetadata()
+                .setCountry("US")
+                .setLevel("Gold")
+                .setType("CREDIT")
+                .setBrand("VISA")
+                .setBank("Chase"));
+        EventRequest request = client.buildRequest(new TransactionFieldSet()
+            .setUserId("billy_jones_301")
+            .setAmount(506790000L)
+            .setCurrencyCode("EUR")
+            .setUserEmail("bill@gmail.com")
+            .setTransactionType("$buy")
+            .setTransactionId("719637215")
+            .setPaymentMethod(paymentMethod));
+        EventResponse siftResponse = request.send();
+
+        // Verify the request.
+        RecordedRequest request1 = server.takeRequest();
+        Assert.assertEquals("POST", request1.getMethod());
+        Assert.assertEquals("/v205/events", request1.getPath());
+        JSONAssert.assertEquals(expectedRequestBody, request.getFieldSet().toJson(), true);
+
+        // Verify the response.
+        Assert.assertEquals(HTTP_OK, siftResponse.getHttpStatusCode());
+        Assert.assertEquals(0, (int) siftResponse.getBody().getStatus());
+        JSONAssert.assertEquals(response.getBody().readUtf8(),
+            siftResponse.getBody().toJson(), true);
+
+        server.shutdown();
+    }
 }