Release/2.20180918.1

CHANGES.md

@@ -1,5 +1,20 @@
 # Change Log
 
+## Version 2.20180918.1 (2018-10-24)
+
+### New feature: Support for Partial Payments in Connect v1
+
+The Connect SDK now supports partial payment functionality for the Connect v1 Transactions API with the addition of a new `Payment` field:
+* `Payment.is_partial` — Indicates whether or not the payment is only partially paid for. If `true`, the payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
+
+`Tender` also includes 2 new fields to help resolve timing around payments with multiple tenders. Invoices that involve partial payment (e.g., requiring a deposit) may include tenders settled well before the entire payment is completed:
+* `Tender.tendered_at` — The time when the tender was accepted by the merchant.
+* `Tender.settled_at` — The time when the tender was captured, in ISO 8601 format. Typically the same as (or within moments of) `tendered_at` unless the tender was part of a delay capture transaction.
+
+The change also makes some behavioral changes to the Connect v1 Payment endpoints:
+* **Create Refunds** rejects requests for invoices that have partial payments pending.
+* **List Payments** takes a new request field, `include_partial` to indicate whether partial payments should be included in the response.
+
 ## Version 2.20180918.0 (2018-09-18)
 
 We have added Connect v2 Inventory API and birthdays in `Customer` entities.

README.md

@@ -18,7 +18,7 @@ Add this dependency to your project's POM:
 <dependency>
     <groupId>com.squareup</groupId>
     <artifactId>connect</artifactId>
-    <version>2.20180918.0</version>
+    <version>2.20180918.1</version>
     <scope>compile</scope>
 </dependency>
 ```
@@ -28,7 +28,7 @@ Add this dependency to your project's POM:
 Add this dependency to your project's build file:
 
 ```groovy
