increase 1.337.0 → 1.339.0

data/rbi/increase/models/entity_create_params.rbi

@@ -310,7 +310,8 @@ module Increase
         attr_accessor :beneficial_owners
 
         # The legal identifier of the corporation. This is usually the Employer
-        # Identification Number (EIN).
+        # Identification Number (EIN). This replaces the deprecated `tax_identifier`
+        # field.
         sig do
           returns(Increase::EntityCreateParams::Corporation::LegalIdentifier)
         end
@@ -414,7 +415,8 @@ module Increase
           # `control` person.
           beneficial_owners:,
           # The legal identifier of the corporation. This is usually the Employer
-          # Identification Number (EIN).
+          # Identification Number (EIN). This replaces the deprecated `tax_identifier`
+          # field.
           legal_identifier:,
           # The legal name of the corporation.
           name:,
@@ -847,7 +849,8 @@ module Increase
               # An identification number that can be used to verify the individual's identity,
               # such as a social security number. For Social Security Numbers and Individual
               # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-              # separators.
+              # separators. When testing in sandbox, use one of our
+              # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
               sig { returns(String) }
               attr_accessor :number
 
@@ -928,7 +931,8 @@ module Increase
                 # An identification number that can be used to verify the individual's identity,
                 # such as a social security number. For Social Security Numbers and Individual
                 # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-                # separators.
+                # separators. When testing in sandbox, use one of our
+                # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
                 number:,
                 # Information about the United States driver's license used for identification.
                 # Required if `method` is equal to `drivers_license`.
@@ -1263,7 +1267,8 @@ module Increase
             end
 
           # The legal identifier. For US Employer Identification Numbers, submit nine digits
-          # with no dashes or other separators.
+          # with no dashes or other separators. When testing in sandbox, use one of our
+          # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
           sig { returns(String) }
           attr_accessor :value
 
@@ -1287,7 +1292,8 @@ module Increase
           attr_writer :category
 
           # The legal identifier of the corporation. This is usually the Employer
