feat: adds referral customer billing functions

CHANGELOG.md

@@ -3,6 +3,11 @@
 ## Next Release
 
 - Adds `WebhookCustomHeader` model, allowing `custom_headers` to be passed when creating/updating a webhook
+- Adds the following functions to assist ReferralCustomers add credit cards and bank accounts:
+  - `betaReferralCustomer.createCreditCardClientSecret`
+  - `betaReferralCustomer.createBankAccountClientSecret`
+  - `referralCustomer.addCreditCardFromStripe`
+  - `referralCustomer.addBankAccountFromStripe`
 - Adds `tracking_codes` param to tracker index endpoint
 - Fixes error parsing
   - Allows for alternative format of `errors` field (previously we deserialized the `errors` field into a list of `Error` objects; however, sometimes the errors are simply a list of strings. This change make the `errors` field a list of `Object` allowing for either the new `FieldError` object or a list of strings. Users will need to check for the type of error returned and handle appropriately)

src/main/java/com/easypost/model/ClientSecret.java

@@ -0,0 +1,8 @@
+package com.easypost.model;
+
+import lombok.Getter;
+
+@Getter
+public final class ClientSecret {
+    private String clientSecret;
+}

src/main/java/com/easypost/model/PaymentMethodObject.java

@@ -48,6 +48,8 @@ String getEndpoint() {
     private String name;
     // bank_account
     private boolean verified;
+    // both
+    private boolean requiresMandateCollection;
 
     /**
      * Get the type of this PaymentMethodObject object.

src/main/java/com/easypost/service/BetaReferralCustomerService.java

@@ -6,6 +6,7 @@
 import com.easypost.http.Requestor;
 import com.easypost.http.Requestor.RequestMethod;
 import com.easypost.model.BetaPaymentRefund;
+import com.easypost.model.ClientSecret;
 import com.easypost.model.PaymentMethod;
 import com.easypost.model.PaymentMethodObject;
 
@@ -92,4 +93,44 @@ public BetaPaymentRefund refundByPaymentLog(String paymentLogId) throws EasyPost
         return Requestor.request(RequestMethod.POST, endpoint, params,
                 BetaPaymentRefund.class, client, "beta");
     }
+
+    /**
+     * Creates a client secret to use with Stripe when adding a credit card.
+     *
+     * @return ClientSecret containing the client secret.
+     * @throws EasyPostException When the request fails.
+     */
+    public ClientSecret createCreditCardClientSecret() throws EasyPostException {
+        String endpoint = "setup_intents";
+
+        return Requestor.request(RequestMethod.POST, endpoint, null, ClientSecret.class, client, "beta");
+    }
+
+    /**
+     * Creates a client secret to use with Stripe when adding a bank account.
+     *
+     * @return ClientSecret containing the client secret.
+     * @throws EasyPostException When the request fails.
+     */
+    public ClientSecret createBankAccountClientSecret() throws EasyPostException {
+        return createBankAccountClientSecret(null);
+    }
+
+    /**
+     * Creates a client secret to use with Stripe when adding a bank account.
+     *
+     * @param returnUrl Optional return URL for the bank account setup.
+     * @return ClientSecret containing the client secret.
+     * @throws EasyPostException When the request fails.
+     */
+    public ClientSecret createBankAccountClientSecret(String returnUrl) throws EasyPostException {
+        HashMap<String, Object> params = new HashMap<>();
+        if (returnUrl != null) {
+            params.put("return_url", returnUrl);
+        }
+
+        String endpoint = "financial_connections_sessions";
+
+        return Requestor.request(RequestMethod.POST, endpoint, params, ClientSecret.class, client, "beta");
+    }
 }

src/main/java/com/easypost/service/ReferralCustomerService.java

@@ -166,6 +166,59 @@ public PaymentMethodObject addCreditCardToUser(final String referralApiKey, fina
         return createEasypostCreditCard(referralApiKey, stripeToken, priority.toString().toLowerCase());
     }
 
+    /**
+     * Add a credit card to EasyPost for a ReferralCustomer with a payment method ID from Stripe.
+     * This function requires the ReferralCustomer User's API key.
+     *
+     * @param referralApiKey  API key of the referral user.
+     * @param paymentMethodId Payment method ID from Stripe.
+     * @param priority        Priority of the credit card (e.g., "primary" or "secondary").
+     * @return PaymentMethodObject object.
+     * @throws EasyPostException when the request fails.
+     */
+    public PaymentMethodObject addCreditCardFromStripe(final String referralApiKey, final String paymentMethodId,
+                                                    final PaymentMethod.Priority priority) throws EasyPostException {
+        Map<String, Object> params = new HashMap<>();
+        Map<String, Object> creditCardParams = new HashMap<>();
+        creditCardParams.put("payment_method_id", paymentMethodId);
+        creditCardParams.put("priority", priority.toString().toLowerCase());
+        params.put("credit_card", creditCardParams);
+
+        EasyPostClient referralClient = new EasyPostClient(referralApiKey);
+
+        String endpoint = "credit_cards";
+
+        return Requestor.request(RequestMethod.POST, endpoint, params, PaymentMethodObject.class, referralClient);
+    }
+
+    /**
+     * Add a bank account to EasyPost for a ReferralCustomer.
+     * This function requires the ReferralCustomer User's API key.
+     *
+     * @param referralApiKey          API key of the referral user.
+     * @param financialConnectionsId  Financial connections ID from Stripe.
+     * @param mandateData             Mandate data for the bank account.
+     * @param priority                Priority of the bank account (e.g., "primary" or "secondary").
+     * @return PaymentMethodObject object.
+     * @throws EasyPostException when the request fails.
+     */
+    public PaymentMethodObject addBankAccountFromStripe(final String referralApiKey, 
+                                                        final String financialConnectionsId,
+                                                        final Map<String, Object> mandateData,
+                                                        final PaymentMethod.Priority priority)
+            throws EasyPostException {
+        Map<String, Object> params = new HashMap<>();
+        params.put("financial_connections_id", financialConnectionsId);
+        params.put("mandate_data", mandateData);
+        params.put("priority", priority.toString().toLowerCase());
+
+        EasyPostClient referralClient = new EasyPostClient(referralApiKey);
+
+        String endpoint = "bank_accounts";
+
+        return Requestor.request(RequestMethod.POST, endpoint, params, PaymentMethodObject.class, referralClient);
+    }
+
     /**
      * Retrieve EasyPost Stripe API key.
      *