-compile "com.squareup:connect:2.20180918.0"
+compile "com.squareup:connect:2.20180918.1"
 ```
 
 ### Build and Install locally
@@ -47,7 +47,7 @@ At first generate the JAR by executing:
 
 Then manually install the following JARs:
 
-* target/connect-2.20180918.0.jar
+* target/connect-2.20180918.1.jar
 * target/lib/*.jar
 
 ## Getting Started

build.gradle

@@ -2,7 +2,7 @@ apply plugin: 'idea'
 apply plugin: 'eclipse'
 
 group = 'com.squareup'
-version = '2.20180918.0'
+version = '2.20180918.1'
 
 buildscript {
     repositories {

docs/V1Payment.md

@@ -30,6 +30,7 @@ Name | Type | Description | Notes
 **itemizations** | [**List<V1PaymentItemization>**](V1PaymentItemization.md) | The items purchased in the payment. |  [optional]
 **surchargeMoney** | [**V1Money**](V1Money.md) | The total of all surcharges applied to the payment. |  [optional]
 **surcharges** | [**List<V1PaymentSurcharge>**](V1PaymentSurcharge.md) | A list of all surcharges associated with the payment. |  [optional]
+**isPartial** | **Boolean** | Indicates whether or not the payment is only partially paid for. If true, this payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed. |  [optional]
 
 
 

docs/V1PaymentSurcharge.md

@@ -11,7 +11,7 @@ Name | Type | Description | Notes
 **type** | [**TypeEnum**](#TypeEnum) | Indicates the source of the surcharge. For example, if it was applied as an automatic gratuity for a large group. |  [optional]
 **taxable** | **Boolean** | Indicates whether the surcharge is taxable. |  [optional]
 **taxes** | [**List<V1PaymentTax>**](V1PaymentTax.md) | The list of taxes that should be applied to the surcharge. |  [optional]
-**surchargeId** | **String** |  |  [optional]
+**surchargeId** | **String** | A Square-issued unique identifier associated with the surcharge. |  [optional]
 
 
 <a name="TypeEnum"></a>

docs/V1Tender.md

@@ -15,6 +15,8 @@ Name | Type | Description | Notes
 **paymentNote** | **String** | Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the type: OTHER. |  [optional]
 **totalMoney** | [**V1Money**](V1Money.md) | The total amount of money provided in this form of tender. |  [optional]
 **tenderedMoney** | [**V1Money**](V1Money.md) | The amount of total_money applied to the payment. |  [optional]
+**tenderedAt** | **String** | The time when the tender was created, in ISO 8601 format. |  [optional]
+**settledAt** | **String** | The time when the tender was settled, in ISO 8601 format. |  [optional]
 **changeBackMoney** | [**V1Money**](V1Money.md) | The amount of total_money returned to the buyer as change. |  [optional]
 **refundedMoney** | [**V1Money**](V1Money.md) | The total of all refunds applied to this tender. This amount is always negative or zero. |  [optional]
 **isExchange** | **Boolean** | Indicates whether or not the tender is associated with an exchange. If is_exchange is true, the tender represents the value of goods returned in an exchange not the actual money paid. The exchange value reduces the tender amounts needed to pay for items purchased in the exchange. |  [optional]

docs/V1TransactionsApi.md

@@ -186,7 +186,7 @@ Name | Type | Description  | Notes
 
 <a name="listPayments"></a>
 # **listPayments**
-> List&lt;V1Payment&gt; listPayments(locationId, order, beginTime, endTime, limit, batchToken)
+> List&lt;V1Payment&gt; listPayments(locationId, order, beginTime, endTime, limit, batchToken, includePartial)
 
 Provides summary information for all payments taken by a merchant or any of the merchant&#39;s mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.
 
@@ -214,8 +214,9 @@ String beginTime = "beginTime_example"; // String | The beginning of the request
 String endTime = "endTime_example"; // String | The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
 Integer limit = 56; // Integer | The maximum number of payments to return in a single response. This value cannot exceed 200.
 String batchToken = "batchToken_example"; // String | A pagination cursor to retrieve the next set of results for your original query to the endpoint.
+Boolean includePartial = true; // Boolean | Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
 try {
-    List<V1Payment> result = apiInstance.listPayments(locationId, order, beginTime, endTime, limit, batchToken);
+    List<V1Payment> result = apiInstance.listPayments(locationId, order, beginTime, endTime, limit, batchToken, includePartial);
     System.out.println(result);
 } catch (ApiException e) {
     System.err.println("Exception when calling V1TransactionsApi#listPayments");
@@ -233,6 +234,7 @@ Name | Type | Description  | Notes
  **endTime** | **String**| The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. | [optional]
  **limit** | **Integer**| The maximum number of payments to return in a single response. This value cannot exceed 200. | [optional]
  **batchToken** | **String**| A pagination cursor to retrieve the next set of results for your original query to the endpoint. | [optional]
+ **includePartial** | **Boolean**| Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. | [optional]
 
 ### Return type
 

pom.xml

@@ -5,7 +5,7 @@
   <artifactId>connect</artifactId>
   <packaging>jar</packaging>
   <name>connect</name>
-  <version>2.20180918.0</version>
+  <version>2.20180918.1</version>
   <url>https://github.com/square/connect-java-sdk/</url>
   <description>Java client library for the Square Connect API</description>
   <scm>

src/main/java/com/squareup/connect/ApiClient.java

@@ -73,7 +73,7 @@ public ApiClient() {
     this.dateFormat = new RFC3339DateFormat();
 
     // Set default User-Agent.
-    setUserAgent("Square-Connect-Java/2.20180918.0");
+    setUserAgent("Square-Connect-Java/2.20180918.1");
 
     // Setup authentications (key: authentication name, value: authentication).
     authentications = new HashMap<String, Authentication>();

src/main/java/com/squareup/connect/api/V1TransactionsApi.java

@@ -329,10 +329,11 @@ public List<V1Order> listOrders(String locationId, String order, Integer limit,
    * @param endTime The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. (optional)
    * @param limit The maximum number of payments to return in a single response. This value cannot exceed 200. (optional)
    * @param batchToken A pagination cursor to retrieve the next set of results for your original query to the endpoint. (optional)
+   * @param includePartial Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. (optional)
    * @return List&lt;V1Payment&gt;
    * @throws ApiException if fails to make API call
    */
-  public List<V1Payment> listPayments(String locationId, String order, String beginTime, String endTime, Integer limit, String batchToken) throws ApiException {
+  public List<V1Payment> listPayments(String locationId, String order, String beginTime, String endTime, Integer limit, String batchToken, Boolean includePartial) throws ApiException {
     Object localVarPostBody = null;
 
     // verify the required parameter 'locationId' is set
@@ -353,6 +354,7 @@ public List<V1Payment> listPayments(String locationId, String order, String begi
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "end_time", endTime));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "limit", limit));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "batch_token", batchToken));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "include_partial", includePartial));
 
 
 
@@ -382,10 +384,11 @@ public List<V1Payment> listPayments(String locationId, String order, String begi
    * @param endTime The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time. (optional)
    * @param limit The maximum number of payments to return in a single response. This value cannot exceed 200. (optional)
    * @param batchToken A pagination cursor to retrieve the next set of results for your original query to the endpoint. (optional)
+   * @param includePartial Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed. (optional)
    * @return CompleteResponse<List<V1Payment>>
    * @throws ApiException if fails to make API call
    */
-  public CompleteResponse<List<V1Payment>>listPaymentsWithHttpInfo(String locationId, String order, String beginTime, String endTime, Integer limit, String batchToken) throws ApiException {
+  public CompleteResponse<List<V1Payment>>listPaymentsWithHttpInfo(String locationId, String order, String beginTime, String endTime, Integer limit, String batchToken, Boolean includePartial) throws ApiException {
     Object localVarPostBody = null;
 
     // verify the required parameter 'locationId' is set
@@ -407,6 +410,7 @@ public List<V1Payment> listPayments(String locationId, String order, String begi
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "end_time", endTime));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "limit", limit));
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "batch_token", batchToken));
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "include_partial", includePartial));
 
 
 

src/main/java/com/squareup/connect/models/V1Payment.java

@@ -112,6 +112,9 @@ public class V1Payment {
   @JsonProperty("surcharges")
   private List<V1PaymentSurcharge> surcharges = new ArrayList<V1PaymentSurcharge>();
 
+  @JsonProperty("is_partial")
+  private Boolean isPartial = null;
+
   public V1Payment id(String id) {
     this.id = id;
     return this;
@@ -610,6 +613,24 @@ public void setSurcharges(List<V1PaymentSurcharge> surcharges) {
     this.surcharges = surcharges;
   }
 
+  public V1Payment isPartial(Boolean isPartial) {
+    this.isPartial = isPartial;
+    return this;
+  }
+
+   /**
+   * Indicates whether or not the payment is only partially paid for. If true, this payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
+   * @return isPartial
+  **/
+  @ApiModelProperty(value = "Indicates whether or not the payment is only partially paid for. If true, this payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed.")
+  public Boolean getIsPartial() {
+    return isPartial;
+  }
+
+  public void setIsPartial(Boolean isPartial) {
+    this.isPartial = isPartial;
+  }
+
 
   @Override
   public boolean equals(java.lang.Object o) {
@@ -645,12 +666,13 @@ public boolean equals(java.lang.Object o) {
         Objects.equals(this.refunds, v1Payment.refunds) &&
         Objects.equals(this.itemizations, v1Payment.itemizations) &&
         Objects.equals(this.surchargeMoney, v1Payment.surchargeMoney) &&
-        Objects.equals(this.surcharges, v1Payment.surcharges);
+        Objects.equals(this.surcharges, v1Payment.surcharges) &&
+        Objects.equals(this.isPartial, v1Payment.isPartial);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(id, merchantId, createdAt, creatorId, device, paymentUrl, receiptUrl, inclusiveTaxMoney, additiveTaxMoney, taxMoney, tipMoney, discountMoney, totalCollectedMoney, processingFeeMoney, netTotalMoney, refundedMoney, swedishRoundingMoney, grossSalesMoney, netSalesMoney, inclusiveTax, additiveTax, tender, refunds, itemizations, surchargeMoney, surcharges);
+    return Objects.hash(id, merchantId, createdAt, creatorId, device, paymentUrl, receiptUrl, inclusiveTaxMoney, additiveTaxMoney, taxMoney, tipMoney, discountMoney, totalCollectedMoney, processingFeeMoney, netTotalMoney, refundedMoney, swedishRoundingMoney, grossSalesMoney, netSalesMoney, inclusiveTax, additiveTax, tender, refunds, itemizations, surchargeMoney, surcharges, isPartial);
   }
 
 
@@ -685,6 +707,7 @@ public String toString() {
     sb.append("    itemizations: ").append(toIndentedString(itemizations)).append("\n");
     sb.append("    surchargeMoney: ").append(toIndentedString(surchargeMoney)).append("\n");
     sb.append("    surcharges: ").append(toIndentedString(surcharges)).append("\n");
+    sb.append("    isPartial: ").append(toIndentedString(isPartial)).append("\n");
     sb.append("}");
     return sb.toString();
   }

src/main/java/com/squareup/connect/models/V1PaymentSurcharge.java

@@ -222,10 +222,10 @@ public V1PaymentSurcharge surchargeId(String surchargeId) {
   }
 
    /**
-   * Get surchargeId
+   * A Square-issued unique identifier associated with the surcharge.
    * @return surchargeId
   **/
-  @ApiModelProperty(value = "")
+  @ApiModelProperty(value = "A Square-issued unique identifier associated with the surcharge.")
   public String getSurchargeId() {
     return surchargeId;
   }

src/main/java/com/squareup/connect/models/V1Tender.java

@@ -185,6 +185,12 @@ public static EntryMethodEnum fromValue(String text) {
   @JsonProperty("tendered_money")
   private V1Money tenderedMoney = null;
 
+  @JsonProperty("tendered_at")
+  private String tenderedAt = null;
+
+  @JsonProperty("settled_at")
+  private String settledAt = null;
+
   @JsonProperty("change_back_money")
   private V1Money changeBackMoney = null;
 
@@ -392,6 +398,42 @@ public void setTenderedMoney(V1Money tenderedMoney) {
     this.tenderedMoney = tenderedMoney;
   }
 
+  public V1Tender tenderedAt(String tenderedAt) {
+    this.tenderedAt = tenderedAt;
+    return this;
+  }
+
+   /**
+   * The time when the tender was created, in ISO 8601 format.
+   * @return tenderedAt
+  **/
+  @ApiModelProperty(value = "The time when the tender was created, in ISO 8601 format.")
+  public String getTenderedAt() {
+    return tenderedAt;
+  }
+
+  public void setTenderedAt(String tenderedAt) {
+    this.tenderedAt = tenderedAt;
+  }
+
+  public V1Tender settledAt(String settledAt) {
+    this.settledAt = settledAt;
+    return this;
+  }
+
+   /**
+   * The time when the tender was settled, in ISO 8601 format.
+   * @return settledAt
+  **/
+  @ApiModelProperty(value = "The time when the tender was settled, in ISO 8601 format.")
+  public String getSettledAt() {
+    return settledAt;
+  }
+
+  public void setSettledAt(String settledAt) {
+    this.settledAt = settledAt;
+  }
+
   public V1Tender changeBackMoney(V1Money changeBackMoney) {
     this.changeBackMoney = changeBackMoney;
     return this;
@@ -467,14 +509,16 @@ public boolean equals(java.lang.Object o) {
         Objects.equals(this.paymentNote, v1Tender.paymentNote) &&
         Objects.equals(this.totalMoney, v1Tender.totalMoney) &&
         Objects.equals(this.tenderedMoney, v1Tender.tenderedMoney) &&
+        Objects.equals(this.tenderedAt, v1Tender.tenderedAt) &&
+        Objects.equals(this.settledAt, v1Tender.settledAt) &&
         Objects.equals(this.changeBackMoney, v1Tender.changeBackMoney) &&
         Objects.equals(this.refundedMoney, v1Tender.refundedMoney) &&
         Objects.equals(this.isExchange, v1Tender.isExchange);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(id, type, name, employeeId, receiptUrl, cardBrand, panSuffix, entryMethod, paymentNote, totalMoney, tenderedMoney, changeBackMoney, refundedMoney, isExchange);
+    return Objects.hash(id, type, name, employeeId, receiptUrl, cardBrand, panSuffix, entryMethod, paymentNote, totalMoney, tenderedMoney, tenderedAt, settledAt, changeBackMoney, refundedMoney, isExchange);
   }
 
 
@@ -494,6 +538,8 @@ public String toString() {
     sb.append("    paymentNote: ").append(toIndentedString(paymentNote)).append("\n");
     sb.append("    totalMoney: ").append(toIndentedString(totalMoney)).append("\n");
     sb.append("    tenderedMoney: ").append(toIndentedString(tenderedMoney)).append("\n");
+    sb.append("    tenderedAt: ").append(toIndentedString(tenderedAt)).append("\n");
+    sb.append("    settledAt: ").append(toIndentedString(settledAt)).append("\n");
     sb.append("    changeBackMoney: ").append(toIndentedString(changeBackMoney)).append("\n");
     sb.append("    refundedMoney: ").append(toIndentedString(refundedMoney)).append("\n");
     sb.append("    isExchange: ").append(toIndentedString(isExchange)).append("\n");

src/test/java/com/squareup/connect/api/V1TransactionsApiTest.java

@@ -106,7 +106,7 @@ public void listPaymentsTest() throws ApiException {
         String endTime = null;
         Integer limit = null;
         String batchToken = null;
-        List<V1Payment> response = api.listPayments(locationId, order, beginTime, endTime, limit, batchToken);
+        List<V1Payment> response = api.listPayments(locationId, order, beginTime, endTime, limit, batchToken, true);
 
         // TODO: test validations
     }