-          # Identification Number (EIN).
+          # Identification Number (EIN). This replaces the deprecated `tax_identifier`
+          # field.
           sig do
             params(
               value: String,
@@ -1297,7 +1303,8 @@ module Increase
           end
           def self.new(
             # The legal identifier. For US Employer Identification Numbers, submit nine digits
-            # with no dashes or other separators.
+            # with no dashes or other separators. When testing in sandbox, use one of our
+            # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
             value:,
             # The category of the legal identifier. If not provided, the default is
             # `us_employer_identification_number`.
@@ -1930,7 +1937,8 @@ module Increase
             # An identification number that can be used to verify the individual's identity,
             # such as a social security number. For Social Security Numbers and Individual
             # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-            # separators.
+            # separators. When testing in sandbox, use one of our
+            # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
             sig { returns(String) }
             attr_accessor :number
 
@@ -2011,7 +2019,8 @@ module Increase
               # An identification number that can be used to verify the individual's identity,
               # such as a social security number. For Social Security Numbers and Individual
               # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-              # separators.
+              # separators. When testing in sandbox, use one of our
+              # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
               number:,
               # Information about the United States driver's license used for identification.
               # Required if `method` is equal to `drivers_license`.
@@ -2509,7 +2518,8 @@ module Increase
           # An identification number that can be used to verify the individual's identity,
           # such as a social security number. For Social Security Numbers and Individual
           # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-          # separators.
+          # separators. When testing in sandbox, use one of our
+          # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
           sig { returns(String) }
           attr_accessor :number
 
@@ -2590,7 +2600,8 @@ module Increase
             # An identification number that can be used to verify the individual's identity,
             # such as a social security number. For Social Security Numbers and Individual
             # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-            # separators.
+            # separators. When testing in sandbox, use one of our
+            # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
             number:,
             # Information about the United States driver's license used for identification.
             # Required if `method` is equal to `drivers_license`.
@@ -3700,7 +3711,8 @@ module Increase
               # An identification number that can be used to verify the individual's identity,
               # such as a social security number. For Social Security Numbers and Individual
               # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-              # separators.
+              # separators. When testing in sandbox, use one of our
+              # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
               sig { returns(String) }
               attr_accessor :number
 
@@ -3781,7 +3793,8 @@ module Increase
                 # An identification number that can be used to verify the individual's identity,
                 # such as a social security number. For Social Security Numbers and Individual
                 # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-                # separators.
+                # separators. When testing in sandbox, use one of our
+                # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
                 number:,
                 # Information about the United States driver's license used for identification.
                 # Required if `method` is equal to `drivers_license`.
@@ -4278,7 +4291,8 @@ module Increase
             # An identification number that can be used to verify the individual's identity,
             # such as a social security number. For Social Security Numbers and Individual
             # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-            # separators.
+            # separators. When testing in sandbox, use one of our
+            # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
             sig { returns(String) }
             attr_accessor :number
 
@@ -4359,7 +4373,8 @@ module Increase
               # An identification number that can be used to verify the individual's identity,
               # such as a social security number. For Social Security Numbers and Individual
               # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-              # separators.
+              # separators. When testing in sandbox, use one of our
+              # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
               number:,
               # Information about the United States driver's license used for identification.
               # Required if `method` is equal to `drivers_license`.

data/rbi/increase/models/entity_update_params.rbi

@@ -869,7 +869,8 @@ module Increase
           # An identification number that can be used to verify the individual's identity,
           # such as a social security number. For Social Security Numbers and Individual
           # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-          # separators.
+          # separators. When testing in sandbox, use one of our
+          # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
           sig { returns(String) }
           attr_accessor :number
 
@@ -950,7 +951,8 @@ module Increase
             # An identification number that can be used to verify the individual's identity,
             # such as a social security number. For Social Security Numbers and Individual
             # Taxpayer Identification Numbers, submit nine digits with no dashes or other
-            # separators.
+            # separators. When testing in sandbox, use one of our
+            # [sandbox test values](https://increase.com/documentation/sandbox-test-values).
             number:,
             # Information about the United States driver's license used for identification.
             # Required if `method` is equal to `drivers_license`.

data/rbi/increase/models/fednow_transfer.rbi

@@ -885,6 +885,13 @@ module Increase
           T.type_alias { T.all(Symbol, Increase::FednowTransfer::Status) }
         OrSymbol = T.type_alias { T.any(Symbol, String) }
 
+        # The transfer is queued to be submitted to FedNow.
+        PENDING_SUBMITTING =
+          T.let(
+            :pending_submitting,
+            Increase::FednowTransfer::Status::TaggedSymbol
+          )
+
         # The transfer is pending review by Increase.
         PENDING_REVIEWING =
           T.let(
@@ -917,13 +924,6 @@ module Increase
             Increase::FednowTransfer::Status::TaggedSymbol
           )
 
-        # The transfer is queued to be submitted to FedNow.
-        PENDING_SUBMITTING =
-          T.let(
-            :pending_submitting,
-            Increase::FednowTransfer::Status::TaggedSymbol
-          )
-
         # The transfer has been submitted and is pending a response from FedNow.
         PENDING_RESPONSE =
           T.let(

data/rbi/increase/models/fednow_transfer_list_params.rbi

@@ -255,6 +255,13 @@ module Increase
             end
           OrSymbol = T.type_alias { T.any(Symbol, String) }
 
+          # The transfer is queued to be submitted to FedNow.
+          PENDING_SUBMITTING =
+            T.let(
+              :pending_submitting,
+              Increase::FednowTransferListParams::Status::In::TaggedSymbol
+            )
+
           # The transfer is pending review by Increase.
           PENDING_REVIEWING =
             T.let(
@@ -290,13 +297,6 @@ module Increase
               Increase::FednowTransferListParams::Status::In::TaggedSymbol
             )
 
-          # The transfer is queued to be submitted to FedNow.
-          PENDING_SUBMITTING =
-            T.let(
-              :pending_submitting,
-              Increase::FednowTransferListParams::Status::In::TaggedSymbol
-            )
-
           # The transfer has been submitted and is pending a response from FedNow.
           PENDING_RESPONSE =
             T.let(

data/rbi/increase/models/inbound_fednow_transfer.rbi

@@ -87,6 +87,12 @@ module Increase
       sig { returns(Increase::InboundFednowTransfer::Type::TaggedSymbol) }
       attr_accessor :type
 
+      # The Unique End-to-end Transaction Reference
+      # ([UETR](https://www.swift.com/payments/what-unique-end-end-transaction-reference-uetr))
+      # of the transfer.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :unique_end_to_end_transaction_reference
+
       # Additional information included with the transfer.
       sig { returns(T.nilable(String)) }
       attr_accessor :unstructured_remittance_information
@@ -111,6 +117,7 @@ module Increase
           status: Increase::InboundFednowTransfer::Status::OrSymbol,
           transaction_id: T.nilable(String),
           type: Increase::InboundFednowTransfer::Type::OrSymbol,
+          unique_end_to_end_transaction_reference: T.nilable(String),
           unstructured_remittance_information: T.nilable(String)
         ).returns(T.attached_class)
       end
@@ -149,6 +156,10 @@ module Increase
         # A constant representing the object's type. For this resource it will always be
         # `inbound_fednow_transfer`.
         type:,
+        # The Unique End-to-end Transaction Reference
+        # ([UETR](https://www.swift.com/payments/what-unique-end-end-transaction-reference-uetr))
+        # of the transfer.
+        unique_end_to_end_transaction_reference:,
         # Additional information included with the transfer.
         unstructured_remittance_information:
       )
@@ -173,6 +184,7 @@ module Increase
             status: Increase::InboundFednowTransfer::Status::TaggedSymbol,
             transaction_id: T.nilable(String),
             type: Increase::InboundFednowTransfer::Type::TaggedSymbol,
+            unique_end_to_end_transaction_reference: T.nilable(String),
             unstructured_remittance_information: T.nilable(String)
           }
         )

