feat(payments): add fallback_source_used to PaymentProcessing and complete ProcessingData JavaDoc

src/main/java/com/checkout/payments/PaymentProcessing.java

@@ -141,6 +141,12 @@ public final class PaymentProcessing {
      */
     private Long surchargeAmount;
 
+    /**
+     * Indicates whether the {@code fallback_source} field was used for the payment.
+     * [Optional]
+     */
+    private Boolean fallbackSourceUsed;
+
     /**
      * Indicates whether a Checkout.com Network Token was available for the payment.
      * [Optional]

src/main/java/com/checkout/payments/response/ProcessingData.java

@@ -12,50 +12,157 @@
 @Data
 public final class ProcessingData {
 
+    /**
+     * The preferred scheme for co-badged card payment processing. If performing 3DS via a third party,
+     * this is the scheme that processed 3DS. Does not support PINless debit schemes in the US
+     * (STAR, PULSE, NYCE, ACCEL, SHAZAM).
+     * [Optional]
+     */
     private PreferredSchema preferredScheme;
 
+    /**
+     * The customer's application identifier.
+     * [Optional]
+     */
     private String appId;
 
+    /**
+     * The customer's ID on the partner platform.
+     * [Optional]
+     */
     private String partnerCustomerId;
 
+    /**
+     * The partner-originated unique payment identifier.
+     * [Optional]
+     */
     private String partnerPaymentId;
 
+    /**
+     * Total tax amount of the order.
+     * [Optional]
+     */
     private Long taxAmount;
 
+    /**
+     * The country where the purchase was made. ISO 3166-1 alpha-2 country code.
+     * Not documented in the public spec for this response, kept for backward compatibility.
+     * [Optional]
+     */
     private CountryCode purchaseCountry;
 
+    /**
+     * The language and region of the customer. ISO 639-2 language code, its value consists of
+     * language-country.
+     * [Optional]
+     * Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$
+     * min 2 characters, max 10 characters
+     */
     private String locale;
 
+    /**
+     * A unique identifier for the authorization provided by partner.
+     * [Optional]
+     */
     private String retrievalReferenceNumber;
 
+    /**
+     * The Klarna order ID associated with the payment.
+     * [Optional]
+     */
     private String partnerOrderId;
 
+    /**
+     * Status of a payment provided by partner.
+     * [Optional]
+     */
     private String partnerStatus;
 
+    /**
+     * Unique transaction identification provided by partner.
+     * [Optional]
+     */
     private String partnerTransactionId;
 
+    /**
+     * The list of error codes that led the payment to fail or be declined, as given by the
+     * payment provider.
+     * [Optional]
+     */
     private List<String> partnerErrorCodes;
 
+    /**
+     * Error description provided by partner.
+     * [Optional]
+     */
     private String partnerErrorMessage;
 
+    /**
+     * Authorization code provided by partner.
+     * [Optional]
+     */
     private String partnerAuthorizationCode;
 
+    /**
+     * Authorization response code provided by partner.
+     * [Optional]
+     */
     private String partnerAuthorizationResponseCode;
 
+    /**
+     * Fraud status of the payment.
+     * Not documented in the public spec for this response, kept for backward compatibility.
+     * Prefer {@code partnerFraudStatus}.
+     * [Optional]
+     */
     private String fraudStatus;
 
+    /**
+     * The payment method authorized by the provider.
+     * Not documented in the public spec for this response, kept for backward compatibility.
+     * [Optional]
+     */
     private ProviderAuthorizedPaymentMethod providerAuthorizedPaymentMethod;
 
+    /**
+     * An array defining which of the configured payment options within a payment category
+     * (for example, {@code pay_later} or {@code pay_over_time}) should be displayed for this purchase.
+     * [Optional]
+     */
     private List<String> customPaymentMethodIds;
 
+    /**
+     * Indicates whether the payment is an Account Funding Transaction.
+     * [Optional]
+     */
     private Boolean aft;
 
+    /**
+     * Four-digit code for retail financial services expressed in ISO 18245 format, classifying
+     * the types of goods or services you provide.
+     * [Optional]
+     */
     private String merchantCategoryCode;
 
+    /**
+     * The merchant identifier that was configured with the scheme and used for the payment.
+     * [Optional]
+     */
     private String schemeMerchantId;
 
+    /**
+     * The type of Primary Account Number (PAN) used for the payment. DPAN indicates a network
+     * token was used, FPAN indicates the full card was used.
+     * [Optional]
+     * Enum: "fpan" "dpan"
+     */
     private PanProcessedType panTypeProcessed;
 
+    /**
+     * Indicates whether a Checkout.com Network Token was available for the payment.
+     * Not documented in the public spec for this response, kept for backward compatibility.
+     * [Optional]
+     */
     private Boolean ckoNetworkTokenAvailable;
 
     /**

src/test/java/com/checkout/payments/PaymentProcessingSerializationTest.java

@@ -195,6 +195,7 @@ void shouldDeserializeFullSwaggerExample() {
                 + "\"recommendation_code\":\"R001\","
                 + "\"scheme\":\"Mastercard\","
                 + "\"pan_type_processed\":\"fpan\","
+                + "\"fallback_source_used\":true,"
                 + "\"cko_network_token_available\":false,"
                 + "\"purchase_country\":\"GB\","
                 + "\"scheme_merchant_id\":\"SMI001\","
@@ -215,6 +216,7 @@ void shouldDeserializeFullSwaggerExample() {
         assertEquals("Acquirer Bank", processing.getAcquirerName());
         assertEquals(CountryCode.GB, processing.getAcquirerCountryCode());
         assertEquals(PanProcessedType.FPAN, processing.getPanTypeProcessed());
+        assertEquals(Boolean.TRUE, processing.getFallbackSourceUsed());
         assertEquals(Boolean.FALSE, processing.getCkoNetworkTokenAvailable());
         assertEquals(CountryCode.GB, processing.getPurchaseCountry());
         assertEquals("SMI001", processing.getSchemeMerchantId());
@@ -224,6 +226,28 @@ void shouldDeserializeFullSwaggerExample() {
         assertEquals("MTL-XYZ-789", processing.getSchemeTransactionLinkId());
     }
 
+    @Test
+    void shouldDeserializeFallbackSourceUsed() {
+        final String json = "{\"fallback_source_used\":true}";
+
+        final PaymentProcessing processing = serializer.fromJson(json, PaymentProcessing.class);
+
+        assertNotNull(processing);
+        assertEquals(Boolean.TRUE, processing.getFallbackSourceUsed());
+    }
+
+    @Test
+    void shouldRoundTripFallbackSourceUsed() {
+        final PaymentProcessing processing = new PaymentProcessing();
+        processing.setFallbackSourceUsed(false);
+
+        final String json = serializer.toJson(processing);
+        final PaymentProcessing deserialized = serializer.fromJson(json, PaymentProcessing.class);
+
+        assertTrue(json.contains("\"fallback_source_used\":false"));
+        assertEquals(Boolean.FALSE, deserialized.getFallbackSourceUsed());
+    }
+
     @Test
     void shouldHandleAbsentOptionalFields() {
         final String json = "{}";