Generated PR for Release: 38.2.0.20241017

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": "38.1.0.20240919",
+    "version": "38.2.0.20241017",
     "type": "library",
     "keywords": [
         "Square",

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-09-19'` |
+| `squareVersion` | `string` | Square Connect API versions<br>*Default*: `'2024-10-17'` |
 | `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-09-19')
+    ->squareVersion('2024-10-17')
     ->environment(Environment::PRODUCTION)
     ->customUrl('https://connect.squareup.com')
     ->build();
@@ -61,7 +61,7 @@ $client = SquareClientBuilder::init()
             'AccessToken'
         )
     )
-    ->squareVersion('2024-09-19')
+    ->squareVersion('2024-10-17')
     ->environment(Environment::PRODUCTION)
     ->customUrl('https://connect.squareup.com')
     ->build();

doc/models/destination-details-cash-refund-details.md

@@ -0,0 +1,31 @@
+
+# Destination Details Cash Refund Details
+
+Stores details about a cash refund. Contains only non-confidential information.
+
+## Structure
+
+`DestinationDetailsCashRefundDetails`
+
+## Fields
+
+| Name | Type | Tags | Description | Getter | Setter |
+|  --- | --- | --- | --- | --- | --- |
+| `sellerSuppliedMoney` | [`Money`](../../doc/models/money.md) | Required | 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. | getSellerSuppliedMoney(): Money | setSellerSuppliedMoney(Money sellerSuppliedMoney): void |
+| `changeBackMoney` | [`?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. | getChangeBackMoney(): ?Money | setChangeBackMoney(?Money changeBackMoney): void |
+
+## Example (as JSON)
+
+```json
+{
+  "seller_supplied_money": {
+    "amount": 36,
+    "currency": "AZN"
+  },
+  "change_back_money": {
+    "amount": 78,
+    "currency": "DJF"
+  }
+}
+```
+

doc/models/destination-details-external-refund-details.md

@@ -0,0 +1,27 @@
+
+# Destination Details External Refund Details
+
+Stores details about an external refund. Contains only non-confidential information.
+
+## Structure
+
+`DestinationDetailsExternalRefundDetails`
+
+## Fields
+
+| Name | Type | Tags | Description | Getter | Setter |
+|  --- | --- | --- | --- | --- | --- |
+| `type` | `string` | Required | The type of external refund the seller paid to the buyer. It can be one of the<br>following:<br><br>- CHECK - Refunded using a physical check.<br>- BANK_TRANSFER - Refunded using external bank transfer.<br>- OTHER\_GIFT\_CARD - Refunded using a non-Square gift card.<br>- CRYPTO - Refunded using a crypto currency.<br>- SQUARE_CASH - Refunded using Square Cash App.<br>- SOCIAL - Refunded using peer-to-peer payment applications.<br>- EXTERNAL - A third-party application gathered this refund outside of Square.<br>- EMONEY - Refunded using an E-money provider.<br>- CARD - A credit or debit card that Square does not support.<br>- STORED_BALANCE - Use for house accounts, store credit, and so forth.<br>- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals<br>- OTHER - A type not listed here.<br>**Constraints**: *Maximum Length*: `50` | getType(): string | setType(string type): void |
+| `source` | `string` | Required | A description of the external refund source. For example,<br>"Food Delivery Service".<br>**Constraints**: *Maximum Length*: `255` | getSource(): string | setSource(string source): void |
+| `sourceId` | `?string` | Optional | An ID to associate the refund to its originating source.<br>**Constraints**: *Maximum Length*: `255` | getSourceId(): ?string | setSourceId(?string sourceId): void |
+
+## Example (as JSON)
+
+```json
+{
+  "type": "type4",
+  "source": "source2",
+  "source_id": "source_id0"
+}
+```
+

doc/models/destination-details.md

@@ -12,6 +12,8 @@ Details about a refund's destination.
 | Name | Type | Tags | Description | Getter | Setter |
 |  --- | --- | --- | --- | --- | --- |
 | `cardDetails` | [`?DestinationDetailsCardRefundDetails`](../../doc/models/destination-details-card-refund-details.md) | Optional | - | getCardDetails(): ?DestinationDetailsCardRefundDetails | setCardDetails(?DestinationDetailsCardRefundDetails cardDetails): void |
+| `cashDetails` | [`?DestinationDetailsCashRefundDetails`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. | getCashDetails(): ?DestinationDetailsCashRefundDetails | setCashDetails(?DestinationDetailsCashRefundDetails cashDetails): void |
+| `externalDetails` | [`?DestinationDetailsExternalRefundDetails`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. | getExternalDetails(): ?DestinationDetailsExternalRefundDetails | setExternalDetails(?DestinationDetailsExternalRefundDetails externalDetails): void |
 
 ## Example (as JSON)
 
@@ -27,6 +29,21 @@ Details about a refund's destination.
     },
     "entry_method": "entry_method8",
     "auth_result_code": "auth_result_code0"
+  },
+  "cash_details": {
+    "seller_supplied_money": {
+      "amount": 36,
+      "currency": "AZN"
+    },
+    "change_back_money": {
+      "amount": 78,
+      "currency": "DJF"
+    }
+  },
+  "external_details": {
+    "type": "type6",
+    "source": "source0",
+    "source_id": "source_id8"
   }
 }
 ```

doc/models/get-payment-refund-response.md

@@ -57,6 +57,21 @@ present or it might be present in a FAILED state.
         },
         "entry_method": "entry_method8",
         "auth_result_code": "auth_result_code0"
+      },
+      "cash_details": {
+        "seller_supplied_money": {
+          "amount": 36,
+          "currency": "AZN"
+        },
+        "change_back_money": {
+          "amount": 78,
+          "currency": "DJF"
+        }
+      },
+      "external_details": {
+        "type": "type6",
+        "source": "source0",
+        "source_id": "source_id8"
       }
     }
   },

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

@@ -59,6 +59,21 @@ Either `errors` or `refunds` is present in a given response (never both).
           },
           "entry_method": "entry_method8",
           "auth_result_code": "auth_result_code0"
+        },
+        "cash_details": {
+          "seller_supplied_money": {
+            "amount": 36,
+            "currency": "AZN"
+          },
+          "change_back_money": {
+            "amount": 78,
+            "currency": "DJF"
+          }
+        },
+        "external_details": {
+          "type": "type6",
+          "source": "source0",
+          "source_id": "source_id8"
         }
       }
     }

doc/models/payment-refund.md

@@ -48,6 +48,21 @@ the original payment and the amount of money refunded.
       },
       "entry_method": "entry_method8",
       "auth_result_code": "auth_result_code0"
+    },
+    "cash_details": {
+      "seller_supplied_money": {
+        "amount": 36,
+        "currency": "AZN"
+      },
+      "change_back_money": {
+        "amount": 78,
+        "currency": "DJF"
+      }
+    },
+    "external_details": {
+      "type": "type6",
+      "source": "source0",
+      "source_id": "source_id8"
     }
   },
   "amount_money": {

doc/models/refund-payment-request.md

@@ -15,13 +15,15 @@ Describes a request to refund a payment using [RefundPayment](../../doc/apis/ref
 | `amountMoney` | [`Money`](../../doc/models/money.md) | Required | 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 |
 | `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. | getAppFeeMoney(): ?Money | setAppFeeMoney(?Money appFeeMoney): void |
 | `paymentId` | `?string` | Optional | The unique ID of the payment being refunded.<br>Required when unlinked=false, otherwise must not be set. | getPaymentId(): ?string | setPaymentId(?string paymentId): void |
