Merge pull request #139 from square/release/38.2.0.20241017

Esawyer25 · web-flow · commit bb7bddd8caf8 · 2024-10-17T09:10:39.000-07:00
Generated PR for Release: 38.2.0.20241017
diff --git a/composer.json b/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",
diff --git a/doc/client.md b/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();
diff --git a/doc/models/destination-details-cash-refund-details.md b/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"
+  }
+}
+```
+
diff --git a/doc/models/destination-details-external-refund-details.md b/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"
+}
+```
+
diff --git a/doc/models/destination-details.md b/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"
   }
 }
 ```
diff --git a/doc/models/get-payment-refund-response.md b/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"
       }
     }
   },
diff --git a/doc/models/list-payment-refunds-response.md b/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"
         }
       }
     }
diff --git a/doc/models/payment-refund.md b/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": {
diff --git a/doc/models/refund-payment-request.md b/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)
 
diff --git a/doc/models/refund-payment-response.md b/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"
       }
     }
   },
diff --git a/src/ConfigurationDefaults.php b/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 = [];
 
diff --git a/src/Models/Builders/DestinationDetailsBuilder.php b/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.
      */
diff --git a/src/Models/Builders/DestinationDetailsCashRefundDetailsBuilder.php b/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);
+    }
+}
diff --git a/src/Models/Builders/DestinationDetailsExternalRefundDetailsBuilder.php b/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);
+    }
+}
diff --git a/src/Models/Builders/RefundPaymentRequestBuilder.php b/src/Models/Builders/RefundPaymentRequestBuilder.php
diff --git a/src/Models/DestinationDetails.php b/src/Models/DestinationDetails.php
diff --git a/src/Models/DestinationDetailsCashRefundDetails.php b/src/Models/DestinationDetailsCashRefundDetails.php
diff --git a/src/Models/DestinationDetailsExternalRefundDetails.php b/src/Models/DestinationDetailsExternalRefundDetails.php
diff --git a/src/Models/RefundPaymentRequest.php b/src/Models/RefundPaymentRequest.php
diff --git a/src/SquareClient.php b/src/SquareClient.php

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "square/square",`
`3`	`3`	`"description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.",`
`4`		`- "version": "38.1.0.20240919",`
	`4`	`+ "version": "38.2.0.20241017",`
`5`	`5`	`"type": "library",`
`6`	`6`	`"keywords": [`
`7`	`7`	`"Square",`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:`
`5`	`5`
`6`	`6`	`\| Parameter \| Type \| Description \|`
`7`	`7`	`\| --- \| --- \| --- \|`
`8`		-\| `squareVersion` \| `string` \| Square Connect API versions<br>Default: `'2024-09-19'` \|
	`8`	+\| `squareVersion` \| `string` \| Square Connect API versions<br>Default: `'2024-10-17'` \|
`9`	`9`	\| `customUrl` \| `string` \| Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>Default: `'https://connect.squareup.com'` \|
`10`	`10`	\| `environment` \| `string` \| The API environment. <br> Default: `production` \|
`11`	`11`	\| `timeout` \| `int` \| Timeout for API calls in seconds.<br>Default: `60` \|
`@@ -30,7 +30,7 @@ $client = SquareClientBuilder::init()`
`30`	`30`	`'AccessToken'`
`31`	`31`	`)`
`32`	`32`	`)`
`33`		`- ->squareVersion('2024-09-19')`
	`33`	`+ ->squareVersion('2024-10-17')`
`34`	`34`	`->environment(Environment::PRODUCTION)`
`35`	`35`	`->customUrl('https://connect.squareup.com')`
`36`	`36`	`->build();`
`@@ -61,7 +61,7 @@ $client = SquareClientBuilder::init()`
`61`	`61`	`'AccessToken'`
`62`	`62`	`)`
`63`	`63`	`)`
`64`		`- ->squareVersion('2024-09-19')`
	`64`	`+ ->squareVersion('2024-10-17')`
`65`	`65`	`->environment(Environment::PRODUCTION)`
`66`	`66`	`->customUrl('https://connect.squareup.com')`
`67`	`67`	`->build();`