straddle 0.5.0 → 1.0.0

data/rbi/straddle/resources/paykeys.rbi

@@ -2,22 +2,40 @@
 
 module Straddle
   module Resources
-    # Paykeys are secure tokens that link verified customer identities to their bank
-    # accounts. Each Paykey includes built-in balance checking, fraud detection
-    # through LSTM machine learning models, and can be reused for subscriptions and
-    # recurring payments without storing sensitive data. Paykeys eliminate fraud by
-    # ensuring the person initiating payment owns the funding account.
+    # A paykey links a verified customer to a bank account without exposing bank
+    # account details. Use a paykey to create charges and payouts.
     class Paykeys
-      # Paykeys are secure tokens that link verified customer identities to their bank
-      # accounts. Each Paykey includes built-in balance checking, fraud detection
-      # through LSTM machine learning models, and can be reused for subscriptions and
-      # recurring payments without storing sensitive data. Paykeys eliminate fraud by
-      # ensuring the person initiating payment owns the funding account.
+      # A paykey links a verified customer to a bank account without exposing bank
+      # account details. Use a paykey to create charges and payouts.
       sig { returns(Straddle::Resources::Paykeys::Review) }
       attr_reader :review
 
-      # Returns a list of paykeys associated with a Straddle account. This endpoint
-      # supports advanced sorting and filtering options.
+      # Returns a paykey by `id`, including the masked paykey value and bank account
+      # details.
+      sig do
+        params(
+          id: String,
+          correlation_id: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::PaykeyResponse)
+      end
+      def retrieve(
+        # Unique identifier for the paykey.
+        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
+
+      # Returns a paginated list of paykeys for the account. Optional query parameters
+      # filter, search, and sort the results.
       sig do
         params(
           created_from: Time,
@@ -27,19 +45,15 @@ module Straddle
           page_size: Integer,
           search_text: String,
           sort_by: Straddle::PaykeyListParams::SortBy::OrSymbol,
-          sort_order: Straddle::PaykeyListParams::SortOrder::OrSymbol,
-          source: T::Array[Straddle::PaykeyListParams::Source::OrSymbol],
-          status: T::Array[Straddle::PaykeyListParams::Status::OrSymbol],
+          sort_order: Straddle::SortOrder::OrSymbol,
+          source: T::Array[Straddle::PaykeySource::OrSymbol],
+          status: T::Array[Straddle::PaykeyStatus::OrSymbol],
           unblock_eligible: T::Boolean,
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(
-          Straddle::Internal::PageNumberSchema[
-            Straddle::PaykeySummaryPagedV1::Data
-          ]
-        )
+        ).returns(Straddle::PaykeySummaryList)
       end
       def list(
         # Query param: Start date for filtering by creation date.
@@ -54,31 +68,31 @@ module Straddle
         page_size: nil,
         # Query param: General search term to filter paykeys.
         search_text: nil,
-        # Query param
+        # Query param: Field used to sort the results.
         sort_by: nil,
-        # Query param
+        # Query param: Order in which to sort the results.
         sort_order: nil,
         # Query param: Filter paykeys by their source.
         source: nil,
         # Query param: Filter paykeys by their current status.
         status: nil,
-        # Query param: Filter paykeys by unblock eligibility. When true, returns only
-        # blocked paykeys eligible for client-initiated unblocking (blocked due to R29
-        # returns and not previously unblocked). When false, returns only blocked paykeys
-        # that are not eligible for unblocking.
+        # Query param: Filters paykeys by unblock eligibility. `true` returns blocked
+        # paykeys that are eligible because of an `R29` return and have not been unblocked
+        # before. `false` returns blocked paykeys that are not eligible.
         unblock_eligible: 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 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
 
+      # Cancels a paykey so it cannot be used for new payments.
       sig do
         params(
           id: String,
@@ -88,30 +102,30 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PaykeyV1)
+        ).returns(Straddle::PaykeyResponse)
       end
       def cancel(
-        # Path param
+        # Path param: Unique identifier for the paykey.
         id,
-        # Body param
+        # Body param: Reason for canceling the paykey.
         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 paykey. Supply the unique paykey `id` and
-      # Straddle will return the corresponding paykey record , including the `paykey`
-      # token value and masked bank account details.
+      # Returns a paykey by `id`, including the full paykey value and unmasked bank
+      # account details. Straddle must enable this endpoint for your account. Use this
+      # endpoint only when unmasked data is necessary.
       sig do
         params(
           id: String,
@@ -119,48 +133,77 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PaykeyV1)
+        ).returns(Straddle::UnmaskedPaykeyResponse)
       end
-      def get(
+      def list_unmasked(
+        # Unique identifier for the paykey.
         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
 
-      # Retrieves the details of a paykey that has previously been created. Supply the
-      # unique paykey ID that was returned from your previous request, and Straddle will
-      # return the corresponding paykey information including the unmasked token.
+      # Starts an asynchronous balance refresh for a paykey. The response returns the
+      # paykey before the refresh finishes.
       sig do
         params(
           id: String,
           correlation_id: String,
+          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::Models::PaykeyRevealResponse)
+        ).returns(Straddle::PaykeyResponse)
       end
-      def reveal(
+      def refresh_balance(
+        # Unique identifier for the paykey.
+        id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated key for an idempotent request.
+        idempotency_key: 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
+
+      # Starts a new verification review for a paykey. The review runs asynchronously.
+      # Webhooks and the paykey review endpoint return updated results.
+      sig do
+        params(
+          id: String,
+          correlation_id: String,
+          idempotency_key: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::PaykeyResponse)
+      end
+      def refresh_review(
+        # Unique identifier for the paykey.
         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 key for an idempotent request.
+        idempotency_key: nil,
+        # 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
 
-      # Retrieves the unmasked details of an existing paykey. Supply the unique paykey
-      # `id` and Straddle will return the corresponding paykey record, including the
-      # unmasked bank account details. This endpoint needs to be enabled by Straddle for
-      # your account and should only be used when absolutely necessary.
+      # Returns a paykey by `id`, including the full paykey value and masked bank
+      # account details.
       sig do
         params(
           id: String,
@@ -168,41 +211,48 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PaykeyUnmaskedV1)
+        ).returns(Straddle::RevealedPaykeyResponse)
       end
-      def unmasked(
+      def reveal(
+        # Unique identifier for the paykey.
         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 balance of a paykey. This endpoint allows you to refresh the balance
-      # of a paykey.
+      # Unblocks a paykey that was blocked by an `R29` return. The paykey must not have
+      # been unblocked before.
       sig do
         params(
           id: String,
+          message: T.nilable(String),
           correlation_id: String,
           idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::PaykeyV1)
+        ).returns(Straddle::PaykeyResponse)
       end
-      def update_balance(
+      def unblock(
+        # Path param: Unique identifier for the paykey.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Body param: Optional message describing the reason for unblocking.
+        message: nil,
+        # 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: {}
       )

data/rbi/straddle/resources/payments.rbi

@@ -2,18 +2,15 @@
 
 module Straddle
   module Resources
-    # Payments provide endpoints to filter both Charges and Payouts with multiple
-    # different parameters.
+    # Payments provide a combined view of charges and payouts.
     class Payments
-      # Search for payments, including `charges` and `payouts`, using a variety of
-      # criteria. This endpoint supports advanced sorting and filtering options.
+      # Returns a paged list of charges and payouts that match the filters.
       sig do
         params(
           customer_id: String,
           default_page_size: Integer,
           default_sort: Straddle::PaymentListParams::DefaultSort::OrSymbol,
-          default_sort_order:
-            Straddle::PaymentListParams::DefaultSortOrder::OrSymbol,
+          default_sort_order: Straddle::SortOrder::OrSymbol,
           external_id: String,
           funding_id: String,
           has_refund: T::Boolean,
@@ -36,106 +33,96 @@ module Straddle
           paykey: String,
           paykey_id: String,
           payment_id: String,
-          payment_status:
-            T::Array[Straddle::PaymentListParams::PaymentStatus::OrSymbol],
-          payment_type:
-            T::Array[Straddle::PaymentListParams::PaymentType::OrSymbol],
+          payment_status: T::Array[Straddle::PaymentStatus::OrSymbol],
+          payment_type: T::Array[Straddle::PaymentType::OrSymbol],
           search_text: String,
           sort_by: Straddle::PaymentListParams::SortBy::OrSymbol,
-          sort_order: Straddle::PaymentListParams::SortOrder::OrSymbol,
-          status_reason:
-            T::Array[Straddle::PaymentListParams::StatusReason::OrSymbol],
-          status_source:
-            T::Array[Straddle::PaymentListParams::StatusSource::OrSymbol],
+          sort_order: Straddle::SortOrder::OrSymbol,
+          status_reason: T::Array[Straddle::PaymentStatusReason::OrSymbol],
+          status_source: T::Array[Straddle::PaymentStatusSource::OrSymbol],
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(
-          Straddle::Internal::PageNumberSchema[
-            Straddle::PaymentSummaryPagedV1::Data
-          ]
-        )
+        ).returns(Straddle::PaymentSummaryList)
       end
       def list(
-        # Query param: Search using the `customer_id` of a `charge` or `payout`.
+        # Query param: Filter by the unique identifier of the customer.
         customer_id: nil,
-        # Query param
+        # Query param: Default number of results returned per page.
         default_page_size: nil,
-        # Query param: The field to sort the results by.
+        # Query param: Default field used to sort the results.
         default_sort: nil,
-        # Query param
+        # Query param: Default order in which to sort the results.
         default_sort_order: nil,
-        # Query param: Search using the `external_id` of a `charge` or `payout`.
+        # Query param: Filter by your external identifier for the payment.
         external_id: nil,
-        # Query param: Search using the `funding_id` of a `charge` or `payout`.
+        # Query param: Filter by the unique identifier of a funding event.
         funding_id: nil,
-        # Query param: Has the payment been refunded by an associated payout (only
-        # applicable to charges).
+        # Query param: Filter charges by whether an associated payout has refunded them.
         has_refund: nil,
-        # Query param: Has the payment been resubmitted.
+        # Query param: Filter payments by whether they have been resubmitted.
         has_resubmit: nil,
-        # Query param: Include the metadata for payments in the returned data.
+        # Query param: Whether to include metadata in each returned payment. Defaults to
+        # false.
         include_metadata: nil,
-        # Query param: Is the payment a refund of an original charge (only applicable to
-        # payouts).
+        # Query param: Filter payouts by whether they refund an original charge.
         is_refund: nil,
-        # Query param: Is the payment a resubmit of an original payment.
+        # Query param: Filter payments by whether they resubmit an original payment.
         is_resubmit: nil,
-        # Query param: Search using a maximum `amount` of a `charge` or `payout`.
+        # Query param: Filter to payments with an amount in cents less than or equal to
+        # this value.
         max_amount: nil,
-        # Query param: Search using the latest `created_at` date of a `charge` or
-        # `payout`.
+        # Query param: Filter to payments created at or before this timestamp.
         max_created_at: nil,
-        # Query param: Search using the latest `effective_date` of a `charge` or `payout`.
+        # Query param: Filter to payments effective at or before this timestamp.
         max_effective_at: nil,
-        # Query param: Search using the latest `payment_date` of a `charge` or `payout`.
+        # Query param: Filter to payments with a payment date on or before this date.
         max_payment_date: nil,
         # Query param: Filter to payments last updated on or before this timestamp.
         max_updated_at: nil,
-        # Query param: Search using the minimum `amount of a `charge`or`payout`.
+        # Query param: Filter to payments with an amount in cents greater than or equal to
+        # this value.
         min_amount: nil,
-        # Query param: Search using the earliest `created_at` date of a `charge` or
-        # `payout`.
+        # Query param: Filter to payments created at or after this timestamp.
         min_created_at: nil,
-        # Query param: Search using the earliest `effective_date` of a `charge` or
-        # `payout`.
+        # Query param: Filter to payments effective at or after this timestamp.
         min_effective_at: nil,
-        # Query param: Search using the earliest ` `of a `charge` or `payout`.
+        # Query param: Filter to payments with a payment date on or after this date.
         min_payment_date: nil,
         # Query param: Filter to payments last updated on or after this timestamp.
         min_updated_at: nil,
-        # Query param: Results page number. Starts at page 1.
+        # Query param: Page number to return.
         page_number: nil,
-        # Query param: Results page size. Max value: 1000
+        # Query param: Number of results to return per page.
         page_size: nil,
-        # Query param: Search using the `paykey` of a `charge` or `payout`.
+        # Query param: Filter by the paykey token.
         paykey: nil,
-        # Query param: Search using the `paykey_id` of a `charge` or `payout`.
+        # Query param: Filter by the unique identifier of the paykey.
         paykey_id: nil,
-        # Query param: Search using the `id` of a `charge` or `payout`.
+        # Query param: Filter by the payment's unique identifier.
         payment_id: nil,
-        # Query param: Search by the status of a `charge` or `payout`.
+        # Query param: Filter by payment status.
         payment_status: nil,
-        # Query param: Search by the type of a `charge` or `payout`.
+        # Query param: Filter by payment type.
         payment_type: nil,
-        # Query param: Search using a text string associated with a `charge` or `payout`.
+        # Query param: Free-text search across payment fields.
         search_text: nil,
-        # Query param: The field to sort the results by.
+        # Query param: Field used to sort the results.
         sort_by: nil,
-        # Query param
+        # Query param: Order in which to sort the results.
         sort_order: nil,
-        # Query param: Reason for latest payment status change.
+        # Query param: Filter by the reason for the most recent payment status change.
         status_reason: nil,
-        # Query param: Source of latest payment status change.
+        # Query param: Filter by the source of the most recent payment status change.
         status_source: 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 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: {}
       )