-| `destinationId` | `?string` | Optional | The ID indicating where funds will be refunded to, if this is an unlinked refund.<br>This can be any of the following: A token generated by Web Payments SDK;<br>a card-on-file identifier.<br>Required for requests specifying unlinked=true.<br>Otherwise, if included when `unlinked=false`, will throw an error. | getDestinationId(): ?string | setDestinationId(?string destinationId): void |
+| `destinationId` | `?string` | Optional | The ID indicating where funds will be refunded to. Required for unlinked refunds. For more<br>information, see [Create an unlinked refund](https://developer.squareup.com/docs/payments-api/refund-payments#create-an-unlinked-refund).<br><br>For refunds linked to Square payments, destination_id is usually omitted; in this case, funds<br>will be returned to the original payment source. The field may be specified in order to request<br>a cross-method refund to a gift card. For more information,<br>see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards). | getDestinationId(): ?string | setDestinationId(?string destinationId): void |
 | `unlinked` | `?bool` | Optional | Indicates that the refund is not linked to a Square payment.<br>If set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not<br>be provided. | getUnlinked(): ?bool | setUnlinked(?bool unlinked): void |
 | `locationId` | `?string` | Optional | The location ID associated with the unlinked refund.<br>Required for requests specifying `unlinked=true`.<br>Otherwise, if included when `unlinked=false`, will throw an error.<br>**Constraints**: *Maximum Length*: `50` | getLocationId(): ?string | setLocationId(?string locationId): void |
 | `customerId` | `?string` | Optional | The [Customer](entity:Customer) ID of the customer associated with the refund.<br>This is required if the `destination_id` refers to a card on file created using the Cards<br>API. Only allowed when `unlinked=true`. | getCustomerId(): ?string | setCustomerId(?string customerId): void |
 | `reason` | `?string` | Optional | A description of the reason for the refund.<br>**Constraints**: *Maximum Length*: `192` | getReason(): ?string | setReason(?string reason): void |
 | `paymentVersionToken` | `?string` | Optional | Used for optimistic concurrency. This opaque token identifies the current `Payment`<br>version that the caller expects. If the server has a different version of the Payment,<br>the update fails and a response with a VERSION_MISMATCH error is returned.<br>If the versions match, or the field is not provided, the refund proceeds as normal. | getPaymentVersionToken(): ?string | setPaymentVersionToken(?string paymentVersionToken): void |
 | `teamMemberId` | `?string` | Optional | An optional [TeamMember](entity:TeamMember) ID to associate with this refund.<br>**Constraints**: *Maximum Length*: `192` | getTeamMemberId(): ?string | setTeamMemberId(?string teamMemberId): void |
+| `cashDetails` | [`?DestinationDetailsCashRefundDetails`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. | getCashDetails(): ?DestinationDetailsCashRefundDetails | setCashDetails(?DestinationDetailsCashRefundDetails cashDetails): void |
+| `externalDetails` | [`?DestinationDetailsExternalRefundDetails`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. | getExternalDetails(): ?DestinationDetailsExternalRefundDetails | setExternalDetails(?DestinationDetailsExternalRefundDetails externalDetails): void |
 
 ## Example (as JSON)
 

doc/models/refund-payment-response.md

@@ -52,6 +52,21 @@ present, or it might be present with a status of `FAILED`.
         },
         "entry_method": "entry_method8",
         "auth_result_code": "auth_result_code0"
+      },
+      "cash_details": {
+        "seller_supplied_money": {
+          "amount": 36,
+          "currency": "AZN"
+        },
+        "change_back_money": {
+          "amount": 78,
+          "currency": "DJF"
+        }
+      },
+      "external_details": {
+        "type": "type6",
+        "source": "source0",
+        "source_id": "source_id8"
       }
     }
   },

