Merge pull request #112 from square/release/4.20200923.4

Release 4.20200923.4

CHANGES.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## Version 4.20200923.4 (2020-09-23T00:00)
+## 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 4.20200826.3 (2020-08-26T00:00)
 ## Existing API updates
 * Orders API

docs/CreatePaymentRequest.md

@@ -8,7 +8,7 @@ Creates a payment from the source (nonce, card on file, etc.)  The `PAYMENTS_WRI
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **source_id** | **String** | The ID for the source of funds for this payment.  This can be a nonce generated by the Payment Form or a card on file made with the Customers API. | 
-**idempotency_key** | **String** | A unique string that identifies this CreatePayment request. Keys can be any valid string but must be unique for every CreatePayment request.  Max: 45 characters  See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | 
+**idempotency_key** | **String** | A unique string that identifies this CreatePayment request. Keys can be any valid string but must be unique for every CreatePayment request.  Max: 45 characters  Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used.  See [Idempotency keys](https://developer.squareup.com/docs/basics/api101/idempotency) for more information. | 
 **amount_money** | [**Money**](Money.md) | The amount of money to accept for this payment, not including `tip_money`.  Must be specified in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See [Working with monetary amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for details.  The currency code must match the currency associated with the business that is accepting the payment. | 
 **tip_money** | [**Money**](Money.md) | The amount designated as a tip, in addition to `amount_money`  Must be specified in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See [Working with monetary amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for details.  The currency code must match the currency associated with the business that is accepting the payment. | [optional] 
 **app_fee_money** | [**Money**](Money.md) | The amount of money the developer is taking as a fee for facilitating the payment on behalf of the seller.  Cannot be more than 90% of the total amount of the Payment.  Must be specified in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See [Working with monetary amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for details.  The fee currency code must match the currency associated with the merchant that is accepting the payment. The application must be from a developer account in the same country, and using the same currency code, as the merchant.  For more information about the application fee scenario, see [Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). | [optional] 

docs/DeviceDetails.md

@@ -8,6 +8,7 @@ Details about the device that took the payment.
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **device_id** | **String** | Square-issued ID of the device. | [optional] 
+**device_installation_id** | **String** | Square-issued installation ID for the device. | [optional] 
 **device_name** | **String** | The name of the device set by the merchant. | [optional] 
 
 

docs/DisputesApi.md

@@ -21,7 +21,7 @@ Method | HTTP request | Description
 
 AcceptDispute
 
-Accepts loss on a dispute. Square returns the disputed amount to the cardholder and updates the 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](/docs/disputes-api/overview).
+Accepts loss on a dispute. Square returns the disputed amount to the cardholder and updates the 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.
 
 ### Example
 ```javascript
@@ -70,7 +70,7 @@ Name | Type | Description  | Notes
 
 CreateDisputeEvidenceText
 
-Uploads text to use as evidence for a dispute challenge. For more information, see [Challenge a Dispute](/docs/disputes-api/process-disputes#challenge-a-dispute).
+Uploads text to use as evidence for a dispute challenge.
 
 ### Example
 ```javascript
@@ -378,7 +378,7 @@ Name | Type | Description  | Notes
 
 SubmitEvidence
 
-Submits evidence to the cardholder's bank.  Before submitting evidence, Square compiles all available evidence. This includes evidence uploaded using the [CreateDisputeEvidenceFile](/reference/square/disputes-api/create-dispute-evidence-file) and [CreateDisputeEvidenceText](/reference/square/disputes-api/create-dispute-evidence-text) endpoints, and evidence automatically provided by Square, when available. For more information, see [Challenge a Dispute](/docs/disputes-api/process-disputes#challenge-a-dispute).
+Submits evidence to the cardholder's bank.  Before submitting evidence, Square compiles all available evidence. This includes evidence uploaded using the [CreateDisputeEvidenceFile](/reference/square/disputes-api/create-dispute-evidence-file) and [CreateDisputeEvidenceText](/reference/square/disputes-api/create-dispute-evidence-text) endpoints, and evidence automatically provided by Square, when available.
 
 ### Example
 ```javascript

docs/InvoiceStatus.md

@@ -21,4 +21,6 @@
 
 * `FAILED` (value: `"FAILED"`)
 
+* `PAYMENT_PENDING` (value: `"PAYMENT_PENDING"`)
+
 

docs/InvoicesApi.md

@@ -73,7 +73,7 @@ Name | Type | Description  | Notes
 
 CreateInvoice
 
-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](/docs/invoices-api/overview).
+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).
 
 ### Example
 ```javascript
@@ -224,7 +224,7 @@ Name | Type | Description  | Notes
 
 ListInvoices
 
-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](/docs/invoices-api/overview#retrieve-invoices).
+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.
 
 ### Example
 ```javascript
