feat(api): add simulations.check_transfers.return_() method

Author: stainless-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 115
+configured_endpoints: 116

api.md

@@ -481,6 +481,7 @@ Methods:
 
 - <code title="post /simulations/check_transfers/{check_transfer_id}/deposit">client.simulations.check_transfers.<a href="./src/increase/resources/simulations/check_transfers.py">deposit</a>(check_transfer_id) -> <a href="./src/increase/types/check_transfer.py">CheckTransfer</a></code>
 - <code title="post /simulations/check_transfers/{check_transfer_id}/mail">client.simulations.check_transfers.<a href="./src/increase/resources/simulations/check_transfers.py">mail</a>(check_transfer_id) -> <a href="./src/increase/types/check_transfer.py">CheckTransfer</a></code>
+- <code title="post /simulations/check_transfers/{check_transfer_id}/return">client.simulations.check*transfers.<a href="./src/increase/resources/simulations/check_transfers.py">return*</a>(check_transfer_id, \*\*<a href="src/increase/types/simulations/check_transfer_return_params.py">params</a>) -> <a href="./src/increase/types/check_transfer.py">CheckTransfer</a></code>
 
 ## Documents
 

src/increase/_exceptions.py

@@ -52,15 +52,15 @@
 class InvalidParametersError(exceptions.BadRequestError):
     detail: Optional[str]
 
+    errors: List[object]
+    """All errors related to parsing the request parameters."""
+
     status: Literal[400]
 
     title: str
 
     type: Literal["invalid_parameters_error"]
 
-    errors: Optional[List[object]]
-    """All errors related to parsing the request parameters."""
-
     def __init__(self, message: str, *, body: object, request: httpx.Request, response: httpx.Response) -> None:
         data = cast(Mapping[str, object], body if is_mapping(body) else {})
         title = cast(Any, data.get("title"))

src/increase/resources/accounts.py