src/ConfigurationDefaults.php

@@ -27,7 +27,7 @@ class ConfigurationDefaults
 
     public const HTTP_METHODS_TO_RETRY = ['GET', 'PUT'];
 
-    public const SQUARE_VERSION = '2024-09-19';
+    public const SQUARE_VERSION = '2024-10-17';
 
     public const ADDITIONAL_HEADERS = [];
 

src/Models/Builders/DestinationDetailsBuilder.php

@@ -7,6 +7,8 @@
 use Core\Utils\CoreHelper;
 use Square\Models\DestinationDetails;
 use Square\Models\DestinationDetailsCardRefundDetails;
+use Square\Models\DestinationDetailsCashRefundDetails;
+use Square\Models\DestinationDetailsExternalRefundDetails;
 
 /**
  * Builder for model DestinationDetails
@@ -42,6 +44,24 @@ public function cardDetails(?DestinationDetailsCardRefundDetails $value): self
         return $this;
     }
 
+    /**
+     * Sets cash details field.
+     */
+    public function cashDetails(?DestinationDetailsCashRefundDetails $value): self
+    {
+        $this->instance->setCashDetails($value);
+        return $this;
+    }
+
+    /**
+     * Sets external details field.
+     */
+    public function externalDetails(?DestinationDetailsExternalRefundDetails $value): self
+    {
+        $this->instance->setExternalDetails($value);
+        return $this;
+    }
+
     /**
      * Initializes a new destination details object.
      */