@@ -279,7 +279,7 @@ Name | Type | Description  | Notes
 
 PublishInvoice
 
-Publishes the specified draft invoice.   After an invoice is published, Square  follows up based on the invoice configuration. For example, Square  sends the invoice to the customer's email address, charges the customer's card on file, or does  nothing. Square also makes the invoice available on a Square-hosted invoice page.   The invoice `status` also changes from `DRAFT` to a status  based on the invoice configuration. For example, the status changes to `UNPAID` if  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](/docs/invoices-api/overview#create-and-publish-an-invoice).
+Publishes the specified draft invoice.   After an invoice is published, Square  follows up based on the invoice configuration. For example, Square  sends the invoice to the customer's email address, charges the customer's card on file, or does  nothing. Square also makes the invoice available on a Square-hosted invoice page.   The invoice `status` also changes from `DRAFT` to a status  based on the invoice configuration. For example, the status changes to `UNPAID` if  Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the  invoice amount).
 
 ### Example
 ```javascript
@@ -331,7 +331,7 @@ Name | Type | Description  | Notes
 
 SearchInvoices
 
-Searches for invoices from a location specified in  the filter. You can optionally specify customers in the filter for whom to  retrieve invoices. In the current implementation, you can only specify one location and  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](/docs/invoices-api/overview#retrieve-invoices).
+Searches for invoices from a location specified in  the filter. You can optionally specify customers in the filter for whom to  retrieve invoices. In the current implementation, you can only specify one location and  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.
 
 ### Example
 ```javascript
@@ -380,7 +380,7 @@ Name | Type | Description  | Notes
 
 UpdateInvoice
 
