RC-2.0.1 Add support for InvoicePaymet API updates (#45)

# Update #

Adding support for `InvoicePayment.Create`, `InvoicePayment.Update` API
updates

### Checklist

- [x] I acknowledge that all my contributions will be made under the
project's license
- [x] I have made a material change to the repo (functionality, testing,
spelling, grammar)
- [x] I have titled the PR appropriately
- [x] I have updated my branch with the main branch
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have added the necessary documentation about the functionality
in the appropriate .md file
- [x] I have added inline documentation to the code I modified

If you have questions, create a GitHub Issue in this repository.

README.md

@@ -12,7 +12,7 @@ Add this dependency to your project's POM:
 <dependency>
     <groupId>com.trolley</groupId>
     <artifactId>java-sdk</artifactId>
-    <version>2.0.0</version>
+    <version>2.0.1</version>
 </dependency>
 ```
 

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.trolley</groupId>
     <artifactId>java-sdk</artifactId>
-    <version>2.0.0</version>
+    <version>2.0.1</version>
     <description>Java SDK for Trolley API</description>
     <packaging>jar</packaging>
     <name>Trolley Java SDK</name>

src/main/java/com/trolley/InvoicePaymentGateway.java

@@ -8,6 +8,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.trolley.Exceptions.InvalidFieldException;
 import com.trolley.types.InvoicePayment;
+import com.trolley.types.supporting.InvoicePaymentRequest;
 import com.trolley.types.supporting.InvoicePaymentPart;
 import com.trolley.types.supporting.InvoicePayments;
 import com.trolley.types.supporting.InvoicePaymentsIterator;
@@ -26,12 +27,14 @@ public InvoicePaymentGateway(final Configuration config) {
      * NOTE: If you provide a batch id, this method will try to add the payment to it. If you provide a 
      * {@code null} or blank ({@code ""}) batch id, a new batch will be created.
      *
+     * @deprecated As of v2.0.1, this method is deprecated to support improvements to Create InvoicePayment API. Use {@link InvoicePaymentGateway#create(InvoicePaymentRequest) create(InvoicePaymentRequest)} instead.
      * 
      * @param batchId (Optional) Id of the batch you want to add these payments too.
      * @param payment InvoicePaymentPart object representing the Invoice payment that needs to be created
      * @return InvoicePayment object of representing the created payment for the Invoice
      * @throws Exception
      */
+    @Deprecated
     public InvoicePayment create(final String batchId, final InvoicePaymentPart payment) throws Exception {
         final String endPoint = "/v1/invoices/payment/create/";
 
@@ -62,11 +65,14 @@ public InvoicePayment create(final String batchId, final InvoicePaymentPart paym
      * NOTE: If you provide a batch id, this method will try to add the payment to it. If you provide a 
      * {@code null} or blank ({@code ""}) batch id, a new batch will be created. 
      * 
+     * @deprecated As of v2.0.1, this method is deprecated to support improvements to Create InvoicePayment API. Use {@link InvoicePaymentGateway#create(InvoicePaymentRequest) create(InvoicePaymentRequest)} instead.
+     * 
      * @param batchId (Optional) Id of the batch you want to add these payments too.
      * @param invoicePaymentParts A List of InvoicePaymentPart objects representing the Invoice payments that need to be created.
      * @return InvoicePayment object of representing the created payment for the Invoice
      * @throws Exception
      */
+    @Deprecated
     public InvoicePayment create(final String batchId, final List<InvoicePaymentPart> invoicePaymentParts) throws Exception {
         final String endPoint = "/v1/invoices/payment/create/";
 
@@ -86,6 +92,27 @@ public InvoicePayment create(final String batchId, final List<InvoicePaymentPart
         return InvoicePayment.invoicePaymentFactory(response);
     }
 
+    /**
+     * Create a payment against an invoice, with payment fields.
+     * <p>
+     * NOTE: If you provide a batch id, this method will try to add the payment to it. If you provide a 
+     * {@code null} or blank ({@code ""}) batch id, a new batch will be created.
+     *
+     * @param invoicePaymentRequest {@code InvoicePaymentRequest} object representing the InvoicePayment request, with payment fields that needs to be added to the created payment.
+     * @return InvoicePayment object of representing the created payment for the Invoice
+     * @throws Exception
+     */
+    public InvoicePayment create(final InvoicePaymentRequest invoicePaymentRequest) throws Exception {
+        final String endPoint = "/v1/invoices/payment/create/";
+
+        String body= new ObjectMapper()
+                    .setSerializationInclusion(Include.NON_EMPTY)
+                    .writeValueAsString(invoicePaymentRequest);
+
+        final String response = this.client.post(endPoint, body);
+        return InvoicePayment.invoicePaymentFactory(response);
+    }
+
    /**
     * Update an Invoice Payment whose details are provided in invoicePaymentPart object.
     * <p>

src/main/java/com/trolley/types/supporting/InvoicePaymentPart.java

@@ -1,10 +1,18 @@
 package com.trolley.types.supporting;
 
+import java.util.ArrayList;
+
 public class InvoicePaymentPart{
     private String invoiceId;
     private String invoiceLineId;
     private String paymentId;
     private Amount amount;
+
+    //These fields are to hold values from parsed JSON, not for request body
+    private boolean coverFees;
+    private String memo;
+    private String externalId;
+    private String[] tags;
 
     public InvoicePaymentPart() {
     }
@@ -16,6 +24,21 @@ public InvoicePaymentPart(String invoiceId, String invoiceLineId, String payment
         this.amount = amount;
     }
 
+    /**
+     * IMPORTANT: Use as request only while updating an InvoicePayment. For "Create Invoice Payment" request, use {@link InvoicePaymentRequest#InvoicePaymentRequest(String, boolean, String, String, String[], InvoicePaymentPart) InvoicePaymentRequest}.
+     */
+    public InvoicePaymentPart(String invoiceId, String invoiceLineId, String paymentId, Amount amount,
+            boolean coverFees, String memo, String externalId, String[] tags) {
+        this.invoiceId = invoiceId;
+        this.invoiceLineId = invoiceLineId;
+        this.paymentId = paymentId;
+        this.amount = amount;
+        this.coverFees = coverFees;
+        this.memo = memo;
+        this.externalId = externalId;
+        this.tags = tags;
+    }
+
     public String getInvoiceId() {
         return invoiceId;
     }
@@ -46,5 +69,53 @@ public Amount getAmount() {
 
     public void setAmount(Amount amount) {
         this.amount = amount;
-    }  
+    }
+
+    public boolean shouldCoverFees() {
+        return coverFees;
+    }
+
+    /**
+     * IMPORTANT: Use as request only while updating an InvoicePayment
+     * @param coverFees
+     */
+    public void setCoverFees(boolean coverFees) {
+        this.coverFees = coverFees;
+    }
+
+    public String getMemo() {
+        return memo;
+    }
+
+    /**
+     * IMPORTANT: Use as request only while updating an InvoicePayment
+     * @param memo
+     */
+    public void setMemo(String memo) {
+        this.memo = memo;
+    }
+
+    public String getExternalId() {
+        return externalId;
+    }
+
+    /**
+     * IMPORTANT: Use as request only while updating an InvoicePayment
+     * @param externalId
+     */
+    public void setExternalId(String externalId) {
+        this.externalId = externalId;
+    }
+
+    public String[] getTags() {
+        return tags;
+    }
+
+    /**
+     * IMPORTANT: Use as request only while updating an InvoicePayment
+     * @param tags
+     */
+    public void setTags(String[] tags) {
+        this.tags = tags;
+    }
 }

src/main/java/com/trolley/types/supporting/InvoicePaymentRequest.java

@@ -0,0 +1,104 @@
+package com.trolley.types.supporting;
+
+import java.util.ArrayList;
+
+/**
+ * Used while creating a new InvoicePayment request
+ */
+public class InvoicePaymentRequest{
+    private String batchId;
+    private boolean coverFees;
+    private String memo;
+    private String externalId;
+    private String[] tags;
+    private InvoicePaymentPart[] ids;
+
+    public InvoicePaymentRequest() {
+    }
+
+    /**
+     * Constructor to create a new request when you have more than one Invoices or InvoiceLines to create payment for.
+     * @param batchId ID of the batch you'd want to add this payment to. If it's {@code null} or {@code ""}, a new payment will be created.
+     * @param coverFees Denotes whether you want to cover fees with this payment.
+     * @param memo A recipient viewable Memo that you'd want the created payment to have.
+     * @param externalId A unique External ID that you'd want to assign to the created payment.
+     * @param tags A {@code String[]} array where each element is a merchant-viewable tag that you want to assign to the created payment.
+     * @param ids An {@code InvoicePaymentPart[]} array representing InvoicePaymentPart objects containing IDs and Amounts of Invoices and InvoiceLines you want to create payments for.
+     */
+    public InvoicePaymentRequest(String batchId, boolean coverFees, String memo, String externalId,
+            String[] tags, InvoicePaymentPart[] ids) {
+        this.batchId = batchId;
+        this.coverFees = coverFees;
+        this.memo = memo;
+        this.externalId = externalId;
+        this.tags = tags;
+        this.ids = ids;
+    }
+
+    /**
+     * Constructor to create a new request when you have only one Invoice/InvoiceLine to create a payment for.
+     * @param batchId ID of the batch you'd want to add this payment to. If it's {@code null} or {@code ""}, a new payment will be created.
+     * @param coverFees Denotes whether you want to cover fees with this payment.
+     * @param memo A recipient viewable Memo that you'd want the created payment to have.
+     * @param externalId A unique External ID that you'd want to assign to the created payment.
+     * @param tags A {@code String[]} array where each element is a merchant-viewable tag that you want to assign to the created payment.
+     * @param ids An {@code InvoicePaymentPart[]} array representing InvoicePaymentPart objects containing IDs and Amounts of Invoices and InvoiceLines you want to create payments for.
+     */
+    public InvoicePaymentRequest(String batchId, boolean coverFees, String memo, String externalId,
+            String[] tags, InvoicePaymentPart paymentPart) {
+        this.batchId = batchId;
+        this.coverFees = coverFees;
+        this.memo = memo;
+        this.externalId = externalId;
+        this.tags = tags;
+        this.ids = new InvoicePaymentPart[]{paymentPart};
+    }
+
+    public String getBatchId() {
+        return batchId;
+    }
+
+    public void setBatchId(String batchId) {
+        this.batchId = batchId;
+    }
+
+    public boolean shouldCoverFees() {
+        return coverFees;
+    }
+
+    public void setCoverFees(boolean coverFees) {
+        this.coverFees = coverFees;
+    }
+
+    public String getMemo() {
+        return memo;
+    }
+
+    public void setMemo(String memo) {
+        this.memo = memo;
+    }
+
+    public String getExternalId() {
+        return externalId;
+    }
+
+    public void setExternalId(String externalId) {
+        this.externalId = externalId;
+    }
+
+    public String[] getTags() {
+        return tags;
+    }
+
+    public void setTags(String[] tags) {
+        this.tags = tags;
+    }
+
+    public InvoicePaymentPart[] getIds() {
+        return ids;
+    }
+
+    public void setIds(InvoicePaymentPart[] ids) {
+        this.ids = ids;
+    }
+}

src/test/java/com/trolley/integration/InvoiceTests.java

@@ -16,6 +16,7 @@
 import com.trolley.types.Invoices;
 import com.trolley.types.Recipient;
 import com.trolley.types.supporting.Amount;
+import com.trolley.types.supporting.InvoicePaymentRequest;
 import com.trolley.types.supporting.InvoicePaymentPart;
 import com.trolley.types.supporting.InvoicePaymentsIterator;
 import com.trolley.types.supporting.InvoicesIterator;
@@ -247,6 +248,7 @@ public void testInvoicePayments() throws Exception {
             null, 
             null, 
             invoiceLines));
+
         assertEquals(invoice.getRecipientId(), recipient.getId());
 
         //Create a new Invoice Payment
@@ -255,7 +257,17 @@ public void testInvoicePayments() throws Exception {
         paymentPart.setInvoiceLineId(invoice.getLines().get(0).getId());
         paymentPart.setAmount(new Amount("50", "USD"));
 
-        InvoicePayment invoicePayment = client.invoicePayment.create(null, paymentPart);
+        String[] tags = {"tag1", "tag2"};
+
+        InvoicePaymentRequest invoicePaymentRequest = new InvoicePaymentRequest(
+            null,
+            false,
+            "Integration Test Payment",
+            "ext-id-"+System.currentTimeMillis(),
+            tags,
+            paymentPart);       
+
+        InvoicePayment invoicePayment = client.invoicePayment.create(invoicePaymentRequest);
 
         assertTrue(invoicePayment.getInvoicePayments().size()>0);
 
@@ -265,6 +277,8 @@ public void testInvoicePayments() throws Exception {
         paymentPart.setInvoiceLineId(invoice.getLines().get(0).getId());
         paymentPart.setPaymentId(invoicePayment.getPaymentId());
         paymentPart.setAmount(new Amount("10","USD"));
+        paymentPart.setExternalId("ext-id-"+System.currentTimeMillis());
+        paymentPart.setCoverFees(true);
 
         boolean paymentUpdateResult = client.invoicePayment.update(paymentPart);
         assertTrue(paymentUpdateResult);