Merge pull request #121 from square/release/41.0.0.20240821

Generated PR for Release: 41.0.0.20240821

doc/api/catalog.md

@@ -39,7 +39,7 @@ children.
 IDs can be deleted. The response will only include IDs that were
 actually deleted.
 
-To ensure consistency, only one delete request is processed at a time per seller account. 
+To ensure consistency, only one delete request is processed at a time per seller account.
 While one (batch or non-batch) delete request is being processed, other (batched and non-batched)
 delete requests are rejected with the `429` error code.
 
@@ -138,7 +138,7 @@ batches will be processed in order as long as the total object count for the
 request (items, variations, modifier lists, discounts, and taxes) is no more
 than 10,000.
 
-To ensure consistency, only one update request is processed at a time per seller account. 
+To ensure consistency, only one update request is processed at a time per seller account.
 While one (batch or non-batch) update request is being processed, other (batched and non-batched)
 update requests are rejected with the `429` error code.
 
@@ -468,7 +468,7 @@ catalogApi.listCatalogAsync(null, null, null).thenAccept(result -> {
 
 Creates a new or updates the specified [CatalogObject](../../doc/models/catalog-object.md).
 
-To ensure consistency, only one update request is processed at a time per seller account. 
+To ensure consistency, only one update request is processed at a time per seller account.
 While one (batch or non-batch) update request is being processed, other (batched and non-batched)
 update requests are rejected with the `429` error code.
 
@@ -551,7 +551,7 @@ are also deleted. For example, deleting a [CatalogItem](../../doc/models/catalog
 will also delete all of its
 [CatalogItemVariation](../../doc/models/catalog-item-variation.md) children.
 
-To ensure consistency, only one delete request is processed at a time per seller account. 
+To ensure consistency, only one delete request is processed at a time per seller account.
 While one (batch or non-batch) delete request is being processed, other (batched and non-batched)
 delete requests are rejected with the `429` error code.
 

doc/api/gift-card-activities.md

@@ -67,8 +67,7 @@ giftCardActivitiesApi.listGiftCardActivitiesAsync(null, null, null, null, null,
 # Create Gift Card Activity
 
 Creates a gift card activity to manage the balance or state of a [gift card](../../doc/models/gift-card.md).
-For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance
-before the gift card can be used.
+For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use.
 
 ```java
 CompletableFuture<CreateGiftCardActivityResponse> createGiftCardActivityAsync(

doc/api/gift-cards.md

@@ -63,9 +63,11 @@ giftCardsApi.listGiftCardsAsync(null, null, null, null, null).thenAccept(result
 
 # Create Gift Card
 
-Creates a digital gift card or registers a physical (plastic) gift card. After the gift card
-is created, you must call [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity)
-to activate the card with an initial balance before it can be used for payment.
+Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card
+has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call
+[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) and create an `ACTIVATE`
+activity with the initial balance. Alternatively, you can use [RefundPayment](../../doc/api/refunds.md#refund-payment)
+to refund a payment to the new gift card.
 
 ```java
 CompletableFuture<CreateGiftCardResponse> createGiftCardAsync(

doc/api/o-auth.md

@@ -148,29 +148,18 @@ where `ACCESS_TOKEN` is a
 
 If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error.
 
-:information_source: **Note** This endpoint does not require authentication.
-
 ```java
-CompletableFuture<RetrieveTokenStatusResponse> retrieveTokenStatusAsync(
- final String authorization)
+CompletableFuture<RetrieveTokenStatusResponse> retrieveTokenStatusAsync()
 ```
 
-## Parameters
-
-| Parameter | Type | Tags | Description |
-| --- | --- | --- | --- |
-| `authorization` | `String` | Header, Required | Client APPLICATION_SECRET |
-
 ## Response Type
 
 [`RetrieveTokenStatusResponse`](../../doc/models/retrieve-token-status-response.md)
 
 ## Example Usage
 
 ```java
-String authorization = "Client CLIENT_SECRET";
-
-oAuthApi.retrieveTokenStatusAsync(authorization).thenAccept(result -> {
+oAuthApi.retrieveTokenStatusAsync().thenAccept(result -> {
  // TODO success callback handler
  System.out.println(result);
 }).exceptionally(exception -> {

doc/api/payments.md

@@ -38,7 +38,10 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
  final Long total,
  final String last4,
  final String cardBrand,
- final Integer limit)
+ final Integer limit,
+ final Boolean isOfflinePayment,
+ final String offlineBeginTime,
+ final String offlineEndTime)
 ```
 
 ## Parameters
@@ -54,6 +57,9 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
 | `last4` | `String` | Query, Optional | The last four digits of a payment card. |
 | `cardBrand` | `String` | Query, Optional | The brand of the payment card (for example, VISA). |
 | `limit` | `Integer` | Query, Optional | The 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>The default value of 100 is also the maximum allowed value. If the provided value is<br>greater than 100, it is ignored and the default value is used instead.<br><br>Default: `100` |
+| `isOfflinePayment` | `Boolean` | Query, Optional | Whether the payment was taken offline or not. |
+| `offlineBeginTime` | `String` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
+| `offlineEndTime` | `String` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339<br>format for timestamps. The range is determined using the<br>`offline_payment_details.client_created_at` field for each Payment. If set, payments without a<br>value set in `offline_payment_details.client_created_at` will not be returned.<br><br>Default: The current time. |
 
 ## Response Type
 
@@ -62,7 +68,9 @@ CompletableFuture<ListPaymentsResponse> listPaymentsAsync(
 ## Example Usage
 
 ```java
-paymentsApi.listPaymentsAsync(null, null, null, null, null, null, null, null, null).thenAccept(result -> {
+Boolean isOfflinePayment = false;
+
+paymentsApi.listPaymentsAsync(null, null, null, null, null, null, null, null, null, isOfflinePayment, null, null).thenAccept(result -> {
  // TODO success callback handler
  System.out.println(result);
 }).exceptionally(exception -> {

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2024-07-17"` |
+| `squareVersion` | `String` | Square Connect API versions<br>*Default*: `"2024-08-21"` |
 | `customUrl` | `String` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `"https://connect.squareup.com"` |
 | `environment` | `string` | The API environment. <br> **Default: `production`** |
 | `httpClientConfig` | [`Consumer<HttpClientConfiguration.Builder>`](http-client-configuration-builder.md) | Set up Http Client Configuration instance. |
@@ -19,7 +19,7 @@ The API client can be initialized as follows:
 SquareClient client = new SquareClient.Builder()
  .httpClientConfig(configBuilder -> configBuilder
  .timeout(0))
- .squareVersion("2024-07-17")
+ .squareVersion("2024-08-21")
  .bearerAuthCredentials(new BearerAuthModel.Builder(
  "AccessToken"
  )
@@ -44,7 +44,7 @@ public class Program {
  SquareClient client = new SquareClient.Builder()
  .httpClientConfig(configBuilder -> configBuilder
  .timeout(0))
- .squareVersion("2024-07-17")
+ .squareVersion("2024-08-21")
  .bearerAuthCredentials(new BearerAuthModel.Builder(
  "AccessToken"
  )

doc/models/create-payment-request.md

@@ -35,6 +35,7 @@ Describes a request to create a payment using
 | `CashDetails` | [`CashPaymentDetails`](../../doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see<br>[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). | CashPaymentDetails getCashDetails() |
 | `ExternalDetails` | [`ExternalPaymentDetails`](../../doc/models/external-payment-details.md) | Optional | Stores details about an external payment. Contains only non-confidential information.<br>For more information, see<br>[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). | ExternalPaymentDetails getExternalDetails() |
 | `CustomerDetails` | [`CustomerDetails`](../../doc/models/customer-details.md) | Optional | Details about the customer making the payment. | CustomerDetails getCustomerDetails() |
+| `OfflinePaymentDetails` | [`OfflinePaymentDetails`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | OfflinePaymentDetails getOfflinePaymentDetails() |
 
 ## Example (as JSON)
 

doc/models/gift-card-activity-activate.md

@@ -15,7 +15,7 @@ Represents details about an `ACTIVATE` [gift card activity type](../../doc/model
 | `OrderId` | `String` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.<br><br>Applications that use the Square Orders API to process orders must specify the order ID<br>[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | String getOrderId() |
 | `LineItemUid` | `String` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.<br><br>Applications that use the Square Orders API to process orders must specify the line item UID<br>in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | String getLineItemUid() |
 | `ReferenceId` | `String` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.<br><br>Applications that use a custom order processing system can use this field to track information<br>related to an order or payment. | String getReferenceId() |
-| `BuyerPaymentInstrumentIds` | `List<String>` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks. | List<String> getBuyerPaymentInstrumentIds() |
+| `BuyerPaymentInstrumentIds` | `List<String>` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks.<br><br>Each buyer payment instrument ID can contain a maximum of 255 characters. | List<String> getBuyerPaymentInstrumentIds() |
 
 ## Example (as JSON)
 

doc/models/gift-card-activity-load.md

@@ -15,7 +15,7 @@ Represents details about a `LOAD` [gift card activity type](../../doc/models/gif
 | `OrderId` | `String` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.<br><br>Applications that use the Square Orders API to process orders must specify the order ID in the<br>[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | String getOrderId() |
 | `LineItemUid` | `String` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.<br><br>Applications that use the Square Orders API to process orders must specify the line item UID<br>in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | String getLineItemUid() |
 | `ReferenceId` | `String` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.<br><br>Applications that use a custom order processing system can use this field to track information related to<br>an order or payment. | String getReferenceId() |
-| `BuyerPaymentInstrumentIds` | `List<String>` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks. | List<String> getBuyerPaymentInstrumentIds() |
+| `BuyerPaymentInstrumentIds` | `List<String>` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID<br>or bank account ID.<br><br>Applications that use a custom order processing system must specify payment instrument IDs in<br>the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.<br>Square uses this information to perform compliance checks.<br><br>For applications that use the Square Orders API to process payments, Square has the necessary<br>instrument IDs to perform compliance checks.<br><br>Each buyer payment instrument ID can contain a maximum of 255 characters. | List<String> getBuyerPaymentInstrumentIds() |
 
 ## Example (as JSON)
 

doc/models/gift-card-activity-refund.md

@@ -11,10 +11,10 @@ Represents details about a `REFUND` [gift card activity type](../../doc/models/g
 
 | Name | Type | Tags | Description | Getter |
 | --- | --- | --- | --- | --- |
-| `RedeemActivityId` | `String` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the<br>`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request<br>represents a redemption made by the same gift card. Note that you must use `RefundPayment`<br>to refund a gift card payment to the same gift card if the payment was processed by Square.<br><br>For applications that use a custom payment processing system, this field is required when creating<br>a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. | String getRedeemActivityId() |
+| `RedeemActivityId` | `String` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the<br>`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request<br>represents a gift card redemption.<br><br>For applications that use a custom payment processing system, this field is required when creating<br>a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. | String getRedeemActivityId() |
 | `AmountMoney` | [`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 getAmountMoney() |
 | `ReferenceId` | `String` | Optional | A client-specified ID that associates the gift card activity with an entity in another system. | String getReferenceId() |
-| `PaymentId` | `String` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a<br>payment processed by Square and one of the following conditions is true:<br><br>- The Refunds API is used to refund a gift card payment to the same gift card.<br>- A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment source can be the<br> same gift card or a cross-tender payment from a credit card or a different gift card. | String getPaymentId() |
+| `PaymentId` | `String` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a<br>payment processed by Square. This field matches the `payment_id` in the corresponding<br>[RefundPayment](api-endpoint:Refunds-RefundPayment) request. | String getPaymentId() |
 
 ## Example (as JSON)
 

doc/models/gift-card-activity-type.md

@@ -18,7 +18,7 @@ Indicates the type of [gift card activity](../../doc/models/gift-card-activity.m
 | `DEACTIVATE` | Permanently blocked a gift card from balance-changing activities. |
 | `ADJUST_INCREMENT` | Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow. |
 | `ADJUST_DECREMENT` | Deducted money from a gift card outside of a typical `REDEEM` activity flow. |
-| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to<br>a Square payment, depending on how the payment and refund are processed. For example:<br><br>- A gift card payment processed by Square can be refunded to the same gift card using Square Point of Sale,<br> the Square Seller Dashboard, or the Refunds API.<br>- A cross-tender payment processed by Square can be refunded to a gift card using Square Point of Sale or the<br> Square Seller Dashboard. The payment source might be a credit card or different gift card.<br>- A payment processed using a custom payment processing system can be refunded to the same gift card. |
+| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to<br>a Square payment, depending on how the payment and refund are processed. For example:<br><br>- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square<br> Seller Dashboard, Square Point of Sale, or Refunds API.<br>- A payment processed using a custom processing system can be refunded to the same gift card. |
 | `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that was processed using a custom payment<br>processing system and not linked to the gift card. |
 | `IMPORT` | Imported a third-party gift card with a balance. `IMPORT` activities are managed<br>by Square and cannot be created using the Gift Card Activities API. |
 | `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities<br>are managed by Square and cannot be created using the Gift Card Activities API. |