Merge pull request #137 from square/release/38.0.0.20240821

Generated PR for Release: 38.0.0.20240821

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "square/square",
     "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.",
-    "version": "37.1.1.20240717",
+    "version": "38.0.0.20240821",
     "type": "library",
     "keywords": [
         "Square",
@@ -48,7 +48,7 @@
         "lint-src-fix": "phpcbf --standard=phpcs-ruleset.xml src/",
         "lint-tests": "phpcs --standard=phpcs-ruleset.xml tests/",
         "lint-tests-fix": "phpcbf --standard=phpcs-ruleset.xml tests/",
-        "analyze": "phan --allow-polyfill-parser",
+        "analyze": "phan --allow-polyfill-parser -p",
         "lint": [
             "@lint-src",
             "@lint-tests"

doc/apis/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.
 
@@ -144,7 +144,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.
 
@@ -520,7 +520,7 @@ var_dump($apiResponse->getHeaders());
 
 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.
 
@@ -614,7 +614,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/apis/gift-card-activities.md

@@ -71,8 +71,7 @@ var_dump($apiResponse->getHeaders());
 # 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.
 
 ```php
 function createGiftCardActivity(CreateGiftCardActivityRequest $body): ApiResponse

doc/apis/gift-cards.md

@@ -67,9 +67,11 @@ var_dump($apiResponse->getHeaders());
 
 # 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/apis/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/apis/gift-card-activities.md#create-gift-card-activity) and create an `ACTIVATE`
+activity with the initial balance. Alternatively, you can use [RefundPayment](../../doc/apis/refunds.md#refund-payment)
+to refund a payment to the new gift card.
 
 ```php
 function createGiftCard(CreateGiftCardRequest $body): ApiResponse

doc/apis/o-auth.md

@@ -154,28 +154,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.
-
 ```php
-function retrieveTokenStatus(string $authorization): ApiResponse
+function retrieveTokenStatus(): ApiResponse
 ```
 
-## Parameters
-
-| Parameter | Type | Tags | Description |
-|  --- | --- | --- | --- |
-| `authorization` | `string` | Header, Required | Client APPLICATION_SECRET |
-
 ## Response Type
 
 This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`RetrieveTokenStatusResponse`](../../doc/models/retrieve-token-status-response.md).
 
 ## Example Usage
 
 ```php
-$authorization = 'Client CLIENT_SECRET';
-
-$apiResponse = $oAuthApi->retrieveTokenStatus($authorization);
+$apiResponse = $oAuthApi->retrieveTokenStatus();
 
 if ($apiResponse->isSuccess()) {
     $retrieveTokenStatusResponse = $apiResponse->getResult();

doc/apis/payments.md

@@ -38,7 +38,10 @@ function listPayments(
     ?int $total = null,
     ?string $last4 = null,
     ?string $cardBrand = null,
-    ?int $limit = null
+    ?int $limit = null,
+    ?bool $isOfflinePayment = false,
+    ?string $offlineBeginTime = null,
+    ?string $offlineEndTime = null
 ): ApiResponse
 ```
 
@@ -55,6 +58,9 @@ function listPayments(
 | `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` | `?int` | 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` | `?bool` | 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
 
@@ -63,7 +69,20 @@ This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` met
 ## Example Usage
 
 ```php
-$apiResponse = $paymentsApi->listPayments();
+$isOfflinePayment = false;
+
+$apiResponse = $paymentsApi->listPayments(
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    $isOfflinePayment
+);
 
 if ($apiResponse->isSuccess()) {
     $listPaymentsResponse = $apiResponse->getResult();

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`** |
 | `timeout` | `int` | Timeout for API calls in seconds.<br>*Default*: `60` |
@@ -30,7 +30,7 @@ $client = SquareClientBuilder::init()
             'AccessToken'
         )
     )
-    ->squareVersion('2024-07-17')
+    ->squareVersion('2024-08-21')
     ->environment('production')
     ->customUrl('https://connect.squareup.com')
     ->build();
@@ -60,7 +60,7 @@ $client = SquareClientBuilder::init()
             'AccessToken'
         )
     )
-    ->squareVersion('2024-07-17')
+    ->squareVersion('2024-08-21')
     ->build();
 
 $apiResponse = $client->getLocationsApi()->listLocations();

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). | getCashDetails(): ?CashPaymentDetails | setCashDetails(?CashPaymentDetails cashDetails): void |
 | `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). | getExternalDetails(): ?ExternalPaymentDetails | setExternalDetails(?ExternalPaymentDetails externalDetails): void |
 | `customerDetails` | [`?CustomerDetails`](../../doc/models/customer-details.md) | Optional | Details about the customer making the payment. | getCustomerDetails(): ?CustomerDetails | setCustomerDetails(?CustomerDetails customerDetails): void |
+| `offlinePaymentDetails` | [`?OfflinePaymentDetails`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | getOfflinePaymentDetails(): ?OfflinePaymentDetails | setOfflinePaymentDetails(?OfflinePaymentDetails offlinePaymentDetails): void |
 
 ## 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. | getOrderId(): ?string | setOrderId(?string orderId): void |
 | `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. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void |
 | `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. | getReferenceId(): ?string | setReferenceId(?string referenceId): void |
-| `buyerPaymentInstrumentIds` | `?(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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void |
+| `buyerPaymentInstrumentIds` | `?(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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void |
 
 ## 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. | getOrderId(): ?string | setOrderId(?string orderId): void |
 | `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. | getLineItemUid(): ?string | setLineItemUid(?string lineItemUid): void |
 | `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. | getReferenceId(): ?string | setReferenceId(?string referenceId): void |
-| `buyerPaymentInstrumentIds` | `?(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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void |
+| `buyerPaymentInstrumentIds` | `?(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. | getBuyerPaymentInstrumentIds(): ?array | setBuyerPaymentInstrumentIds(?array buyerPaymentInstrumentIds): void |
 
 ## 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 | Setter |
 |  --- | --- | --- | --- | --- | --- |
-| `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. | getRedeemActivityId(): ?string | setRedeemActivityId(?string redeemActivityId): void |
+| `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. | getRedeemActivityId(): ?string | setRedeemActivityId(?string redeemActivityId): void |
 | `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. | getAmountMoney(): ?Money | setAmountMoney(?Money amountMoney): void |
 | `referenceId` | `?string` | Optional | A client-specified ID that associates the gift card activity with an entity in another system. | getReferenceId(): ?string | setReferenceId(?string referenceId): void |
-| `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. | getPaymentId(): ?string | setPaymentId(?string paymentId): void |
+| `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. | getPaymentId(): ?string | setPaymentId(?string paymentId): void |
 
 ## Example (as JSON)