@@ -26,6 +26,7 @@ def create(
         name: str,
         entity_id: str | NotGiven = NOT_GIVEN,
         informational_entity_id: str | NotGiven = NOT_GIVEN,
+        program_id: str | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -44,6 +45,8 @@ def create(
           informational_entity_id: The identifier of an Entity that, while not owning the Account, is associated
               with its activity. Its relationship to your group must be `informational`.
 
+          program_id: The identifier for the Program that this Account falls under.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -57,6 +60,7 @@ def create(
             body=maybe_transform(
                 {
                     "entity_id": entity_id,
+                    "program_id": program_id,
                     "informational_entity_id": informational_entity_id,
                     "name": name,
                 },
@@ -209,6 +213,7 @@ async def create(
         name: str,
         entity_id: str | NotGiven = NOT_GIVEN,
         informational_entity_id: str | NotGiven = NOT_GIVEN,
+        program_id: str | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -227,6 +232,8 @@ async def create(
           informational_entity_id: The identifier of an Entity that, while not owning the Account, is associated
               with its activity. Its relationship to your group must be `informational`.
 
+          program_id: The identifier for the Program that this Account falls under.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -240,6 +247,7 @@ async def create(
             body=maybe_transform(
                 {
                     "entity_id": entity_id,
+                    "program_id": program_id,
                     "informational_entity_id": informational_entity_id,
                     "name": name,
                 },

src/increase/resources/simulations/check_transfers.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+from typing_extensions import Literal
+
 from ...types import CheckTransfer
 from ..._types import Body, Query, Headers
+from ..._utils import maybe_transform
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._base_client import make_request_options
+from ...types.simulations import check_transfer_return_params
 
 __all__ = ["CheckTransfers", "AsyncCheckTransfers"]
 
@@ -65,6 +69,45 @@ def mail(
             cast_to=CheckTransfer,
         )
 
+    def return_(
+        self,
+        check_transfer_id: str,
+        *,
+        reason: Literal["mail_delivery_failure", "refused_by_recipient"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        idempotency_key: str | None = None,
+    ) -> CheckTransfer:
+        """
+        Simulates a [Check Transfer](#check-transfers) being returned via USPS to
+        Increase. This transfer must first have a `status` of `mailed`.
+
+        Args:
+          reason: The reason why the Check Transfer was returned to Increase.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          idempotency_key: Specify a custom idempotency key for this request
+        """
+        return self._post(
+            f"/simulations/check_transfers/{check_transfer_id}/return",
+            body=maybe_transform({"reason": reason}, check_transfer_return_params.CheckTransferReturnParams),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                idempotency_key=idempotency_key,
+            ),
+            cast_to=CheckTransfer,
+        )
+
 
 class AsyncCheckTransfers(AsyncAPIResource):
     async def deposit(
@@ -120,3 +163,42 @@ async def mail(
             ),
             cast_to=CheckTransfer,
         )
+
+    async def return_(
+        self,
+        check_transfer_id: str,
+        *,
+        reason: Literal["mail_delivery_failure", "refused_by_recipient"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        idempotency_key: str | None = None,
+    ) -> CheckTransfer:
+        """
+        Simulates a [Check Transfer](#check-transfers) being returned via USPS to
+        Increase. This transfer must first have a `status` of `mailed`.
+
+        Args:
+          reason: The reason why the Check Transfer was returned to Increase.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          idempotency_key: Specify a custom idempotency key for this request
+        """
+        return await self._post(
+            f"/simulations/check_transfers/{check_transfer_id}/return",
+            body=maybe_transform({"reason": reason}, check_transfer_return_params.CheckTransferReturnParams),
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                idempotency_key=idempotency_key,
+            ),
+            cast_to=CheckTransfer,
+        )

src/increase/types/account_create_params.py

@@ -19,3 +19,6 @@ class AccountCreateParams(TypedDict, total=False):
     The identifier of an Entity that, while not owning the Account, is associated
     with its activity. Its relationship to your group must be `informational`.
     """
+
+    program_id: str
+    """The identifier for the Program that this Account falls under."""

src/increase/types/check_transfer.py

@@ -6,7 +6,7 @@
 
 from .._models import BaseModel
 
-__all__ = ["CheckTransfer", "ReturnAddress", "Submission", "StopPaymentRequest", "Deposit"]
+__all__ = ["CheckTransfer", "ReturnAddress", "Submission", "StopPaymentRequest", "Deposit", "ReturnDetails"]
 
 
 class ReturnAddress(BaseModel):
@@ -65,6 +65,17 @@ class Deposit(BaseModel):
     """
 
 
+class ReturnDetails(BaseModel):
+    file_id: Optional[str]
+    """If available, a document with additional information about the return."""
+
+    reason: Literal["mail_delivery_failure", "refused_by_recipient"]
+    """The reason why the check was returned."""
+
+    transfer_id: str
+    """The identifier of the returned Check Transfer."""
+
+
 class CheckTransfer(BaseModel):
     account_id: str
     """The identifier of the Account from which funds will be transferred."""
@@ -123,6 +134,13 @@ class CheckTransfer(BaseModel):
     return_address: Optional[ReturnAddress]
     """The return address to be printed on the check."""
 
+    return_details: Optional[ReturnDetails]
+    """After a check transfer is returned, this will contain supplemental details.
+
+    A check transfer is returned when the receiver mails a never deposited check
+    back to the bank printed on the check.
+    """
+
     status: Literal[
         "pending_approval",
         "pending_submission",

src/increase/types/declined_transaction.py

@@ -155,6 +155,7 @@ class SourceCardDecline(BaseModel):
         "webhook_declined",
         "webhook_timed_out",
         "declined_by_stand_in_processing",
+        "invalid_physical_card",
     ]
     """Why the transaction was declined."""
 

src/increase/types/file.py

@@ -43,6 +43,7 @@ class File(BaseModel):
         "digital_wallet_artwork",
         "digital_wallet_app_icon",
         "entity_supplemental_document",
+        "export",
     ]
     """What the File will be used for.
 

src/increase/types/file_list_params.py

@@ -53,6 +53,7 @@ class CreatedAt(TypedDict, total=False):
                 "digital_wallet_artwork",
                 "digital_wallet_app_icon",
                 "entity_supplemental_document",
+                "export",
             ]
         ],
     },