Merge pull request #25 from square/release/6.4.0.20200923

release

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## Version 6.4.0.20200923 (2020-09-23)
+## Existing API updates 
+* Invoices API (beta)
+  * [InvoiceStatus](https://developer.squareup.com/reference/square_2020-09-23/enums/InvoiceStatus) enum. Added the `PAYMENT_PENDING` value. Previously, the Invoices API returned a `PAID` or `PARTIALLY_PAID` status for invoices in a payment pending state. Now, the Invoices API returns a `PAYMENT_PENDING` status for all invoices in a payment pending state, including those previously returned as `PAID` or `PARTIALLY_PAID`.
+* Payments API 
+  * [ListPayment](https://developer.squareup.com/reference/square_2020-09-23/payments-api/list-payments). The endpoint now supports the `limit` parameter.
+* Refunds API
+  * [ListPaymentRefunds](https://developer.squareup.com/reference/square_2020-09-23/refunds-api/list-payment-refunds). The endpoint now supports the `limit` parameter.
+* [DeviceDetails](https://developer.squareup.com/reference/square_2020-09-23/objects/DeviceDetails#definition__property-device_installation_id). The object now includes the `device_installation_id` field.
+## Documentation updates
+* [Payment status.](https://developer.squareup.com/docs/payments-api/take-payments#payment-status) Added details about the `Payment.status` changes and how the status relates to the seller receiving the funds.
+* [Refund status.](https://developer.squareup.com/docs/payments-api/refund-payments#refund-status) Added details about the `PaymentRefund.status` changes and how the status relates to the cardholder receiving the funds.
+* [CreateRefund errors.](https://developer.squareup.com/docs/payments-api/error-codes#createrefund-errors) Added documentation for the `REFUND_DECLINED` error code.
+
 ## Version 6.3.0.20200826 (2020-08-26)
 ## Existing API updates
 * Orders API
@@ -254,4 +268,4 @@ All SDKs have been updated to support the following changes:
 * __Beta release:__ SDKs updated to support the new [CashDrawerShifts](cashdrawershift-api/reporting) API.
 
 * Square now follows the semantic versioning scheme for all SDKs except PHP and Node.js. This versioning scheme uses three numbers to delineate MAJOR, MINOR, and PATCH versions of our SDK. In addition, the SDK version also includes the API version so you know what Square API version the SDK is related to. For more information, see [Versioning and SDKs](build-basics/versioning-overview#versioning-and-sdks).
-* Java, .Net, Python, and Ruby SDKs are now version 4.0.0. Java and .Net SDKs have breaking changes in version 4.0.0. Ruby and Python do not have breaking changes.
+* Java, .Net, Python, and Ruby SDKs are now version 4.0.0. Java and .Net SDKs have breaking changes in version 4.0.0. Ruby and Python do not have breaking changes.

README.md

@@ -33,7 +33,7 @@ Install the client dynamically by adding a dependency to the POM for your projec
 <dependency>
     <groupId>com.squareup</groupId>
     <artifactId>square</artifactId>
-    <version>6.3.0.20200826</version>
+    <version>6.4.0.20200923</version>
 </dependency>
 ```
 
@@ -330,4 +330,4 @@ You can also use the Square API to create applications or services that work wit
 [V1 Items]: doc/v1-items.md
 [Team]: doc/team.md
 [Transactions]: doc/transactions.md
-[Subscriptions]: doc/subscriptions.md
+[Subscriptions]: doc/subscriptions.md

doc/disputes.md

@@ -23,7 +23,9 @@ DisputesApi disputesApi = client.getDisputesApi();
 ## List Disputes
 
 Returns a list of disputes associated
-with a particular account.
+with a particular account.
+
+Access dispute information: [https://developer.squareup.com/docs/disputes-api/process-disputes#access-dispute-information](https://developer.squareup.com/docs/disputes-api/process-disputes#access-dispute-information)
 
 ```java
 CompletableFuture<ListDisputesResponse> listDisputesAsync(
@@ -100,7 +102,8 @@ dispute state to ACCEPTED.
 Square debits the disputed amount from the seller’s Square
 account. If the Square account balance does not have
 sufficient funds, Square debits the associated bank account.
-For an overview of the Disputes API, see [Overview](https://developer.squareup.com/docs/docs/disputes-api/overview).
+
+Accept a dispute: [https://developer.squareup.com/docs/disputes-api/process-disputes#accept-a-dispute](https://developer.squareup.com/docs/disputes-api/process-disputes#accept-a-dispute)
 
 ```java
 CompletableFuture<AcceptDisputeResponse> acceptDisputeAsync(
@@ -245,7 +248,8 @@ disputesApi.retrieveDisputeEvidenceAsync(disputeId, evidenceId).thenAccept(resul
 Uploads a file to use as evidence in a dispute challenge. The endpoint accepts
 HTTP multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG,
 and TIFF formats.
-For more information, see [Challenge a Dispute](https://developer.squareup.com/docs/docs/disputes-api/process-disputes#challenge-a-dispute).
+
+Challenge a dispute: [https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute](https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute)
 
 ```java
 CompletableFuture<CreateDisputeEvidenceFileResponse> createDisputeEvidenceFileAsync(
@@ -287,8 +291,9 @@ disputesApi.createDisputeEvidenceFileAsync(disputeId, request, imageFile).thenAc
 
 ## Create Dispute Evidence Text
 
-Uploads text to use as evidence for a dispute challenge. For more information, see
-[Challenge a Dispute](https://developer.squareup.com/docs/docs/disputes-api/process-disputes#challenge-a-dispute).
+Uploads text to use as evidence for a dispute challenge.
+
+Challenge a dispute: [https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute](https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute)
 
 ```java
 CompletableFuture<CreateDisputeEvidenceTextResponse> createDisputeEvidenceTextAsync(
@@ -334,8 +339,9 @@ evidence uploaded using the
 [CreateDisputeEvidenceFile](https://developer.squareup.com/docs/reference/square/disputes-api/create-dispute-evidence-file) and
 [CreateDisputeEvidenceText](https://developer.squareup.com/docs/reference/square/disputes-api/create-dispute-evidence-text) endpoints,
 and evidence automatically provided by Square, when
-available. For more information, see
-[Challenge a Dispute](https://developer.squareup.com/docs/docs/disputes-api/process-disputes#challenge-a-dispute).
+available.
+
+Challenge a dispute: [https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute](https://developer.squareup.com/docs/disputes-api/process-disputes#challenge-a-dispute)
 
 ```java
 CompletableFuture<SubmitEvidenceResponse> submitEvidenceAsync(

doc/invoices.md

@@ -24,7 +24,8 @@ InvoicesApi invoicesApi = client.getInvoicesApi();
 Returns a list of invoices for a given location. The response 
 is paginated. If truncated, the response includes a `cursor` that you    
 use in a subsequent request to fetch the next set of invoices.
-For more information about retrieving invoices, see [Retrieve invoices](https://developer.squareup.com/docs/docs/invoices-api/overview#retrieve-invoices).
+
+Retrieve an invoice: [https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice)
 
 ```java
 CompletableFuture<ListInvoicesResponse> listInvoicesAsync(
@@ -66,8 +67,9 @@ Creates a draft [invoice](#type-invoice)
 for an order created using the Orders API.
 
 A draft invoice remains in your account and no action is taken. 
-You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file). 
-For more information, see [Manage Invoices Using the Invoices API](https://developer.squareup.com/docs/docs/invoices-api/overview).
+You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).
+
+Create and publish an invoice: [https://developer.squareup.com/docs/invoices-api/overview#create-and-publish-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#create-and-publish-an-invoice)
 
 ```java
 CompletableFuture<CreateInvoiceResponse> createInvoiceAsync(
@@ -162,8 +164,9 @@ retrieve invoices. In the current implementation, you can only specify one locat
 optionally one customer.
 
 The response is paginated. If truncated, the response includes a `cursor` 
-that you use in a subsequent request to fetch the next set of invoices. 
-For more information about retrieving invoices, see [Retrieve invoices](https://developer.squareup.com/docs/docs/invoices-api/overview#retrieve-invoices).
+that you use in a subsequent request to fetch the next set of invoices.
+
+Retrieve an invoice: [https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice)
 
 ```java
 CompletableFuture<SearchInvoicesResponse> searchInvoicesAsync(
@@ -218,7 +221,9 @@ invoicesApi.searchInvoicesAsync(body).thenAccept(result -> {
 Deletes the specified invoice. When an invoice is deleted, the 
 associated Order status changes to CANCELED. You can only delete a draft 
 invoice (you cannot delete an invoice scheduled for publication, or a 
-published invoice).
+published invoice).
+
+Delete an invoice: [https://developer.squareup.com/docs/invoices-api/overview#delete-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#delete-an-invoice)
 
 ```java
 CompletableFuture<DeleteInvoiceResponse> deleteInvoiceAsync(
@@ -253,7 +258,9 @@ invoicesApi.deleteInvoiceAsync(invoiceId, version).thenAccept(result -> {
 
 ## Get Invoice
 
-Retrieves an invoice by invoice ID.
+Retrieves an invoice by invoice ID.
+
+Retrieve an invoice: [https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#retrieve-an-invoice)
 
 ```java
 CompletableFuture<GetInvoiceResponse> getInvoiceAsync(
@@ -288,8 +295,9 @@ invoicesApi.getInvoiceAsync(invoiceId).thenAccept(result -> {
 Updates an invoice by modifying field values, clearing field values, or both 
 as specified in the request. 
 There are no restrictions to updating an invoice in a draft state. 
-However, there are guidelines for updating a published invoice. 
-For more information, see [Update an invoice](https://developer.squareup.com/docs/docs/invoices-api/overview#update-an-invoice).
+However, there are guidelines for updating a published invoice.
+
+Update an invoice: [https://developer.squareup.com/docs/invoices-api/overview#update-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#update-an-invoice)
 
 ```java
 CompletableFuture<UpdateInvoiceResponse> updateInvoiceAsync(
@@ -371,7 +379,9 @@ invoicesApi.updateInvoiceAsync(invoiceId, body).thenAccept(result -> {
 Cancels an invoice. The seller cannot collect payments for 
 the canceled invoice.
 
-You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
+You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
+
+Cancel an invoice: [https://developer.squareup.com/docs/invoices-api/overview#cancel-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#cancel-an-invoice)
 
 ```java
 CompletableFuture<CancelInvoiceResponse> cancelInvoiceAsync(
@@ -420,8 +430,7 @@ based on the invoice configuration. For example, the status changes to `UNPAID`
 Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the 
 invoice amount).
 
-For more information, see 
-[Create and publish an invoice](https://developer.squareup.com/docs/docs/invoices-api/overview#create-and-publish-an-invoice).
+Create and publish an invoice: [https://developer.squareup.com/docs/invoices-api/overview#create-and-publish-an-invoice](https://developer.squareup.com/docs/invoices-api/overview#create-and-publish-an-invoice)
 
 ```java
 CompletableFuture<PublishInvoiceResponse> publishInvoiceAsync(

doc/models/create-payment-request.md

@@ -19,7 +19,7 @@ For information about application fees in a payment, see
 | Name | Type | Tags | Description | Getter |
 |  --- | --- | --- | --- | --- |
 | `SourceId` | `String` |  | The ID for the source of funds for this payment.  This can be a nonce<br>generated by the Payment Form or a card on file made with the Customers API. | String getSourceId() |
-| `IdempotencyKey` | `String` |  | A unique string that identifies this CreatePayment request. Keys can be any valid string<br>but must be unique for every CreatePayment request.<br><br>Max: 45 characters<br><br>See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | String getIdempotencyKey() |
+| `IdempotencyKey` | `String` |  | A unique string that identifies this CreatePayment request. Keys can be any valid string<br>but must be unique for every CreatePayment request.<br><br>Max: 45 characters<br><br>Note: The number of allowed characters might be less than the stated maximum, if multi-byte<br>characters are used.<br><br>See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | String getIdempotencyKey() |
 | `AmountMoney` | [`Money`](/doc/models/money.md) |  | Represents an amount of money. `Money` fields can be signed or unsigned.<br>Fields that do not explicitly define whether they are signed or unsigned are<br>considered unsigned and can only hold positive amounts. For signed fields, the<br>sign of the value indicates the purpose of the money transfer. See<br>[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)<br>for more information. | Money getAmountMoney() |
 | `TipMoney` | [`Money`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.<br>Fields that do not explicitly define whether they are signed or unsigned are<br>considered unsigned and can only hold positive amounts. For signed fields, the<br>sign of the value indicates the purpose of the money transfer. See<br>[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)<br>for more information. | Money getTipMoney() |
 | `AppFeeMoney` | [`Money`](/doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.<br>Fields that do not explicitly define whether they are signed or unsigned are<br>considered unsigned and can only hold positive amounts. For signed fields, the<br>sign of the value indicates the purpose of the money transfer. See<br>[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)<br>for more information. | Money getAppFeeMoney() |

doc/models/device-details.md

@@ -11,13 +11,15 @@ Details about the device that took the payment.
 | Name | Type | Tags | Description | Getter |
 |  --- | --- | --- | --- | --- |
 | `DeviceId` | `String` | Optional | Square-issued ID of the device. | String getDeviceId() |
+| `DeviceInstallationId` | `String` | Optional | Square-issued installation ID for the device. | String getDeviceInstallationId() |
 | `DeviceName` | `String` | Optional | The name of the device set by the merchant. | String getDeviceName() |
 
 ### Example (as JSON)
 
 ```json
 {
   "device_id": "device_id6",
+  "device_installation_id": "device_installation_id8",
   "device_name": "device_name2"
 }
 ```

doc/models/invoice-status.md

@@ -10,13 +10,14 @@ Indicates the status of an invoice.
 
 | Name | Description |
 |  --- | --- |
-| `DRAFT` | The invoice is a draft. You must publish a draft invoice before Square can process it.<br>A draft invoice has no public_url, so it is not available to customers. |
+| `DRAFT` | The invoice is a draft. You must publish a draft invoice before Square can process it.<br>A draft invoice has no `public_url`, so it is not available to customers. |
 | `UNPAID` | The invoice is published but not yet paid. |
-| `SCHEDULED` | The invoice is scheduled to be processed. On scheduled date,<br>Square emails the invoice (if the `request_method` is EMAIL),<br>charge the customer's card (if `request_method` is CHARGE_CARD_ON_FILE),<br>or take no action (if the `request_method` is SHARE_MANUALLY).<br>The invoice status then changes accordingly (`UNPAID`, `PAID`, or `PARTIALLY_PAID`). |
+| `SCHEDULED` | The invoice is scheduled to be processed. On the scheduled date,<br>Square emails the invoice (if the `request_method` is `EMAIL`),<br>charges the customer's card (if the `request_method` is `CHARGE_CARD_ON_FILE`),<br>or takes no action (if the `request_method` is `SHARE_MANUALLY`).<br>The invoice status then changes accordingly (`UNPAID`, `PAID`, or `PARTIALLY_PAID`). |
 | `PARTIALLY_PAID` | A partial payment is received for the invoice. |
 | `PAID` | The customer paid the invoice in full. |
 | `PARTIALLY_REFUNDED` | The invoice is paid (or partially paid) and some but not all the amount paid is<br>refunded. |
 | `REFUNDED` | The full amount that the customer paid for the invoice is refunded. |
 | `CANCELED` | The invoice is canceled. Square no longer requests payments from the customer.<br>The `public_url` page remains and is accessible, but it displays the invoice<br>as cancelled and does not accept payment. |
 | `FAILED` | Square canceled the invoice due to suspicious activity. |
+| `PAYMENT_PENDING` | A payment on the invoice was initiated but has not yet been processed. <br><br>When in this state, invoices cannot be updated and other payments cannot be initiated. |
 

doc/models/list-payment-refunds-request.md

@@ -19,6 +19,7 @@ Max results per page: 100
 | `LocationId` | `String` | Optional | Limit results to the location supplied. By default, results are returned<br>for all locations associated with the merchant. | String getLocationId() |
 | `Status` | `String` | Optional | If provided, only refunds with the given status are returned.<br>For a list of refund status values, see [PaymentRefund](#type-paymentrefund).<br><br>Default: If omitted refunds are returned regardless of status. | String getStatus() |
 | `SourceType` | `String` | Optional | If provided, only refunds with the given source type are returned.<br>- `CARD` - List refunds only for payments where card was specified as payment<br>source.<br><br>Default: If omitted refunds are returned regardless of source type. | String getSourceType() |
+| `Limit` | `Integer` | Optional | Maximum number of results to be returned in a single page.<br>It is possible to receive fewer results than the specified limit on a given page.<br><br>If the supplied value is greater than 100, at most 100 results will be returned.<br><br>Default: `100` | Integer getLimit() |
 
 ### Example (as JSON)