straddle 0.5.0 → 1.0.0

data/rbi/straddle/resources/payouts.rbi

@@ -2,69 +2,87 @@
 
 module Straddle
   module Resources
-    # Payouts represent transfers from Straddle to customer bank accounts. Create
-    # payouts to handle disbursements, process refunds, or manage marketplace
-    # settlements. Use payouts to send money quickly and securely with the most
-    # cost-effective rail automatically selected.
+    # Payouts send money to a customer's bank account through a paykey.
     class Payouts
-      # Use payouts to send money to your customers.
+      # Creates a payout to a customer's bank account. Straddle submits the payout for
+      # processing on `payment_date` unless the payout is on hold.
       sig do
         params(
           amount: Integer,
           currency: String,
           description: T.nilable(String),
-          device: Straddle::DeviceInfoV1::OrHash,
+          device: Straddle::PaymentDevice::OrHash,
           external_id: String,
           paykey: String,
           payment_date: Date,
-          config: Straddle::PayoutCreateParams::Config::OrHash,
+          config: Straddle::PayoutConfiguration::OrHash,
           metadata: T.nilable(T::Hash[Symbol, String]),
           correlation_id: String,
           idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
       def create(
-        # Body param: The amount of the payout in cents.
+        # Body param: Amount in cents.
         amount:,
-        # Body param: The currency of the payout. Only USD is supported.
+        # Body param: Currency code. Only `USD` is supported.
         currency:,
-        # Body param: An arbitrary description for the payout.
+        # Body param: Description shown on the customer's bank statement where supported.
         description:,
-        # Body param: Information about the device used when the customer authorized the
-        # payout.
+        # Body param: Device used when the customer authorized the payout.
         device:,
-        # Body param: Unique identifier for the payout in your database. This value must
-        # be unique across all payouts.
+        # Body param: Your unique identifier for the payout. Must be unique across
+        # payouts.
         external_id:,
-        # Body param: Value of the `paykey` used for the payout.
+        # Body param: The paykey token that identifies the customer's bank account.
         paykey:,
-        # Body param: The desired date on which the payout should be occur. For payouts,
-        # this means the date you want the funds to be sent from your bank account.
+        # Body param: Date when Straddle submits the payout for processing.
         payment_date:,
         # Body param
         config: nil,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the payout in a structured format.
+        # Body param: Up to 20 user-defined string key-value pairs.
         metadata: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Update the details of a payout prior to processing. The status of the payout
-      # must be `created`, `scheduled`, or `on_hold`.
+      # Returns a payout by its unique identifier.
+      sig do
+        params(
+          id: String,
+          correlation_id: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::PayoutResponse)
+      end
+      def retrieve(
+        # Unique identifier for the payout.
+        id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        # For platform requests, the embedded account UUID that sets the request scope.
+        straddle_account_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Updates the description, amount, `payment_date`, or metadata. The payout must
+      # have a status of `created` or `on_hold`.
       sig do
         params(
           id: String,
@@ -77,178 +95,197 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
       def update(
-        # Path param
+        # Path param: Unique identifier for the payout.
         id,
-        # Body param: The amount of the payout in cents.
+        # Body param: Amount in cents.
         amount:,
-        # Body param: An arbitrary description for the payout.
+        # Body param: Updated description for the payout.
         description:,
-        # Body param: The desired date on which the payment should be occur. For payouts,
-        # this means the date you want the funds to be sent from your bank account.
+        # Body param: New date for Straddle to submit the payout for processing.
         payment_date:,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the payout in a structured format.
+        # Body param: Replacement metadata for the payout. Up to 20 user-defined string
+        # key-value pairs.
         metadata: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Cancel a payout to prevent it from being processed. The status of the payout
-      # must be `created`, `scheduled`, or `on_hold`.
+      # Cancels a payout. The payout must have a status of `created`, `scheduled`, or
+      # `on_hold`.
       sig do
         params(
           id: String,
-          reason: String,
+          reason: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
       def cancel(
-        # Path param
+        # Path param: Unique identifier for the payout.
         id,
-        # Body param: Details about why the payout status was updated.
-        reason:,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Body param: Message explaining the payout status change.
+        reason: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Retrieves the details of an existing payout. Supply the unique payout `id` to
-      # retrieve the corresponding payout information.
+      # Places a payout on hold to prevent submission for processing. The payout must
+      # have a status of `created` or `scheduled`.
       sig do
         params(
           id: String,
+          reason: T.nilable(String),
           correlation_id: String,
+          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
-      def get(
+      def hold(
+        # Path param: Unique identifier for the payout.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Body param: Message explaining the payout status change.
+        reason: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Hold a payout to prevent it from being processed. The status of the payout must
-      # be `created`, `scheduled`, or `on_hold`.
+      # Return a payout with its sensitive fields unmasked.
       sig do
         params(
           id: String,
-          reason: String,
           correlation_id: String,
-          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::UnmaskedPayoutResponse)
       end
-      def hold(
-        # Path param
+      def list_unmasked(
+        # Unique identifier for the payout.
         id,
-        # Body param: Details about why the payout status was updated.
-        reason:,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Optional client-generated identifier for tracing a series of related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
-        idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # For platform requests, the embedded account UUID that sets the request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Release a payout from a `hold` status to allow it to be rescheduled for
-      # processing.
+      # Releases a payout from `on_hold` and returns it to `created` for submission on
+      # `payment_date`.
       sig do
         params(
           id: String,
-          reason: String,
+          reason: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
       def release(
-        # Path param
+        # Path param: Unique identifier for the payout.
         id,
-        # Body param: Details about why the payout status was updated.
-        reason:,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Body param: Message explaining the payout status change.
+        reason: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Get a payout by id.
+      # Creates a new payout from a failed, reversed, or cancelled payout. The request
+      # can override `description`, `external_id`, and `payment_date`. Other payment
+      # details come from the original payout.
       sig do
         params(
           id: String,
+          description: T.nilable(String),
+          external_id: T.nilable(String),
+          payment_date: T.nilable(Date),
           correlation_id: String,
+          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::Models::PayoutUnmaskResponse)
+        ).returns(Straddle::PayoutResponse)
       end
-      def unmask(
+      def resubmit(
+        # Path param: Unique identifier for the payout.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Body param: Description for the resubmitted payout. Defaults to the original
+        # description if omitted.
+        description: nil,
+        # Body param: Your unique identifier for the resubmitted payout. Defaults to a new
+        # value if omitted.
+        external_id: nil,
+        # Body param: Date when Straddle submits the resubmitted payout for processing.
+        # Defaults to today if omitted.
+        payment_date: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Uploads a document as proof of authorization for a payout. Uploading again adds
-      # another entry to documents rather than replacing the previous one.
+      # Uploads a proof-of-authorization document for a payout. A later upload adds
+      # another document and does not replace an existing one.
       sig do
         params(
           id: String,
@@ -258,23 +295,26 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PayoutV1)
+        ).returns(Straddle::PayoutResponse)
       end
-      def upload_authorization_document(
-        # Path param
+      def upload_authorization_proof(
+        # Path param: Unique identifier for the payout.
         id,
         # Body param: The document file to upload as proof of authorization for this
-        # payout.
+        # payout. Supported file types are PDF (.pdf), PNG (.png), JPEG (.jpg, .jpeg),
+        # Word (.doc), and Word (.docx), with a maximum file size of 10 MiB (10,485,760
+        # bytes). Empty (0-byte) files are rejected. Uploaded files are validated for
+        # matching file signatures (magic bytes) and file extension agreement.
         file:,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )

data/rbi/straddle/resources/representatives.rbi

@@ -0,0 +1,203 @@
+# typed: strong
+
+module Straddle
+  module Resources
+    # Representatives are people associated with a business account for ownership,
+    # control, or authorization purposes.
+    class Representatives
+      # Creates a representative for an account and returns the representative.
+      # Relationship fields identify primary representatives, control persons, and
+      # owners.
+      sig do
+        params(
+          account_id: String,
+          dob: Date,
+          email: String,
+          first_name: String,
+          last_name: String,
+          mobile_number: String,
+          relationship: Straddle::RepresentativeRelationship::OrHash,
+          ssn_last4: String,
+          external_id: T.nilable(String),
+          metadata: T.nilable(T::Hash[Symbol, String]),
+          correlation_id: String,
+          idempotency_key: String,
+          request_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::RepresentativeResponse)
+      end
+      def create(
+        # Body param: ID of the account associated with the representative.
+        account_id:,
+        # Body param: Representative's date of birth in `YYYY-MM-DD` format.
+        dob:,
+        # Body param: Representative's company email address.
+        email:,
+        # Body param: Representative's first name.
+        first_name:,
+        # Body param: Representative's last name.
+        last_name:,
+        # Body param: Representative's mobile phone number in E.164 format.
+        mobile_number:,
+        # Body param
+        relationship:,
+        # Body param: Last four digits of the representative's Social Security number.
+        ssn_last4:,
+        # Body param: Your unique ID for the representative.
+        external_id: nil,
+        # Body param: Up to 20 user-defined key-value pairs.
+        metadata: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
+        correlation_id: nil,
+        # Header param: Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns the representative with the specified ID.
+      sig do
+        params(
+          representative_id: String,
+          correlation_id: String,
+          request_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::RepresentativeResponse)
+      end
+      def retrieve(
+        # The ID of the representative.
+        representative_id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Updates a representative's personal, contact, relationship, external ID, and
+      # metadata fields, then returns the representative.
+      sig do
+        params(
+          representative_id: String,
+          dob: Date,
+          email: String,
+          first_name: String,
+          last_name: String,
+          mobile_number: String,
+          relationship: Straddle::RepresentativeRelationship::OrHash,
+          ssn_last4: String,
+          external_id: T.nilable(String),
+          metadata: T.nilable(T::Hash[Symbol, String]),
+          correlation_id: String,
+          idempotency_key: String,
+          request_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::RepresentativeResponse)
+      end
+      def update(
+        # Path param: The ID of the representative.
+        representative_id,
+        # Body param: Representative's date of birth in `YYYY-MM-DD` format.
+        dob:,
+        # Body param: Representative's email address.
+        email:,
+        # Body param: Representative's first name.
+        first_name:,
+        # Body param: Representative's last name.
+        last_name:,
+        # Body param: Representative's mobile phone number in E.164 format.
+        mobile_number:,
+        # Body param
+        relationship:,
+        # Body param: Last four digits of the representative's Social Security number.
+        ssn_last4:,
+        # Body param: Your unique ID for the representative.
+        external_id: nil,
+        # Body param: Up to 20 user-defined key-value pairs.
+        metadata: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
+        correlation_id: nil,
+        # Header param: Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns a paginated list of representatives. Filter the list by account,
+      # organization, platform, or scope.
+      sig do
+        params(
+          account_id: String,
+          level: Straddle::RepresentativeListParams::Level::OrSymbol,
+          organization_id: String,
+          page_number: Integer,
+          page_size: Integer,
+          platform_id: String,
+          sort_by: String,
+          sort_order: Straddle::RepresentativeListParams::SortOrder::OrSymbol,
+          correlation_id: String,
+          request_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::RepresentativeList)
+      end
+      def list(
+        # Query param: Account ID used to filter the results.
+        account_id: nil,
+        # Query param: Scope of representatives to return.
+        level: nil,
+        # Query param: Organization ID used to filter the results.
+        organization_id: nil,
+        # Query param: Page number. Defaults to `1`.
+        page_number: nil,
+        # Query param: Number of results per page. Defaults to `100`. Maximum `1000`.
+        page_size: nil,
+        # Query param: Platform ID used to filter the results.
+        platform_id: nil,
+        # Query param: Field used to sort results. Defaults to `id`.
+        sort_by: nil,
+        # Query param: Sort direction. Defaults to `asc`.
+        sort_order: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
+        correlation_id: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns the representative with the specified ID without masking sensitive
+      # fields. This endpoint requires an administrator role.
+      sig do
+        params(
+          representative_id: String,
+          correlation_id: String,
+          request_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::UnmaskedRepresentativeResponse)
+      end
+      def list_unmasked(
+        # The ID of the representative.
+        representative_id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Straddle::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end