feature/INT-1724 - CashApp payment method integration (#686)

* feat(payment-setups): add device fingerprint, ip, client and os fields

customer.device gains fingerprint, ipv4, ipv6, client (web, mobile_web, app) and os (android, ios). The client is required by Cash App.

* feat(payment-setups): add Cash App Pay payment method

Adds payment_methods.cashapp with customer_profile_sharing and the read-only customer_profile, reference and action (redirect_url). The key is pinned with SerializedName so the global underscore naming policy cannot turn it into cash_app. Tests use the SDK serializer to assert the wire format.

* CashApp review and tests

---------

Co-authored-by: Armando Rodríguez <127134616+armando-rodriguez-cko@users.noreply.github.com>

Author: david-ruiz-cko

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/customer/Customer.java

@@ -1,13 +1,14 @@
 package com.checkout.handlepaymentsandpayouts.setups.entities.customer;
 
+import com.checkout.common.CountryCode;
 import com.checkout.common.Phone;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
 /**
- * Customer information for payment setup
+ * The customer's details.
  */
 @Data
 @Builder
@@ -16,28 +17,52 @@
 public final class Customer {
 
     /**
-     * The customer's email information
+     * Details of the customer's email.
+     * [Optional]
      */
     private CustomerEmail email;
 
     /**
-     * <= 100 characters
-     * The customer's full name
+     * The customer's full name.
+     * [Optional]
+     * max 100 characters
      */
     private String name;
 
     /**
-     * The customer's phone number
+     * The customer's phone number.
+     * [Optional]
      */
     private Phone phone;
 
     /**
-     * Information about the customer's device
+     * Details of the customer's device.
+     * [Optional]
      */
     private CustomerDevice device;
 
     /**
-     * Details of the account the customer holds with the merchant
+     * Details of the account the customer holds with the merchant.
+     * [Optional]
      */
     private MerchantAccount merchantAccount;
-}
+
+    /**
+     * The unique identifier of the customer.
+     * [Optional]
+     */
+    private String id;
+
+    /**
+     * The two-letter ISO country code of the customer for this payment.
+     * [Optional]
+     * min 2 characters, max 2 characters
+     */
+    private CountryCode country;
+
+    /**
+     * The customer's tax identification number.
+     * [Optional]
+     */
+    private String taxNumber;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/customer/CustomerDevice.java

@@ -1,12 +1,13 @@
 package com.checkout.handlepaymentsandpayouts.setups.entities.customer;
 
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.OsType;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
 /**
- * Customer device information
+ * Details of the customer's device.
  */
 @Data
 @Builder
@@ -15,7 +16,41 @@
 public final class CustomerDevice {
 
     /**
-     * The locale setting of the customer's device (e.g., "en-US")
+     * The locale of the device, for example en_GB.
+     * [Optional]
      */
     private String locale;
-}
+
+    /**
+     * A unique identifier for the customer's device.
+     * [Optional]
+     */
+    private String fingerprint;
+
+    /**
+     * The customer's device IPv4 address, used by some payment methods for risk and eligibility checks.
+     * [Optional]
+     */
+    private String ipv4;
+
+    /**
+     * The customer's device IPv6 address, used by some payment methods for risk and eligibility checks.
+     * [Optional]
+     */
+    private String ipv6;
+
+    /**
+     * The type of client the customer uses to initiate the payment. Required when using Cash App
+     * Pay; a Cash App payment setup without it is rejected.
+     * [Optional]
+     * Enum: "web" "mobile_web" "app"
+     */
+    private CustomerDeviceClient client;
+
+    /**
+     * The operating system of the customer's device.
+     * [Optional]
+     * Enum: "android" "ios"
+     */
+    private OsType os;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/customer/CustomerDeviceClient.java

@@ -0,0 +1,27 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.customer;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * The type of client the customer uses to initiate the payment.
+ */
+public enum CustomerDeviceClient {
+
+    /**
+     * A web browser on a desktop device.
+     */
+    @SerializedName("web")
+    WEB,
+
+    /**
+     * A web browser on a mobile device.
+     */
+    @SerializedName("mobile_web")
+    MOBILE_WEB,
+
+    /**
+     * A native mobile application.
+     */
+    @SerializedName("app")
+    APP
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/PaymentMethods.java

@@ -12,6 +12,7 @@
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.blik.Blik;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.card.Card;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cardpresent.CardPresent;
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cashapp.CashApp;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.paybybank.PayByBank;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.stablecoin.Stablecoin;
 import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.dana.Dana;
@@ -307,4 +308,12 @@ public final class PaymentMethods {
      * [Optional]
      */
     private Stablecoin stablecoin;
+
+    /**
+     * The Cash App Pay payment method's details and configuration. The wire key is the single
+     * word cashapp, so keep this field name lowercase: the naming policy turns cashApp into
+     * cash_app.
+     * [Optional]
+     */
+    private CashApp cashapp;
 }

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/cashapp/CashApp.java

@@ -0,0 +1,53 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cashapp;
+
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentMethodBase;
+import com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.common.PaymentMethodInitialization;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/**
+ * Cash App Pay payment method configuration. The customer must be sent to the redirect URL
+ * returned in the action to authorize the payment with Cash App. The payment setup customer
+ * device client is required for this method.
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public final class CashApp extends PaymentMethodBase {
+
+    /**
+     * The initialization state of the payment method. Defaults to disabled.
+     * [Optional]
+     */
+    private PaymentMethodInitialization initialization = PaymentMethodInitialization.DISABLED;
+
+    /**
+     * Indicates whether the customer consents to share their Cash App customer profile with
+     * Checkout.com. When enabled, the customer profile is returned once, after the customer
+     * authorizes the payment.
+     * [Optional]
+     */
+    private Boolean customerProfileSharing;
+
+    /**
+     * The customer's Cash App profile that they consented to share. Included in the response when
+     * customer_profile_sharing is enabled. Cash App releases this profile only once: it is present
+     * in the first successful response when you get the payment setup after the customer
+     * authorizes the payment, and every subsequent response omits it, so store it on first read.
+     * [Optional] readOnly
+     */
+    private CashAppCustomerProfile customerProfile;
+
+    /**
+     * A reference for the Cash App Pay transaction, returned by the provider.
+     * [Optional] readOnly
+     * max 80 characters
+     */
+    private String reference;
+
+    /**
+     * The next available action for the payment method. When its type is redirect, send the
+     * customer to its redirect URL to authorize the payment with Cash App.
+     * [Optional] readOnly
+     */
+    private CashAppAction action;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/cashapp/CashAppAction.java

@@ -0,0 +1,30 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cashapp;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * The next available action for the Cash App payment method.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public final class CashAppAction {
+
+    /**
+     * The type of action.
+     * [Optional] readOnly
+     * Enum: "redirect"
+     */
+    private CashAppActionType type;
+
+    /**
+     * The URL to redirect the customer to so they can authorize the payment with Cash App.
+     * [Optional] readOnly
+     * Format: uri
+     */
+    private String redirectUrl;
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/cashapp/CashAppActionType.java

@@ -0,0 +1,15 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cashapp;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * The type of next action for the Cash App payment method.
+ */
+public enum CashAppActionType {
+
+    /**
+     * Redirect the customer to Cash App to authorize the payment.
+     */
+    @SerializedName("redirect")
+    REDIRECT
+}

src/main/java/com/checkout/handlepaymentsandpayouts/setups/entities/paymentMethods/cashapp/CashAppAddress.java

@@ -0,0 +1,74 @@
+package com.checkout.handlepaymentsandpayouts.setups.entities.paymentMethods.cashapp;
+
+import com.checkout.common.CountryCode;
+import com.google.gson.annotations.SerializedName;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * The customer's address from their Cash App profile. The keys follow Cash App's naming
+ * (address_line_1, locality, administrative_district_level_1), not the Checkout.com address, so
+ * the line and district fields carry an explicit serialized name: the naming policy alone would
+ * produce address_line1.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public final class CashAppAddress {
+
+    /**
+     * The first line of the address.
+     * [Optional] readOnly
+     */
+    @SerializedName("address_line_1")
+    private String addressLine1;
+
+    /**
+     * The second line of the address.
+     * [Optional] readOnly
+     */
+    @SerializedName("address_line_2")
+    private String addressLine2;
+
+    /**
+     * The third line of the address.
+     * [Optional] readOnly
+     */
+    @SerializedName("address_line_3")
+    private String addressLine3;
+
+    /**
+     * The address locality, such as the city or town.
+     * [Optional] readOnly
+     */
+    private String locality;
+
+    /**
+     * The address sublocality, such as the district or neighborhood.
+     * [Optional] readOnly
+     */
+    private String sublocality;
+
+    /**
+     * The address's top-level administrative district, such as the state or province.
+     * [Optional] readOnly
+     */
+    @SerializedName("administrative_district_level_1")
+    private String administrativeDistrictLevel1;
+
+    /**
+     * The postal or zip code.
+     * [Optional] readOnly
+     */
+    private String postalCode;
+
+    /**
+     * The address country, in ISO 3166-1 alpha-2 format.
+     * [Optional] readOnly
+     * max 2 characters
+     */
+    private CountryCode country;
+}