Release/2.7.0 (#35)

* Release 2.7.0

CHANGES.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## Version 2.7.0 (2018-04-26)
+
+### New features: Transactions API and Payments API
+
+The Transactions API in Connect v2 now includes payment and refund information from exchanges.
+
+* `ListTransactions` now includes payment information from sales and exchanges and refund
+information from returns and exchanges.
+* `ListRefunds` now includes refunds that result from exchanges in addition to partial refunds and
+itemized returns through Square's Point of Sale applications.
+
+The Payments API in Connect v1 now includes payment and refund information from exchanges.
+
+* `ListPayments` now includes refunds that are generated from exchanges to account for the
+value of returned goods.
+* `ListRefunds` now returns an approximate number of refunds (default: 100, max: 200).
+The response may contain more results than the prescribed limit when refunds are made
+simultaneously to multiple tenders in a payment or when refunds are generated from exchanges
+to account for the value of returned goods.
+* `is_exchange` is added to `V1Refund` and `V1Tender`. Refunds and tenders marked in this way
+represent the value of returned goods in an exchange, rather than actual money movement.
+
 ## Version 2.6.1 (2018-03-28)
 
 * Updates user-agent header

README.md

@@ -1,6 +1,6 @@
 # Square Connect Java SDK [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.squareup/connect/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.squareup/connect)
 
-**If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new [slack community for Square Developers](https://docs.google.com/forms/d/e/1FAIpQLSfAZGIEZoNs-XryKqUoW3atFQHdQw5UqXLMOVPq3V4DEq-AJw/viewform?usp=sf_link#response=ACYDBNj5LFgPy8Tcac2gSgv_IjXvgWsPy2CO2xTXwnc0OSSxCvWFgc7SCDHvVQ)**
+**If you have feedback about the new SDKs, or just want to talk to other Square Developers, request an invite to the new [slack community for Square Developers](https://squ.re/2GB8GHk)**
 
 ## Requirements
 
@@ -18,7 +18,7 @@ Add this dependency to your project's POM:
 <dependency>
     <groupId>com.squareup</groupId>
     <artifactId>connect</artifactId>
-    <version>2.6.1</version>
+    <version>2.7.0</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.6.1"
+compile "com.squareup:connect:2.7.0"
 ```
 
 ### Build and Install locally
@@ -47,7 +47,7 @@ At first generate the JAR by executing:
 
 Then manually install the following JARs:
 
-* target/connect-2.6.1.jar
+* target/connect-2.7.0.jar
 * target/lib/*.jar
 
 ## Getting Started

build.gradle

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

docs/TransactionsApi.md

@@ -186,7 +186,7 @@ Name | Type | Description  | Notes
 
 ListRefunds
 
-Lists refunds for one of a business's locations.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
+Lists refunds for one of a business's locations.  In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
 
 ### Example
 ```java
@@ -247,7 +247,7 @@ Name | Type | Description  | Notes
 
 ListTransactions
 
-Lists transactions for a particular location.  Max results per [page](#paginatingresults): 50
+Lists transactions for a particular location.  Transactions include payment information from sales and exchanges and refund information from returns and exchanges.  Max results per [page](#paginatingresults): 50
 
 ### Example
 ```java

docs/V1Payment.md

@@ -26,7 +26,7 @@ Name | Type | Description | Notes
 **inclusiveTax** | [**List<V1PaymentTax>**](V1PaymentTax.md) | All of the inclusive taxes associated with the payment. |  [optional]
 **additiveTax** | [**List<V1PaymentTax>**](V1PaymentTax.md) | All of the additive taxes associated with the payment. |  [optional]
 **tender** | [**List<V1Tender>**](V1Tender.md) | All of the additive taxes associated with the payment. |  [optional]
-**refunds** | [**List<V1Refund>**](V1Refund.md) | All of the refunds applied to the payment. |  [optional]
+**refunds** | [**List<V1Refund>**](V1Refund.md) | All of the refunds applied to the payment. Note that the value of all refunds on a payment can exceed the value of all tenders if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange. |  [optional]
 **itemizations** | [**List<V1PaymentItemization>**](V1PaymentItemization.md) | The items purchased in the payment. |  [optional]
 
 

docs/V1Refund.md

@@ -7,10 +7,11 @@ Name | Type | Description | Notes
 **type** | [**TypeEnum**](#TypeEnum) | The type of refund  |  [optional]
 **reason** | **String** | The merchant-specified reason for the refund. |  [optional]
 **refundedMoney** | [**V1Money**](V1Money.md) | The amount of money refunded. This amount is always negative. |  [optional]
-**createdAt** | **String** | The time when the merchant initiated the refund for Square to process, in ISO 8601 format.. |  [optional]
+**createdAt** | **String** | The time when the merchant initiated the refund for Square to process, in ISO 8601 format. |  [optional]
 **processedAt** | **String** | The time when Square processed the refund on behalf of the merchant, in ISO 8601 format. |  [optional]
-**paymentId** | **String** | The Square-issued ID of the payment the refund is applied to. |  [optional]
+**paymentId** | **String** | A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders. |  [optional]
 **merchantId** | **String** |  |  [optional]
+**isExchange** | **Boolean** | Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded. |  [optional]
 
 
 <a name="TypeEnum"></a>

docs/V1Tender.md

@@ -17,6 +17,7 @@ Name | Type | Description | Notes
 **tenderedMoney** | [**V1Money**](V1Money.md) | The amount of total_money applied to the payment. |  [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]
 
 
 <a name="TypeEnum"></a>

docs/V1TransactionsApi.md

@@ -275,7 +275,7 @@ String locationId = "locationId_example"; // String | The ID of the location to
 String order = "order_example"; // String | TThe order in which payments are listed in the response.
 String beginTime = "beginTime_example"; // String | The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
 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.
+Integer limit = 56; // Integer | The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods.
 String batchToken = "batchToken_example"; // String | A pagination cursor to retrieve the next set of results for your original query to the endpoint.
 try {
     List<V1Refund> result = apiInstance.listRefunds(locationId, order, beginTime, endTime, limit, batchToken);
@@ -294,7 +294,7 @@ Name | Type | Description  | Notes
  **order** | **String**| TThe order in which payments are listed in the response. | [optional] [enum: ASC, DESC]
  **beginTime** | **String**| The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year. | [optional]
  **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]
+ **limit** | **Integer**| The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods. | [optional]
  **batchToken** | **String**| A pagination cursor to retrieve the next set of results for your original query to the endpoint. | [optional]
 
 ### Return type
@@ -510,7 +510,7 @@ oauth2.setAccessToken("YOUR ACCESS TOKEN");
 
 V1TransactionsApi apiInstance = new V1TransactionsApi();
 String locationId = "locationId_example"; // String | The ID of the payment's associated location.
-String paymentId = "paymentId_example"; // String | The payment's Square-issued ID. You obtain this value from Payment objects returned by the List Payments endpoint, or Settlement objects returned by the List Settlements endpoint.
+String paymentId = "paymentId_example"; // String | The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint.
 try {
     V1Payment result = apiInstance.retrievePayment(locationId, paymentId);
     System.out.println(result);
@@ -525,7 +525,7 @@ try {
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
  **locationId** | **String**| The ID of the payment&#39;s associated location. |
- **paymentId** | **String**| The payment&#39;s Square-issued ID. You obtain this value from Payment objects returned by the List Payments endpoint, or Settlement objects returned by the List Settlements endpoint. |
+ **paymentId** | **String**| The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint. |
 
 ### Return type
 

pom.xml

@@ -5,7 +5,7 @@
   <artifactId>connect</artifactId>
   <packaging>jar</packaging>
   <name>connect</name>
-  <version>2.6.1</version>
+  <version>2.7.0</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.6.1");
+    setUserAgent("Square-Connect-Java/2.7.0");
 
     // Setup authentications (key: authentication name, value: authentication).
     authentications = new HashMap<String, Authentication>();

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

@@ -355,7 +355,7 @@ public CreateRefundResponse createRefund(String locationId, String transactionId
   }
   /**
    * ListRefunds
-   * Lists refunds for one of a business's locations.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
+   * Lists refunds for one of a business's locations.  In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
    * @param locationId The ID of the location to list refunds for. (required)
    * @param beginTime The beginning of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time minus one year. (optional)
    * @param endTime The end of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time. (optional)
@@ -407,7 +407,7 @@ public ListRefundsResponse listRefunds(String locationId, String beginTime, Stri
 
   /**
    * ListRefunds
-   * Lists refunds for one of a business's locations.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
+   * Lists refunds for one of a business's locations.  In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.  Refunds with a `status` of `PENDING` are not currently included in this endpoint's response.  Max results per [page](#paginatingresults): 50
    * @param locationId The ID of the location to list refunds for. (required)
    * @param beginTime The beginning of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time minus one year. (optional)
    * @param endTime The end of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time. (optional)
@@ -457,7 +457,7 @@ public ListRefundsResponse listRefunds(String locationId, String beginTime, Stri
   }
   /**
    * ListTransactions
-   * Lists transactions for a particular location.  Max results per [page](#paginatingresults): 50
+   * Lists transactions for a particular location.  Transactions include payment information from sales and exchanges and refund information from returns and exchanges.  Max results per [page](#paginatingresults): 50
    * @param locationId The ID of the location to list transactions for. (required)
    * @param beginTime The beginning of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time minus one year. (optional)
    * @param endTime The end of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time. (optional)
@@ -509,7 +509,7 @@ public ListTransactionsResponse listTransactions(String locationId, String begin
 
   /**
    * ListTransactions
-   * Lists transactions for a particular location.  Max results per [page](#paginatingresults): 50
+   * Lists transactions for a particular location.  Transactions include payment information from sales and exchanges and refund information from returns and exchanges.  Max results per [page](#paginatingresults): 50
    * @param locationId The ID of the location to list transactions for. (required)
    * @param beginTime The beginning of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time minus one year. (optional)
    * @param endTime The end of the requested reporting period, in RFC 3339 format.  See [Date ranges](#dateranges) for details on date inclusivity/exclusivity.  Default value: The current time. (optional)