data/rbi/increase/models/inbound_mail_item.rbi

@@ -56,7 +56,9 @@ module Increase
       attr_accessor :type
 
       # Inbound Mail Items represent pieces of physical mail delivered to a Lockbox
-      # Address.
+      # Address. Increase automatically deposits checks mailed to a Lockbox Recipient
+      # into the recipient's Account. Checks that are not matched to a Lockbox Recipient
+      # must be deposited or ignored using the Action an Inbound Mail Item endpoint.
       sig do
         params(
           id: String,

data/rbi/increase/models/inbound_real_time_payments_transfer.rbi

@@ -417,7 +417,7 @@ module Increase
             Increase::InboundRealTimePaymentsTransfer::Status::TaggedSymbol
           )
 
-        # The transfer was not responded to in time.
+        # The transfer was not responded to in time. This is rare and represents an error at Increase.
         TIMED_OUT =
           T.let(
             :timed_out,

data/rbi/increase/models/lockbox_address.rbi

@@ -49,7 +49,11 @@ module Increase
       attr_accessor :type
 
       # Lockbox Addresses are physical locations that can receive mail containing paper
-      # checks.
+      # checks. A Lockbox Address is not itself linked to an Account; Lockbox Recipients
+      # determine where checks received at the address are deposited. Lockbox Addresses
+      # are created with a `pending` status and a null `address`. Increase generates the
+      # mailing address shortly after creation, at which point the status becomes
+      # `active`.
       sig do
         params(
           id: String,

data/rbi/increase/models/lockbox_recipient_create_params.rbi

@@ -18,7 +18,8 @@ module Increase
       sig { returns(String) }
       attr_accessor :account_id
 
-      # The Lockbox Address where this Lockbox Recipient may receive mail.
+      # The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+      # Address must have a `status` of `active`.
       sig { returns(String) }
       attr_accessor :lockbox_address_id
 
@@ -48,7 +49,8 @@ module Increase
       def self.new(
         # The Account that checks sent to this Lockbox Recipient should be deposited into.
         account_id:,
-        # The Lockbox Address where this Lockbox Recipient may receive mail.
+        # The Lockbox Address where this Lockbox Recipient may receive mail. The Lockbox
+        # Address must have a `status` of `active`.
         lockbox_address_id:,
         # The description you choose for the Lockbox Recipient.
         description: nil,

data/rbi/increase/models/pending_transaction.rbi

@@ -17,7 +17,10 @@ module Increase
       attr_accessor :account_id
 
       # The Pending Transaction amount in the minor unit of its currency. For dollars,
-      # for example, this is cents.
+      # for example, this is cents. This amount does not change after the Pending
+      # Transaction is created. If a card authorization settles for a different amount,
+      # the settled amount is available on the resulting Transaction and on the Card
+      # Payment's `state.settled_amount`.
       sig { returns(Integer) }
       attr_accessor :amount
 
@@ -109,7 +112,10 @@ module Increase
         # The identifier for the account this Pending Transaction belongs to.
         account_id:,
         # The Pending Transaction amount in the minor unit of its currency. For dollars,
-        # for example, this is cents.
+        # for example, this is cents. This amount does not change after the Pending
+        # Transaction is created. If a card authorization settles for a different amount,
+        # the settled amount is available on the resulting Transaction and on the Card
+        # Payment's `state.settled_amount`.
         amount:,
         # The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date on which the Pending
         # Transaction was completed.
@@ -4982,7 +4988,7 @@ module Increase
         PENDING =
           T.let(:pending, Increase::PendingTransaction::Status::TaggedSymbol)
 
-        # The Pending Transaction is confirmed. An associated Transaction exists for this object. The Pending Transaction will no longer count against your balance and can generally be hidden from UIs, etc.
+        # The Pending Transaction is confirmed. An associated Transaction exists for this object. The Pending Transaction will no longer count against your balance and can generally be hidden from UIs, etc. The Pending Transaction's `amount` is not updated if the associated Transaction settles for a different amount.
         COMPLETE =
           T.let(:complete, Increase::PendingTransaction::Status::TaggedSymbol)
 

data/rbi/increase/models/pending_transaction_list_params.rbi

@@ -473,7 +473,7 @@ module Increase
               Increase::PendingTransactionListParams::Status::In::TaggedSymbol
             )
 
-          # The Pending Transaction is confirmed. An associated Transaction exists for this object. The Pending Transaction will no longer count against your balance and can generally be hidden from UIs, etc.
+          # The Pending Transaction is confirmed. An associated Transaction exists for this object. The Pending Transaction will no longer count against your balance and can generally be hidden from UIs, etc. The Pending Transaction's `amount` is not updated if the associated Transaction settles for a different amount.
           COMPLETE =
             T.let(
               :complete,

data/rbi/increase/models/physical_card.rbi

@@ -690,14 +690,21 @@ module Increase
                   Increase::PhysicalCard::Shipment::Tracking::Update::Category::TaggedSymbol
                 )
 
-              # There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be returned to sender.
+              # There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be rerouted to the return address.
               DELIVERY_ISSUE =
                 T.let(
                   :delivery_issue,
                   Increase::PhysicalCard::Shipment::Tracking::Update::Category::TaggedSymbol
                 )
 
-              # Delivery failed and the physical card was returned to sender.
+              # The physical card has been rerouted to the return address.
+              RETURNING_TO_SENDER =
+                T.let(
+                  :returning_to_sender,
+                  Increase::PhysicalCard::Shipment::Tracking::Update::Category::TaggedSymbol
+                )
+
+              # The physical card has been delivered to the return address.
               RETURNED_TO_SENDER =
                 T.let(
                   :returned_to_sender,

data/rbi/increase/models/real_time_payments_transfer.rbi

@@ -988,6 +988,13 @@ module Increase
             Increase::RealTimePaymentsTransfer::Status::TaggedSymbol
           )
 
+        # The transfer is queued to be submitted to Real-Time Payments.
+        PENDING_SUBMISSION =
+          T.let(
+            :pending_submission,
+            Increase::RealTimePaymentsTransfer::Status::TaggedSymbol
+          )
+
         # The transfer is pending review by Increase.
         PENDING_REVIEWING =
           T.let(
@@ -1009,13 +1016,6 @@ module Increase
             Increase::RealTimePaymentsTransfer::Status::TaggedSymbol
           )
 
-        # The transfer is queued to be submitted to Real-Time Payments.
-        PENDING_SUBMISSION =
-          T.let(
-            :pending_submission,
-            Increase::RealTimePaymentsTransfer::Status::TaggedSymbol
-          )
-
         # The transfer has been submitted and is pending a response from Real-Time Payments.
         SUBMITTED =
           T.let(

data/rbi/increase/models/real_time_payments_transfer_list_params.rbi

@@ -293,6 +293,13 @@ module Increase
               Increase::RealTimePaymentsTransferListParams::Status::In::TaggedSymbol
             )
 
+          # The transfer is queued to be submitted to Real-Time Payments.
+          PENDING_SUBMISSION =
+            T.let(
+              :pending_submission,
+              Increase::RealTimePaymentsTransferListParams::Status::In::TaggedSymbol
+            )
+
           # The transfer is pending review by Increase.
           PENDING_REVIEWING =
             T.let(
@@ -314,13 +321,6 @@ module Increase
               Increase::RealTimePaymentsTransferListParams::Status::In::TaggedSymbol
             )
 
-          # The transfer is queued to be submitted to Real-Time Payments.
-          PENDING_SUBMISSION =
-            T.let(
-              :pending_submission,
-              Increase::RealTimePaymentsTransferListParams::Status::In::TaggedSymbol
-            )
-
           # The transfer has been submitted and is pending a response from Real-Time Payments.
           SUBMITTED =
             T.let(

data/rbi/increase/models/simulations/inbound_ach_transfer_create_params.rbi

@@ -71,7 +71,8 @@ module Increase
         sig { params(company_id: String).void }
         attr_writer :company_id
 
-        # The name of the sender.
+        # The name of the sender. This corresponds to the `originator_company_name` field
+        # on the resulting Inbound ACH Transfer.
         sig { returns(T.nilable(String)) }
         attr_reader :company_name
 
@@ -154,7 +155,8 @@ module Increase
           company_entry_description: nil,
           # The sender's company ID.
           company_id: nil,
-          # The name of the sender.
+          # The name of the sender. This corresponds to the `originator_company_name` field
+          # on the resulting Inbound ACH Transfer.
           company_name: nil,
           # The ID of the receiver of the transfer.
           receiver_id_number: nil,

data/rbi/increase/models/simulations/inbound_mail_item_create_params.rbi

@@ -27,14 +27,16 @@ module Increase
         sig { params(contents_file_id: String).void }
         attr_writer :contents_file_id
 
-        # The identifier of the Lockbox Address to simulate inbound mail to.
+        # The identifier of the Lockbox Address to simulate inbound mail to. Exactly one
+        # lockbox identifier parameter must be provided.
         sig { returns(T.nilable(String)) }
         attr_reader :lockbox_address_id
 
         sig { params(lockbox_address_id: String).void }
         attr_writer :lockbox_address_id
 
-        # The identifier of the Lockbox Recipient to simulate inbound mail to.
+        # The identifier of the Lockbox Recipient to simulate inbound mail to. Exactly one
+        # lockbox identifier parameter must be provided.
         sig { returns(T.nilable(String)) }
         attr_reader :lockbox_recipient_id
 
@@ -56,9 +58,11 @@ module Increase
           # The file containing the PDF contents. If not present, a default check image file
           # will be used.
           contents_file_id: nil,
-          # The identifier of the Lockbox Address to simulate inbound mail to.
+          # The identifier of the Lockbox Address to simulate inbound mail to. Exactly one
+          # lockbox identifier parameter must be provided.
           lockbox_address_id: nil,
-          # The identifier of the Lockbox Recipient to simulate inbound mail to.
+          # The identifier of the Lockbox Recipient to simulate inbound mail to. Exactly one
+          # lockbox identifier parameter must be provided.
           lockbox_recipient_id: nil,
           request_options: {}
         )

data/rbi/increase/models/simulations/physical_card_create_params.rbi

@@ -137,14 +137,21 @@ module Increase
               Increase::Simulations::PhysicalCardCreateParams::Category::TaggedSymbol
             )
 
-          # There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be returned to sender.
+          # There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the physical card will be rerouted to the return address.
           DELIVERY_ISSUE =
             T.let(
               :delivery_issue,
               Increase::Simulations::PhysicalCardCreateParams::Category::TaggedSymbol
             )
 
-          # Delivery failed and the physical card was returned to sender.
+          # The physical card has been rerouted to the return address.
+          RETURNING_TO_SENDER =
+            T.let(
+              :returning_to_sender,
+              Increase::Simulations::PhysicalCardCreateParams::Category::TaggedSymbol
+            )
+
+          # The physical card has been delivered to the return address.
           RETURNED_TO_SENDER =
             T.let(
               :returned_to_sender,

data/rbi/increase/models/swift_transfer.rbi

@@ -665,6 +665,13 @@ module Increase
         CANCELED =
           T.let(:canceled, Increase::SwiftTransfer::Status::TaggedSymbol)
 
+        # The transfer is pending initiation.
+        PENDING_INITIATING =
+          T.let(
+            :pending_initiating,
+            Increase::SwiftTransfer::Status::TaggedSymbol
+          )
+
         # The transfer is pending review by Increase.
         PENDING_REVIEWING =
           T.let(
@@ -679,13 +686,6 @@ module Increase
             Increase::SwiftTransfer::Status::TaggedSymbol
           )
 
-        # The transfer is pending initiation.
-        PENDING_INITIATING =
-          T.let(
-            :pending_initiating,
-            Increase::SwiftTransfer::Status::TaggedSymbol
-          )
-
         # The transfer has been initiated.
         INITIATED =
           T.let(:initiated, Increase::SwiftTransfer::Status::TaggedSymbol)

data/rbi/increase/models/swift_transfer_list_params.rbi

@@ -258,6 +258,13 @@ module Increase
               Increase::SwiftTransferListParams::Status::In::TaggedSymbol
             )
 
+          # The transfer is pending initiation.
+          PENDING_INITIATING =
+            T.let(
+              :pending_initiating,
+              Increase::SwiftTransferListParams::Status::In::TaggedSymbol
+            )
+
           # The transfer is pending review by Increase.
           PENDING_REVIEWING =
             T.let(
@@ -272,13 +279,6 @@ module Increase
               Increase::SwiftTransferListParams::Status::In::TaggedSymbol
             )
 
-          # The transfer is pending initiation.
-          PENDING_INITIATING =
-            T.let(
-              :pending_initiating,
-              Increase::SwiftTransferListParams::Status::In::TaggedSymbol
-            )
-
           # The transfer has been initiated.
           INITIATED =
             T.let(

data/rbi/increase/models/transaction.rbi

@@ -284,7 +284,8 @@ module Increase
         # Return is created when an ACH Transfer is returned by the receiving bank. It
         # offsets the ACH Transfer Intention. ACH Transfer Returns usually occur within
         # the first two business days after the transfer is initiated, but can occur much
-        # later.
+        # later. The return appears as a new posted Transaction; no Pending Transaction is
+        # created.
         sig do
           returns(T.nilable(Increase::Transaction::Source::ACHTransferReturn))
         end
@@ -1116,7 +1117,8 @@ module Increase
           # Return is created when an ACH Transfer is returned by the receiving bank. It
           # offsets the ACH Transfer Intention. ACH Transfer Returns usually occur within
           # the first two business days after the transfer is initiated, but can occur much
-          # later.
+          # later. The return appears as a new posted Transaction; no Pending Transaction is
+          # created.
           ach_transfer_return: nil,
           # A Blockchain Off-Ramp Transfer Settlement object. This field will be present in
           # the JSON response if and only if `category` is equal to
@@ -1997,7 +1999,8 @@ module Increase
           sig { returns(String) }
           attr_accessor :transaction_id
 
-          # The identifier of the ACH Transfer associated with this return.
+          # The identifier of the ACH Transfer associated with this return. This matches the
+          # original Transaction's `source.ach_transfer_intention.transfer_id`.
           sig { returns(String) }
           attr_accessor :transfer_id
 
@@ -2006,7 +2009,8 @@ module Increase
           # Return is created when an ACH Transfer is returned by the receiving bank. It
           # offsets the ACH Transfer Intention. ACH Transfer Returns usually occur within
           # the first two business days after the transfer is initiated, but can occur much
-          # later.
+          # later. The return appears as a new posted Transaction; no Pending Transaction is
+          # created.
           sig do
             params(
               created_at: Time,
@@ -2034,7 +2038,8 @@ module Increase
             trace_number:,
             # The identifier of the Transaction associated with this return.
             transaction_id:,
-            # The identifier of the ACH Transfer associated with this return.
+            # The identifier of the ACH Transfer associated with this return. This matches the
+            # original Transaction's `source.ach_transfer_intention.transfer_id`.
             transfer_id:
           )
           end

data/rbi/increase/models/wire_transfer.rbi

@@ -1327,6 +1327,10 @@ module Increase
         CANCELED =
           T.let(:canceled, Increase::WireTransfer::Status::TaggedSymbol)
 
+        # The transfer is pending creation.
+        PENDING_CREATING =
+          T.let(:pending_creating, Increase::WireTransfer::Status::TaggedSymbol)
+
         # The transfer is pending review by Increase.
         PENDING_REVIEWING =
           T.let(
@@ -1345,10 +1349,6 @@ module Increase
             Increase::WireTransfer::Status::TaggedSymbol
           )
 
-        # The transfer is pending creation.
-        PENDING_CREATING =
-          T.let(:pending_creating, Increase::WireTransfer::Status::TaggedSymbol)
-
         # The transfer has been reversed.
         REVERSED =
           T.let(:reversed, Increase::WireTransfer::Status::TaggedSymbol)