-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](/docs/invoices-api/overview#update-an-invoice).
+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.
 
 ### Example
 ```javascript

docs/ListPaymentRefundsRequest.md

@@ -14,5 +14,6 @@ Name | Type | Description | Notes
 **location_id** | **String** | Limit results to the location supplied. By default, results are returned for all locations associated with the merchant. | [optional] 
 **status** | **String** | If provided, only refunds with the given status are returned. For a list of refund status values, see `PaymentRefund`.  Default: If omitted refunds are returned regardless of status. | [optional] 
 **source_type** | **String** | If provided, only refunds with the given source type are returned. - `CARD` - List refunds only for payments where card was specified as payment source.  Default: If omitted refunds are returned regardless of source type. | [optional] 
+**limit** | **Number** | Maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page.  If the supplied value is greater than 100, at most 100 results will be returned.  Default: `100` | [optional] 
 
 

docs/ListPaymentsRequest.md

@@ -11,9 +11,10 @@ Name | Type | Description | Notes
 **end_time** | **String** | Timestamp for the end of the requested reporting period, in RFC 3339 format.  Default: The current time. | [optional] 
 **sort_order** | **String** | The order in which results are listed. - `ASC` - oldest to newest - `DESC` - newest to oldest (default). | [optional] 
 **cursor** | **String** | A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.  See [Pagination](https://developer.squareup.com/docs/basics/api101/pagination) for more information. | [optional] 
-**location_id** | **String** | Limit results to the location supplied. By default, results are returned for all locations associated with the merchant. | [optional] 
+**location_id** | **String** | Limit results to the location supplied. By default, results are returned for the default (main) location associated with the merchant. | [optional] 
 **total** | **Number** | The exact amount in the total_money for a `Payment`. | [optional] 
 **last_4** | **String** | The last 4 digits of `Payment` card. | [optional] 
 **card_brand** | **String** | The brand of `Payment` card. For example, `VISA` | [optional] 
+**limit** | **Number** | Maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page.  If the supplied value is greater than 100, at most 100 results will be returned.  Default: `100` | [optional] 
 
 

docs/OrderLineItem.md

@@ -9,7 +9,7 @@ Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **uid** | **String** | Unique ID that identifies the line item only within this order. | [optional] [beta]
 **name** | **String** | The name of the line item. | [optional] 
-**quantity** | **String** | The quantity purchased, formatted as a decimal number. For example: `\"3\"`.  Line items with a `quantity_unit` can have non-integer quantities. For example: `\"1.70000\"`. | 
+**quantity** | **String** | The quantity purchased, formatted as a decimal number. For example: `\"3\"`.  Line items with a quantity of `\"0\"` will be automatically removed upon paying for or otherwise completing the order.  Line items with a `quantity_unit` can have non-integer quantities. For example: `\"1.70000\"`. | 
 **quantity_unit** | [**OrderQuantityUnit**](OrderQuantityUnit.md) | The unit and precision that this line item's quantity is measured in. | [optional] 
 **note** | **String** | The note of the line item. | [optional] 
 **catalog_object_id** | **String** | The `CatalogItemVariation` id applied to this line item. | [optional] 

docs/OrdersApi.md

@@ -115,7 +115,7 @@ Name | Type | Description  | Notes
 
 CreateOrder
 
-Creates a new [Order](#type-order) which can include information on products for purchase and settings to apply to the purchase.  To pay for a created order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) guide.  You can modify open orders using the [UpdateOrder](#endpoint-orders-updateorder) endpoint.  To learn more about the Orders API, see the [Orders API Overview](/orders-api/what-it-does).
+Creates a new [Order](#type-order) which can include information on products for purchase and settings to apply to the purchase.  To pay for a created order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) guide.  You can modify open orders using the [UpdateOrder](#endpoint-orders-updateorder) endpoint.
 
 ### Example
 ```javascript
@@ -164,7 +164,7 @@ Name | Type | Description  | Notes
 
 PayOrder
 
-Pay for an [order](#type-order) using one or more approved [payments](#type-payment), or settle an order with a total of `0`.  The total of the `payment_ids` listed in the request must be equal to the order total. Orders with a total amount of `0` can be marked as paid by specifying an empty array of `payment_ids` in the request.  To be used with PayOrder, a payment must:  - Reference the order by specifying the `order_id` when [creating the payment](#endpoint-payments-createpayment). Any approved payments that reference the same `order_id` not specified in the `payment_ids` will be canceled. - Be approved with [delayed capture](/payments-api/take-payments#delayed-capture). Using a delayed capture payment with PayOrder will complete the approved payment.  Learn how to [pay for orders with a single payment using the Payments API](/orders-api/pay-for-orders).
+Pay for an [order](#type-order) using one or more approved [payments](#type-payment), or settle an order with a total of `0`.  The total of the `payment_ids` listed in the request must be equal to the order total. Orders with a total amount of `0` can be marked as paid by specifying an empty array of `payment_ids` in the request.  To be used with PayOrder, a payment must:  - Reference the order by specifying the `order_id` when [creating the payment](#endpoint-payments-createpayment). Any approved payments that reference the same `order_id` not specified in the `payment_ids` will be canceled. - Be approved with [delayed capture](/payments-api/take-payments#delayed-capture). Using a delayed capture payment with PayOrder will complete the approved payment.
 
 ### Example
 ```javascript
@@ -264,7 +264,7 @@ Name | Type | Description  | Notes
 
 UpdateOrder
 
-Updates an open [Order](#type-order) by adding, replacing, or deleting fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.  An UpdateOrder request requires the following:  - The `order_id` in the endpoint path, identifying the order to update. - The latest `version` of the order to update. - The [sparse order](/orders-api/manage-orders#sparse-order-objects) containing only the fields to update and the version the update is being applied to. - If deleting fields, the [dot notation paths](/orders-api/manage-orders#on-dot-notation) identifying fields to clear.  To pay for an order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) guide.  To learn more about the Orders API, see the [Orders API Overview](/orders-api/what-it-does).
+Updates an open [Order](#type-order) by adding, replacing, or deleting fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.  An UpdateOrder request requires the following:  - The `order_id` in the endpoint path, identifying the order to update. - The latest `version` of the order to update. - The [sparse order](/orders-api/manage-orders#sparse-order-objects) containing only the fields to update and the version the update is being applied to. - If deleting fields, the [dot notation paths](/orders-api/manage-orders#on-dot-notation) identifying fields to clear.  To pay for an order, please refer to the [Pay for Orders](/orders-api/pay-for-orders) guide.
 
 ### Example
 ```javascript