straddle 0.5.0 → 1.0.0

data/lib/straddle/resources/paykeys.rb

@@ -2,25 +2,53 @@
 
 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.
       # @return [Straddle::Resources::Paykeys::Review]
       attr_reader :review
 
+      # Returns a paykey by `id`, including the masked paykey value and bank account
+      # details.
+      #
+      # @overload retrieve(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the paykey.
+      #
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
+      #
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::PaykeyResponse]
+      #
+      # @see Straddle::Models::PaykeyRetrieveParams
+      def retrieve(id, params = {})
+        parsed, options = Straddle::PaykeyRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/paykeys/%1$s", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::PaykeyResponse,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::PaykeyListParams} for more details.
       #
-      # Returns a list of paykeys associated with a Straddle account. This endpoint
-      # supports advanced sorting and filtering options.
+      # Returns a paginated list of paykeys for the account. Optional query parameters
+      # filter, search, and sort the results.
       #
       # @overload list(created_from: nil, created_to: nil, customer_id: nil, page_number: nil, page_size: nil, search_text: nil, sort_by: nil, sort_order: nil, source: nil, status: nil, unblock_eligible: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
@@ -36,55 +64,54 @@ module Straddle
       #
       # @param search_text [String] Query param: General search term to filter paykeys.
       #
-      # @param sort_by [Symbol, Straddle::Models::PaykeyListParams::SortBy] Query param
+      # @param sort_by [Symbol, Straddle::Models::PaykeyListParams::SortBy] Query param: Field used to sort the results.
       #
-      # @param sort_order [Symbol, Straddle::Models::PaykeyListParams::SortOrder] Query param
+      # @param sort_order [Symbol, Straddle::Models::SortOrder] Query param: Order in which to sort the results.
       #
-      # @param source [Array<Symbol, Straddle::Models::PaykeyListParams::Source>] Query param: Filter paykeys by their source.
+      # @param source [Array<Symbol, Straddle::Models::PaykeySource>] Query param: Filter paykeys by their source.
       #
-      # @param status [Array<Symbol, Straddle::Models::PaykeyListParams::Status>] Query param: Filter paykeys by their current status.
+      # @param status [Array<Symbol, Straddle::Models::PaykeyStatus>] Query param: Filter paykeys by their current status.
       #
-      # @param unblock_eligible [Boolean] Query param: Filter paykeys by unblock eligibility. When true, returns only bloc
+      # @param unblock_eligible [Boolean] Query param: Filters paykeys by unblock eligibility. `true` returns blocked payk
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Internal::PageNumberSchema<Straddle::Models::PaykeySummaryPagedV1::Data>]
+      # @return [Straddle::Models::PaykeySummaryList]
       #
       # @see Straddle::Models::PaykeyListParams
       def list(params = {})
-        query_params =
-          [
-            :created_from,
-            :created_to,
-            :customer_id,
-            :page_number,
-            :page_size,
-            :search_text,
-            :sort_by,
-            :sort_order,
-            :source,
-            :status,
-            :unblock_eligible
-          ]
+        query_params = %i[
+          created_from
+          created_to
+          customer_id
+          page_number
+          page_size
+          search_text
+          sort_by
+          sort_order
+          source
+          status
+          unblock_eligible
+        ]
         parsed, options = Straddle::PaykeyListParams.dump_request(params)
         query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
         @client.request(
           method: :get,
           path: "v1/paykeys",
           query: query,
-          headers: parsed.except(*query_params).transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          page: Straddle::Internal::PageNumberSchema,
-          model: Straddle::PaykeySummaryPagedV1::Data,
+          headers:
+            parsed.except(*query_params).transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::PaykeySummaryList,
           options: options
         )
       end
@@ -92,179 +119,227 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::PaykeyCancelParams} for more details.
       #
+      # Cancels a paykey so it cannot be used for new payments.
+      #
       # @overload cancel(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the paykey.
       #