src/Models/Builders/DestinationDetailsCashRefundDetailsBuilder.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Models\Builders;
+
+use Core\Utils\CoreHelper;
+use Square\Models\DestinationDetailsCashRefundDetails;
+use Square\Models\Money;
+
+/**
+ * Builder for model DestinationDetailsCashRefundDetails
+ *
+ * @see DestinationDetailsCashRefundDetails
+ */
+class DestinationDetailsCashRefundDetailsBuilder
+{
+    /**
+     * @var DestinationDetailsCashRefundDetails
+     */
+    private $instance;
+
+    private function __construct(DestinationDetailsCashRefundDetails $instance)
+    {
+        $this->instance = $instance;
+    }
+
+    /**
+     * Initializes a new destination details cash refund details Builder object.
+     */
+    public static function init(Money $sellerSuppliedMoney): self
+    {
+        return new self(new DestinationDetailsCashRefundDetails($sellerSuppliedMoney));
+    }
+
+    /**
+     * Sets change back money field.
+     */
+    public function changeBackMoney(?Money $value): self
+    {
+        $this->instance->setChangeBackMoney($value);
+        return $this;
+    }
+
+    /**
+     * Initializes a new destination details cash refund details object.
+     */
+    public function build(): DestinationDetailsCashRefundDetails
+    {
+        return CoreHelper::clone($this->instance);
+    }
+}

src/Models/Builders/DestinationDetailsExternalRefundDetailsBuilder.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Square\Models\Builders;
+
+use Core\Utils\CoreHelper;
+use Square\Models\DestinationDetailsExternalRefundDetails;
+
+/**
+ * Builder for model DestinationDetailsExternalRefundDetails
+ *
+ * @see DestinationDetailsExternalRefundDetails
+ */
+class DestinationDetailsExternalRefundDetailsBuilder
+{
+    /**
+     * @var DestinationDetailsExternalRefundDetails
+     */
+    private $instance;
+
+    private function __construct(DestinationDetailsExternalRefundDetails $instance)
+    {
+        $this->instance = $instance;
+    }
+
+    /**
+     * Initializes a new destination details external refund details Builder object.
+     */
+    public static function init(string $type, string $source): self
+    {
+        return new self(new DestinationDetailsExternalRefundDetails($type, $source));
+    }
+
+    /**
+     * Sets source id field.
+     */
+    public function sourceId(?string $value): self
+    {
+        $this->instance->setSourceId($value);
+        return $this;
+    }
+
+    /**
+     * Unsets source id field.
+     */
+    public function unsetSourceId(): self
+    {
+        $this->instance->unsetSourceId();
+        return $this;
+    }
+
+    /**
+     * Initializes a new destination details external refund details object.
+     */
+    public function build(): DestinationDetailsExternalRefundDetails
+    {
+        return CoreHelper::clone($this->instance);
+    }
+}