straddle 0.5.0 → 1.0.0

data/rbi/straddle/resources/charges.rbi

@@ -2,21 +2,18 @@
 
 module Straddle
   module Resources
-    # Charges represent attempts to debit money from a customer's bank account using a
-    # Paykey. Each charge includes automatic balance verification, real-time fraud
-    # screening, and multi-rail optimization and detailed status tracking throughout
-    # the payment lifecycle. Use charges to accept bank payments with confidence
-    # knowing every transaction is protected.
+    # Charges debit a customer's bank account through a paykey.
     class Charges
-      # Use charges to collect money from a customer for the sale of goods or services.
+      # Creates a charge against a customer's paykey. Straddle submits the charge for
+      # processing on `payment_date` unless the charge is on hold.
       sig do
         params(
           amount: Integer,
-          config: Straddle::ChargeCreateParams::Config::OrHash,
-          consent_type: Straddle::ChargeCreateParams::ConsentType::OrSymbol,
+          config: Straddle::ChargeConfiguration::OrHash,
+          consent_type: Straddle::ConsentType::OrSymbol,
           currency: String,
           description: T.nilable(String),
-          device: Straddle::DeviceInfoV1::OrHash,
+          device: Straddle::PaymentDevice::OrHash,
           external_id: String,
           paykey: String,
           payment_date: Date,
@@ -26,51 +23,70 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::ChargeV1)
+        ).returns(Straddle::ChargeResponse)
       end
       def create(
-        # Body param: The amount of the charge in cents.
+        # Body param: Amount in cents.
         amount:,
         # Body param
         config:,
-        # Body param: The channel or mechanism through which the payment was authorized.
-        # Use `internet` for payments made online or through a mobile app and `signed` for
-        # signed agreements where there is a consent form or contract. Use `signed` for
-        # PDF signatures.
+        # Body param: How the customer authorized the charge. `internet` covers online and
+        # mobile authorization. `signed` covers written or PDF-signed agreements.
         consent_type:,
-        # Body param: The currency of the charge. Only USD is supported.
+        # Body param: Currency code. Only `USD` is supported.
         currency:,
-        # Body param: An arbitrary description for the charge.
+        # Body param: Description shown on the customer's bank statement where supported.
         description:,
         # Body param
         device:,
-        # Body param: Unique identifier for the charge in your database. This value must
-        # be unique across all charges.
+        # Body param: Your unique identifier for the charge. Must be unique across
+        # charges.
         external_id:,
-        # Body param: Value of the `paykey` used for the charge.
+        # Body param: The paykey token that identifies the customer's bank account.
         paykey:,
-        # Body param: The desired date on which the payment should be occur. For charges,
-        # this means the date you want the customer to be debited on.
+        # Body param: Date when Straddle submits the charge for processing.
         payment_date:,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the charge 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
 
-      # Change the values of parameters associated with a charge prior to processing.
-      # The status of the charge must be `created`, `scheduled`, or `on_hold`.
+      # Returns a charge 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::ChargeResponse)
+      end
+      def retrieve(
+        # Unique identifier for the charge.
+        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 charge must
+      # have a status of `created` or `on_hold`.
       sig do
         params(
           id: String,
@@ -83,37 +99,36 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::ChargeV1)
+        ).returns(Straddle::ChargeResponse)
       end
       def update(
-        # Path param
+        # Path param: Unique identifier for the charge.
         id,
-        # Body param: The amount of the charge in cents.
+        # Body param: Amount in cents.
         amount:,
-        # Body param: An arbitrary description for the charge.
+        # Body param: Updated description for the charge.
         description:,
-        # Body param: The desired date on which the payment should be occur. For charges,
-        # this means the date you want the customer to be debited on.
+        # Body param: New date for Straddle to submit the charge for processing.
         payment_date:,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the charge in a structured format.
+        # Body param: Replacement metadata for the charge. 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 charge to prevent it from being originated for processing. The status
-      # of the charge must be `created`, `scheduled`, or `on_hold`.
+      # Cancels a charge. The charge must have a status of `created`, `scheduled`, or
+      # `on_hold`.
       sig do
         params(
           id: String,
@@ -123,84 +138,133 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::ChargeV1)
+        ).returns(Straddle::ChargeResponse)
       end
       def cancel(
-        # Path param
+        # Path param: Unique identifier for the charge.
         id,
-        # Body param: Details about why the charge status was updated.
+        # Body param: Message explaining the charge status change.
         reason: 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
 
-      # Retrieves the details of an existing charge. Supply the unique charge `id`, and
-      # Straddle will return the corresponding charge information.
+      # Places a charge on hold to prevent submission for processing. The charge 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::ChargeV1)
+        ).returns(Straddle::ChargeResponse)
       end
-      def get(
+      def hold(
+        # Path param: Unique identifier for the charge.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Body param: Message explaining the charge 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
 
-      # Place a charge on hold to prevent it from being originated for processing. The
-      # status of the charge must be `created` or `scheduled`.
+      # Return a charge with its sensitive fields unmasked.
       sig do
         params(
           id: String,
-          reason: T.nilable(String),
+          correlation_id: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::UnmaskedChargeResponse)
+      end
+      def list_unmasked(
+        # Unique identifier for the charge.
+        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
+
+      # Creates a payout to return funds from a paid charge to the customer's bank
+      # account. The payout is linked to the charge through `related_payments`. A charge
+      # can be refunded once, either fully or partially.
+      sig do
+        params(
+          id: String,
+          amount: T.nilable(Integer),
+          description: T.nilable(String),
+          external_id: T.nilable(String),
+          metadata: T.nilable(T::Hash[Symbol, 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::ChargeV1)
+        ).returns(Straddle::PayoutResponse)
       end
-      def hold(
-        # Path param
+      def refund(
+        # Path param: Unique identifier for the charge.
         id,
-        # Body param: Details about why the charge status was updated.
-        reason: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Body param: Refund amount in cents. `null` refunds the full original amount. A
+        # value must be greater than zero and no more than the original charge amount.
+        amount: nil,
+        # Body param: Description for the refund payout. Defaults to a description that
+        # identifies the original charge.
+        description: nil,
+        # Body param: Your unique identifier for the refund. Defaults to a new value if
+        # omitted.
+        external_id: nil,
+        # Body param: User-defined string key-value pairs for the refund payout.
+        metadata: nil,
+        # Body param: Date when Straddle submits the refund 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,
-        # 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
 
-      # Release a charge from an `on_hold` status to allow it to be rescheduled for
-      # processing.
+      # Releases a charge from `on_hold` and returns it to `created` for submission on
+      # `payment_date`.
       sig do
         params(
           id: String,
@@ -210,44 +274,100 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::ChargeV1)
+        ).returns(Straddle::ChargeResponse)
       end
       def release(
-        # Path param
+        # Path param: Unique identifier for the charge.
         id,
-        # Body param: Details about why the charge status was updated.
+        # Body param: Message explaining the charge status change.
         reason: 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 key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
+        straddle_account_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Creates a new charge from a failed, reversed, or cancelled charge. The request
+      # can override `description`, `external_id`, and `payment_date`. Other payment
+      # details come from the original charge.
+      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::ChargeResponse)
+      end
+      def resubmit(
+        # Path param: Unique identifier for the charge.
+        id,
+        # Body param: Description for the resubmitted charge. Defaults to the original
+        # description if omitted.
+        description: nil,
+        # Body param: Your unique identifier for the resubmitted charge. Defaults to a new
+        # value if omitted.
+        external_id: nil,
+        # Body param: Date when Straddle submits the resubmitted charge 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,
-        # 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 charge by id.
+      # Uploads a proof-of-authorization document for a charge. A later upload adds
+      # another document and does not replace an existing one.
       sig do
         params(
           id: String,
+          file: Straddle::Internal::FileInput,
           correlation_id: String,
+          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::Models::ChargeUnmaskResponse)
+        ).returns(Straddle::ChargeResponse)
       end
-      def unmask(
+      def upload_authorization_proof(
+        # Path param: Unique identifier for the charge.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Body param: The document file to upload as proof of authorization for this
+        # charge. 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 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: {}
       )

data/rbi/straddle/resources/customers/review.rbi

@@ -3,56 +3,12 @@
 module Straddle
   module Resources
     class Customers
-      # Customers represent the end users who send or receive payments through your
-      # integration. Each customer undergoes automatic identity verification and fraud
-      # screening upon creation. Use customers to track payment history, manage bank
-      # account connections, and maintain a secure record of all transactions associated
-      # with a user. Customers can be either individuals or businesses with appropriate
-      # compliance checks for each type.
+      # Customers are individuals or businesses that send or receive payments through
+      # your integration.
       class Review
-        # Updates the status of a customer's identity decision. This endpoint allows you
-        # to modify the outcome of a customer risk screening and is useful for correcting
-        # or updating the status of a customer's verification. Note that this endpoint is
-        # only available for customers with a current status of `review`.
-        sig do
-          params(
-            id: String,
-            status: Straddle::Customers::ReviewDecisionParams::Status::OrSymbol,
-            correlation_id: String,
-            idempotency_key: String,
-            request_id: String,
-            straddle_account_id: String,
-            request_options: Straddle::RequestOptions::OrHash
-          ).returns(Straddle::CustomerV1)
-        end
-        def decision(
-          # Path param
-          id,
-          # Body param: The final status of the customer review.
-          status:,
-          # Header param: Optional client generated identifier to trace and debug a series
-          # of 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.
-          request_id: nil,
-          # Header param: For use by platforms to specify an account id and set scope of a
-          # request.
-          straddle_account_id: nil,
-          request_options: {}
-        )
-        end
-
-        # Retrieves and analyzes the results of a customer's identity validation and fraud
-        # score. This endpoint provides a comprehensive breakdown of the validation
-        # outcome, including:
-        #
-        # - Risk and correlation scores
-        # - Reason codes for the decision
-        # - Results of watchlist screening
-        # - Any network alerts detected Use this endpoint to gain insights into the
-        #   verification process and make informed decisions about customer onboarding.
+        # Returns the results of a customer's identity and fraud review. The response
+        # includes decisions, risk and correlation scores, reason codes, watchlist
+        # matches, and network alerts.
         sig do
           params(
             id: String,
@@ -60,42 +16,49 @@ module Straddle
             request_id: String,
             straddle_account_id: String,
             request_options: Straddle::RequestOptions::OrHash
-          ).returns(Straddle::Customers::CustomerReviewV1)
+          ).returns(Straddle::Customers::CustomerReviewResponse)
         end
-        def get(
+        def list(
+          # Unique identifier for the customer.
           id,
-          # 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,
-          # Optional client generated identifier to trace and debug a request.
+          # 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.
+          # For platform requests, the embedded account UUID that sets the request scope.
           straddle_account_id: nil,
           request_options: {}
         )
         end
 
-        # Updates the decision of a customer's identity validation. This endpoint allows
-        # you to modify the outcome of a customer decision and is useful for correcting or
-        # updating the status of a customer's verification.
+        # Updates the verification decision for a customer. The customer's current
+        # `status` must be `review`.
         sig do
           params(
             id: String,
+            status:
+              Straddle::Customers::ReviewSetVerificationDecisionParams::Status::OrSymbol,
             correlation_id: String,
             idempotency_key: String,
             request_id: String,
             straddle_account_id: String,
             request_options: Straddle::RequestOptions::OrHash
-          ).returns(Straddle::CustomerV1)
+          ).returns(Straddle::CustomerResponse)
         end
-        def refresh_review(
+        def set_verification_decision(
+          # Path param: Unique identifier for the customer.
           id,
-          # Optional client generated identifier to trace and debug a series of requests.
+          # Body param: The final status of the customer review.
+          status:,
+          # Header param: Optional client-generated identifier for tracing a series of
+          # related requests.
           correlation_id: nil,
-          # Optional client generated value to use for idempotent requests.
+          # Header param: Optional client-generated key for an idempotent request.
           idempotency_key: nil,
-          # Optional client generated identifier to trace and debug a request.
+          # 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: {}
         )