-      # @param reason [String, nil] Body param
+      # @param reason [String, nil] Body param: Reason for canceling the paykey.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::PaykeyV1]
+      # @return [Straddle::Models::PaykeyResponse]
       #
       # @see Straddle::Models::PaykeyCancelParams
       def cancel(id, params = {})
         parsed, options = Straddle::PaykeyCancelParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :put,
           path: ["v1/paykeys/%1$s/cancel", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::PaykeyV1,
+          model: Straddle::PaykeyResponse,
           options: 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.
       #
-      # @overload get(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload list_unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String]
+      # @param id [String] Unique identifier for the paykey.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::PaykeyV1]
+      # @return [Straddle::Models::UnmaskedPaykeyResponse]
       #
-      # @see Straddle::Models::PaykeyGetParams
-      def get(id, params = {})
-        parsed, options = Straddle::PaykeyGetParams.dump_request(params)
+      # @see Straddle::Models::PaykeyListUnmaskedParams
+      def list_unmasked(id, params = {})
+        parsed, options = Straddle::PaykeyListUnmaskedParams.dump_request(params)
         @client.request(
           method: :get,
-          path: ["v1/paykeys/%1$s", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::PaykeyV1,
+          path: ["v1/paykeys/%1$s/unmasked", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::UnmaskedPaykeyResponse,
           options: 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.
       #
-      # @overload reveal(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload refresh_balance(id, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the paykey.
       #
-      # @param id [String]
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param idempotency_key [String] Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::PaykeyRevealResponse]
+      # @return [Straddle::Models::PaykeyResponse]
       #
-      # @see Straddle::Models::PaykeyRevealParams
-      def reveal(id, params = {})
-        parsed, options = Straddle::PaykeyRevealParams.dump_request(params)
+      # @see Straddle::Models::PaykeyRefreshBalanceParams
+      def refresh_balance(id, params = {})
+        parsed, options = Straddle::PaykeyRefreshBalanceParams.dump_request(params)
         @client.request(
-          method: :get,
-          path: ["v1/paykeys/%1$s/reveal", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::Models::PaykeyRevealResponse,
+          method: :put,
+          path: ["v1/paykeys/%1$s/refresh_balance", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              idempotency_key: "idempotency-key",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::PaykeyResponse,
+          options: options
+        )
+      end
+
+      # Starts a new verification review for a paykey. The review runs asynchronously.
+      # Webhooks and the paykey review endpoint return updated results.
+      #
+      # @overload refresh_review(id, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the paykey.
+      #
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
+      #
+      # @param idempotency_key [String] Optional client-generated key for an idempotent request.
+      #
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::PaykeyResponse]
+      #
+      # @see Straddle::Models::PaykeyRefreshReviewParams
+      def refresh_review(id, params = {})
+        parsed, options = Straddle::PaykeyRefreshReviewParams.dump_request(params)
+        @client.request(
+          method: :put,
+          path: ["v1/paykeys/%1$s/refresh_review", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              idempotency_key: "idempotency-key",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::PaykeyResponse,
           options: 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.
       #
-      # @overload unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload reveal(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String]
+      # @param id [String] Unique identifier for the paykey.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::PaykeyUnmaskedV1]
+      # @return [Straddle::Models::RevealedPaykeyResponse]
       #
-      # @see Straddle::Models::PaykeyUnmaskedParams
-      def unmasked(id, params = {})
-        parsed, options = Straddle::PaykeyUnmaskedParams.dump_request(params)
+      # @see Straddle::Models::PaykeyRevealParams
+      def reveal(id, params = {})
+        parsed, options = Straddle::PaykeyRevealParams.dump_request(params)
         @client.request(
           method: :get,
-          path: ["v1/paykeys/%1$s/unmasked", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::PaykeyUnmaskedV1,
+          path: ["v1/paykeys/%1$s/reveal", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::RevealedPaykeyResponse,
           options: options
         )
       end
 
-      # Updates the balance of a paykey. This endpoint allows you to refresh the balance
-      # of a paykey.
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::PaykeyUnblockParams} for more details.
       #
-      # @overload update_balance(id, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # Unblocks a paykey that was blocked by an `R29` return. The paykey must not have
+      # been unblocked before.
       #
-      # @param id [String]
+      # @overload unblock(id, message: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param id [String] Path param: Unique identifier for the paykey.
       #
-      # @param idempotency_key [String] Optional client generated value to use for idempotent requests.
+      # @param message [String, nil] Body param: Optional message describing the reason for unblocking.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
-      # @return [Straddle::Models::PaykeyV1]
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @see Straddle::Models::PaykeyUpdateBalanceParams
-      def update_balance(id, params = {})
-        parsed, options = Straddle::PaykeyUpdateBalanceParams.dump_request(params)
+      # @return [Straddle::Models::PaykeyResponse]
+      #
+      # @see Straddle::Models::PaykeyUnblockParams
+      def unblock(id, params = {})
+        parsed, options = Straddle::PaykeyUnblockParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
-          method: :put,
-          path: ["v1/paykeys/%1$s/refresh_balance", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::PaykeyV1,
+          method: :patch,
+          path: ["v1/paykeys/%1$s/unblock", id],
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::PaykeyResponse,
           options: options
         )
       end