Merge pull request #137 from square/release/38.2.0.20241017

Generated PR for Release: 38.2.0.20241017

Author: Esawyer25

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2024-09-19'` |
+| `square_version` | `str` | Square Connect API versions<br>*Default*: `'2024-10-17'` |
 | `custom_url` | `str` | 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`** |
 | `http_client_instance` | `HttpClient` | The Http Client passed from the sdk user for making requests |
@@ -24,7 +24,7 @@ The API client can be initialized as follows:
 
 ```python
 client = Client(
-    square_version='2024-09-19',
+    square_version='2024-10-17',
     bearer_auth_credentials=BearerAuthCredentials(
         access_token='AccessToken'
     ),
@@ -53,7 +53,7 @@ from square.http.auth.o_auth_2 import BearerAuthCredentials
 from square.client import Client
 
 client = Client(
-    square_version='2024-09-19',
+    square_version='2024-10-17',
     bearer_auth_credentials=BearerAuthCredentials(
         access_token='AccessToken'
     ),

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
+
+`Destination Details Cash Refund Details`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `seller_supplied_money` | [`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. |
+| `change_back_money` | [`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. |
+
+## 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
+
+`Destination Details External Refund Details`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `type` | `str` | 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` |
+| `source` | `str` | Required | A description of the external refund source. For example,<br>"Food Delivery Service".<br>**Constraints**: *Maximum Length*: `255` |
+| `source_id` | `str` | Optional | An ID to associate the refund to its originating source.<br>**Constraints**: *Maximum Length*: `255` |
+
+## 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 |
 |  --- | --- | --- | --- |
 | `card_details` | [`Destination Details Card Refund Details`](../../doc/models/destination-details-card-refund-details.md) | Optional | - |
+| `cash_details` | [`Destination Details Cash Refund Details`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. |
+| `external_details` | [`Destination Details External Refund Details`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. |
 
 ## 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/api/refu
 | `amount_money` | [`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. |
 | `app_fee_money` | [`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. |
 | `payment_id` | `str` | Optional | The unique ID of the payment being refunded.<br>Required when unlinked=false, otherwise must not be set. |
-| `destination_id` | `str` | 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. |
+| `destination_id` | `str` | 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). |
 | `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. |
 | `location_id` | `str` | 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` |
 | `customer_id` | `str` | 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`. |
 | `reason` | `str` | Optional | A description of the reason for the refund.<br>**Constraints**: *Maximum Length*: `192` |
 | `payment_version_token` | `str` | 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. |
 | `team_member_id` | `str` | Optional | An optional [TeamMember](entity:TeamMember) ID to associate with this refund.<br>**Constraints**: *Maximum Length*: `192` |
+| `cash_details` | [`Destination Details Cash Refund Details`](../../doc/models/destination-details-cash-refund-details.md) | Optional | Stores details about a cash refund. Contains only non-confidential information. |
+| `external_details` | [`Destination Details External Refund Details`](../../doc/models/destination-details-external-refund-details.md) | Optional | Stores details about an external refund. Contains only non-confidential information. |
 
 ## 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"
       }
     }
   },

pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools>=61.0"]
 [project]
 name = "squareup"
 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"
 readme = "README.md"
 requires-python = ">=3.7"
 authors = [{name = "Square Developer Platform", email = "[email protected]"}]