inttegro 4.3.1 → 6.0.0

data/lib/inttegro/resources/financial_accounts.rb

@@ -3,11 +3,19 @@
 
 module Inttegro
   module Resources
+    # Client for financial accounts used for supported collections and payouts.
+    #
+    # Access this resource through {Inttegro::Client#financial_accounts}.
     class FinancialAccounts
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a wallet, Ghana bank account, or Dosh account managed through Inttegro.
+      #
+      # @param payload [Hash, Inttegro::FinancialAccount::CreateRequest] account details
+      # @return [Inttegro::FinancialAccount] created account
       def create(payload)
         @http.post_resource(
           "/financial_accounts/create",
@@ -16,6 +24,10 @@ module Inttegro
         )
       end
 
+      # Retrieve a financial account by identifier.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @return [Inttegro::FinancialAccount] matching account
       def lookup(account_id:)
         @http.post_resource(
           "/financial_accounts/lookup",
@@ -24,6 +36,10 @@ module Inttegro
         )
       end
 
+      # Connect an existing financial account for supported collections or payouts.
+      #
+      # @param payload [Hash, Inttegro::FinancialAccount::CreateRequest] account details to connect
+      # @return [Inttegro::FinancialAccount] connected account
       def connect(payload)
         @http.post_resource(
           "/financial_accounts/connect",
@@ -32,14 +48,22 @@ module Inttegro
         )
       end
 
+      # Retrieve a page of financial accounts.
+      #
+      # @param payload [Hash, Inttegro::FinancialAccount::FinancialAccountPageRequest] pagination fields
+      # @return [Inttegro::FinancialAccount::Page] typed page of accounts
       def page(payload = {})
         @http.post_resource(
           "/financial_accounts/page",
-          Inttegro::FinancialAccountPage, :page,
+          Inttegro::FinancialAccount::Page, :page,
           payload || {}
         )
       end
 
+      # Update mutable account profile fields.
+      #
+      # @param payload [Hash, Inttegro::FinancialAccount::UpdateRequest] account identifier and fields to change
+      # @return [Inttegro::FinancialAccount] updated account
       def update(payload)
         @http.post_resource(
           "/financial_accounts/update",
@@ -48,6 +72,10 @@ module Inttegro
         )
       end
 
+      # Allow the account to receive supported payouts and transfers.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @return [Inttegro::FinancialAccount] updated account
       def enable_push(account_id:)
         @http.post_resource(
           "/financial_accounts/enable_push",
@@ -56,6 +84,11 @@ module Inttegro
         )
       end
 
+      # Stop the account from receiving supported payouts and transfers.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @param unset_as_payout_destination [Boolean, nil] whether to remove this account from payout destinations
+      # @return [Inttegro::FinancialAccount] updated account
       def disable_push(account_id:, unset_as_payout_destination: nil)
         payload = { account_id: account_id }
         payload[:unset_as_payout_destination] = unset_as_payout_destination unless unset_as_payout_destination.nil?
@@ -66,6 +99,10 @@ module Inttegro
         )
       end
 
+      # Allow supported charges to pull funds from the account.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @return [Inttegro::FinancialAccount] updated account
       def enable_pull(account_id:)
         @http.post_resource(
           "/financial_accounts/enable_pull",
@@ -74,6 +111,10 @@ module Inttegro
         )
       end
 
+      # Stop supported charges from pulling funds from the account.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @return [Inttegro::FinancialAccount] updated account
       def disable_pull(account_id:)
         @http.post_resource(
           "/financial_accounts/disable_pull",
@@ -82,6 +123,11 @@ module Inttegro
         )
       end
 
+      # Disconnect an account from new Inttegro activity.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @param unset_as_payout_destination [Boolean, nil] whether to remove this account from payout destinations
+      # @return [Inttegro::FinancialAccount] disconnected account
       def disconnect(account_id:, unset_as_payout_destination: nil)
         payload = { account_id: account_id }
         payload[:unset_as_payout_destination] = unset_as_payout_destination unless unset_as_payout_destination.nil?
@@ -92,6 +138,10 @@ module Inttegro
         )
       end
 
+      # Reconnect a previously disconnected financial account.
+      #
+      # @param account_id [String] unique financial account identifier
+      # @return [Inttegro::FinancialAccount] reconnected account
       def reconnect(account_id:)
         @http.post_resource(
           "/financial_accounts/reconnect",

data/lib/inttegro/resources/keys.rb

@@ -3,19 +3,40 @@
 
 module Inttegro
   module Resources
+    # Client for secret-key creation, public metadata, revocation, and authentication activity.
+    #
+    # Access this resource through {Inttegro::Client#keys}. Lookup and listing methods never return
+    # bearer token material; the token is available only in the result of {#generate}.
     class Keys
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Generate a new active secret key.
+      #
+      # @param payload [Hash, Inttegro::SecretKey::GenerateRequest] key label and request metadata
+      # @return [Inttegro::SecretKey::Generated] key metadata and one-time bearer token
       def generate(payload = {})
-        @http.post_resource("/keys/generate", Inttegro::GeneratedSecretKey, :key, payload || {})
+        @http.post_resource("/keys/generate", Inttegro::SecretKey::Generated, :key, payload || {})
       end
 
+      # Retrieve public metadata for the application's secret keys.
+      #
+      # @param payload [Hash, Inttegro::SecretKey::PageRequest] pagination fields
+      # @return [Inttegro::SecretKey::Page] typed page of keys
       def page(payload = {})
-        @http.post_resource("/keys/page", Inttegro::SecretKeyPage, :page, payload || {})
+        @http.post_resource("/keys/page", Inttegro::SecretKey::Page, :page, payload || {})
       end
 
+      # Retrieve one secret key's public metadata using a supported identifier name.
+      #
+      # The first non-+nil+ value in +secret_key_id+, +key_id+, and +id+ order is sent.
+      #
+      # @param secret_key_id [String, nil] preferred secret-key identifier
+      # @param key_id [String, nil] alternate key identifier
+      # @param id [String, nil] generic identifier accepted by older endpoint shapes
+      # @return [Inttegro::SecretKey] matching key metadata
       def lookup(secret_key_id: nil, key_id: nil, id: nil)
         @http.post_resource(
           "/keys/lookup",
@@ -24,10 +45,20 @@ module Inttegro
         )
       end
 
+      # Update mutable secret-key metadata.
+      #
+      # @param payload [Hash, Inttegro::SecretKey::UpdateRequest] key identifier and fields to change
+      # @return [Inttegro::SecretKey] updated key metadata
       def update(payload)
         @http.post_resource("/keys/update", Inttegro::SecretKey, :key, payload)
       end
 
+      # Revoke one secret key using a supported identifier name.
+      #
+      # @param secret_key_id [String, nil] preferred secret-key identifier
+      # @param key_id [String, nil] alternate key identifier
+      # @param id [String, nil] generic identifier accepted by older endpoint shapes
+      # @return [Inttegro::SecretKey] revoked key metadata
       def destroy(secret_key_id: nil, key_id: nil, id: nil)
         @http.post_resource(
           "/keys/destroy",
@@ -36,8 +67,15 @@ module Inttegro
         )
       end
 
+      # Retrieve recent authentication outcomes for one secret key.
+      #
+      # @param secret_key_id [String, nil] preferred secret-key identifier
+      # @param key_id [String, nil] alternate key identifier
+      # @param id [String, nil] generic identifier accepted by older endpoint shapes
+      # @param options [Hash] pagination or filter fields merged into the request
+      # @return [Inttegro::SecretKey::Usage] typed usage activity
       def usage(secret_key_id: nil, key_id: nil, id: nil, **options)
-        @http.post_model("/keys/usage", Inttegro::SecretKeyUsage,
+        @http.post_model("/keys/usage", Inttegro::SecretKey::Usage,
           identifier_payload(secret_key_id, key_id, id).merge(options)
         )
       end

data/lib/inttegro/resources/message_templates.rb

@@ -3,11 +3,20 @@
 
 module Inttegro
   module Resources
+    # Client for reusable, app-scoped SMS and email message templates.
+    #
+    # Access this resource through {Inttegro::Client#message_templates}.
     class MessageTemplates
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Create a reusable message template.
+      #
+      # @param payload [Hash, Inttegro::MessageTemplate::CreateRequest] channel, content, and variable fields
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::MessageTemplate] created template
       def create(payload, idempotency_key: nil)
         @http.post_resource(
           "/message_templates/create",
@@ -17,6 +26,11 @@ module Inttegro
         )
       end
 
+      # Update a template and create a new draft version.
+      #
+      # @param payload [Hash, Inttegro::MessageTemplate::UpdateRequest] template identifier and fields to change
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::MessageTemplate] updated template
       def update(payload, idempotency_key: nil)
         @http.post_resource(
           "/message_templates/update",
@@ -26,6 +40,11 @@ module Inttegro
         )
       end
 
+      # Publish the current draft version of a template.
+      #
+      # @param template_id [String] unique template identifier
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::MessageTemplate] published template
       def publish(template_id:, idempotency_key: nil)
         @http.post_resource(
           "/message_templates/publish",
@@ -35,6 +54,11 @@ module Inttegro
         )
       end
 
+      # Archive a template so it cannot be changed or used for new sends.
+      #
+      # @param template_id [String] unique template identifier
+      # @param idempotency_key [String, nil] explicit key for safely retrying this logical write
+      # @return [Inttegro::MessageTemplate] archived template
       def archive(template_id:, idempotency_key: nil)
         @http.post_resource(
           "/message_templates/archive",
@@ -44,6 +68,10 @@ module Inttegro
         )
       end
 
+      # Retrieve a message template by identifier.
+      #
+      # @param template_id [String] unique template identifier
+      # @return [Inttegro::MessageTemplate] matching template
       def lookup(template_id:)
         @http.post_resource(
           "/message_templates/lookup",
@@ -52,16 +80,24 @@ module Inttegro
         )
       end
 
+      # Retrieve templates in newest-updated order.
+      #
+      # @param payload [Hash, Inttegro::MessageTemplate::PageRequest] pagination and filter fields
+      # @return [Inttegro::MessageTemplate::Page] typed page of templates
       def page(payload = {})
         @http.post_resource(
           "/message_templates/page",
-          Inttegro::MessageTemplatesPage, :page,
+          Inttegro::MessageTemplate::Page, :page,
           payload || {}
         )
       end
 
+      # Render a draft-aware preview using the supplied variable values.
+      #
+      # @param payload [Hash, Inttegro::MessageTemplate::RenderPreviewRequest] template and preview variables
+      # @return [Inttegro::MessageTemplate::Preview] rendered preview and safety information
       def render_preview(payload)
-        @http.post_model("/message_templates/render_preview", Inttegro::MessageTemplatePreview,
+        @http.post_model("/message_templates/render_preview", Inttegro::MessageTemplate::Preview,
           payload
         )
       end

data/lib/inttegro/resources/orders.rb

@@ -11,6 +11,7 @@ module Inttegro
     #
     # @see https://studio.inttegro.com/orders for detailed guides
     class Orders
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
@@ -21,7 +22,7 @@ module Inttegro
       # existing customer, include multiple line items, and optionally execute payment
       # immediately. Orders must have at least one line item and billing details.
       #
-      # @param payload [Hash] Order creation parameters
+      # @param payload [Hash, Inttegro::Order::CreateNewCustomer, Inttegro::Order::CreateExistingCustomer] Order creation parameters
       # @option payload [Hash] :customer_data New customer information (required if customer_id not provided)
       # @option payload [String] :customer_id Existing customer ID (required if customer_data not provided)
       # @option payload [Array<Hash>] :line_items List of products/services being purchased (required)
@@ -103,10 +104,6 @@ module Inttegro
         @http.post_resource("/orders/create", Inttegro::Order, :order, payload)
       end
 
-      def new(payload)
-        @http.post_resource("/orders/new", Inttegro::Order, :order, payload)
-      end
-
       # Retrieve an existing order by its ID.
       #
       # Returns full order details including customer, line items, payment state, and invoice information.
@@ -130,6 +127,10 @@ module Inttegro
         @http.post_resource("/orders/lookup", Inttegro::Order, :order, body)
       end
 
+      # Update mutable fields on an order.
+      #
+      # @param payload [Hash, Inttegro::Order::UpdateRequest] order identifier and fields to change
+      # @return [Inttegro::Order] updated order
       def update(payload)
         @http.post_resource("/orders/update", Inttegro::Order, :order, payload)
       end
@@ -143,7 +144,7 @@ module Inttegro
       #
       # When payment requires customer confirmation (e.g., OTP), the returned order includes a next_action field.
       #
-      # @param payload [Hash] Payment parameters
+      # @param payload [Hash, Inttegro::Order::PayRequest] Payment parameters
       # @option payload [String] :order_id Unique identifier of the order to pay (required)
       # @option payload [Hash] :payment_method_data Inline payment method details (mobile money, card, etc.)
       # @option payload [String] :payment_method_id ID of a saved payment method to use
@@ -163,7 +164,7 @@ module Inttegro
       #     }
       #   )
       #
-      #   if order.payment&.next_action&.type == Inttegro::PaymentNextActionType::CONFIRM_PAYMENT
+      #   if order.payment&.next_action&.type == Inttegro::Payment::NextActionType::CONFIRM_PAYMENT
       #     # Customer needs to provide OTP sent to their phone
       #     puts 'Please enter the OTP sent to your phone'
       #   end
@@ -191,7 +192,7 @@ module Inttegro
       # Call this method when a payment requires customer confirmation and you've collected the verification
       # token from the customer. The token is typically a 6-digit OTP sent via SMS or email.
       #
-      # @param payload [Hash] Confirmation parameters
+      # @param payload [Hash, Inttegro::Payment::ConfirmRequest] Confirmation parameters
       # @option payload [String] :order_id Unique identifier of the order being paid (required)
       # @option payload [String] :token Verification token provided by customer (required, typically 6 digits)
       #
@@ -203,7 +204,7 @@ module Inttegro
       #     token: '123456'
       #   )
       #
-      #   if order.payment&.status == Inttegro::PaymentStatus::PAID
+      #   if order.payment&.status == Inttegro::Payment::Status::PAID
       #     puts 'Payment confirmed successfully!'
       #   end
       #
@@ -276,11 +277,11 @@ module Inttegro
       #
       # @param order_id [String] Unique identifier of the order whose invoice should be sent (required)
       #
-      # @return [Inttegro::OrderDocumentDeliveryResult] Order and delivery details
+      # @return [Inttegro::Order::DocumentDeliveryResult] Order and delivery details
       def send_invoice(order_id:)
         @http.post_model(
           "/orders/send_invoice",
-          Inttegro::OrderDocumentDeliveryResult,
+          Inttegro::Order::DocumentDeliveryResult,
           { order_id: order_id }
         )
       end
@@ -289,11 +290,11 @@ module Inttegro
       #
       # @param order_id [String] Unique identifier of the paid order whose receipt should be sent (required)
       #
-      # @return [Inttegro::OrderDocumentDeliveryResult] Order and delivery details
+      # @return [Inttegro::Order::DocumentDeliveryResult] Order and delivery details
       def send_receipt(order_id:)
         @http.post_model(
           "/orders/send_receipt",
-          Inttegro::OrderDocumentDeliveryResult,
+          Inttegro::Order::DocumentDeliveryResult,
           { order_id: order_id }
         )
       end
@@ -304,7 +305,7 @@ module Inttegro
       # Completing an order transitions it to its final state and can optionally mark payment as received
       # offline (out-of-band) if paid_out_of_band is set to true.
       #
-      # @param payload [Hash] Completion parameters
+      # @param payload [Hash, Inttegro::Order::CompleteRequest] Completion parameters
       # @option payload [String] :order_id Unique identifier of the order to complete (required)
       # @option payload [Boolean] :paid_out_of_band Set to true if payment received outside Inttegro (default: false)
       #
@@ -358,42 +359,16 @@ module Inttegro
         )
       end
 
-      # Create a refund through the /orders/refund compatibility alias.
-      #
-      # This accepts the same line-item payload as client.refunds.create and returns
-      # the created Refund directly. New integrations should use that canonical method.
-      #
-      # @param payload [Hash] Create-refund payload containing order_id, reason, and line_items
-      #
-      # @return [Inttegro::Refund] Created refund
-      #
-      # @example Refund an order
-      #   refund = client.orders.refund(
-      #     order_id: 'or_0123456789abcdefghijklmnopqrstuvwxyzABCD',
-      #     reason: 'requested_by_customer',
-      #     line_items: [{
-      #       order_line_item_id: 'oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN',
-      #       refund_amount: { currency: 'ghs', value: 2500 }
-      #     }]
-      #   )
-      #
-      #   puts "Refund created: #{refund.id}"
-      #
-      # @see https://studio.inttegro.com/refunds
-      def refund(payload)
-        @http.post_resource("/orders/refund", Inttegro::Refund, :refund, payload)
-      end
-
       # Retrieve a paginated list of orders.
       #
       # Returns orders in reverse chronological order (most recent first).
       #
-      # @param payload [Hash] Pagination and filter parameters (optional)
+      # @param payload [Hash, Inttegro::Order::PageRequest] Pagination and filter parameters (optional)
       # @option payload [Integer] :page_number Zero-based page index to retrieve (0-10)
       # @option payload [Integer] :page_size Number of orders per page (1-256)
       # @option payload [String] :customer_id Optional customer whose orders should be returned
       #
-      # @return [Inttegro::OrderPage] Paginated list of orders
+      # @return [Inttegro::Order::Page] Paginated list of orders
       #
       # @example Get first page of orders
       #   page = client.orders.page(
@@ -412,7 +387,7 @@ module Inttegro
       # @see https://studio.inttegro.com/pagination for pagination guide
       # @see https://studio.inttegro.com/orders for API reference
       def page(payload = {})
-        @http.post_resource("/orders/page", Inttegro::OrderPage, :page, payload || {})
+        @http.post_resource("/orders/page", Inttegro::Order::Page, :page, payload || {})
       end
 
       private

data/lib/inttegro/resources/otp.rb

@@ -3,27 +3,47 @@
 
 module Inttegro
   module Resources
+    # Client for one-time-password delivery, verification, lookup, and cancellation.
+    #
+    # Access this resource through {Inttegro::Client#otp}.
     class Otp
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
 
+      # Generate and deliver a one-time password.
+      #
+      # @param payload [Hash, Inttegro::OTP::InitiateRequest] recipient and OTP constraints
+      # @return [Inttegro::OTP::Transaction] created OTP transaction
       def initiate(payload)
-        @http.post_resource("/otp/initiate", Inttegro::OTPTransaction, :transaction, payload)
+        @http.post_resource("/otp/initiate", Inttegro::OTP::Transaction, :transaction, payload)
       end
 
       alias_method :initialize_session, :initiate
 
+      # Check a submitted token and record the verification attempt.
+      #
+      # @param payload [Hash, Inttegro::OTP::VerifyRequest] transaction identifier and submitted token
+      # @return [Inttegro::OTP::Verification] verification result
       def verify(payload)
-        @http.post_model("/otp/verify", Inttegro::OTPVerification, payload)
+        @http.post_model("/otp/verify", Inttegro::OTP::Verification, payload)
       end
 
+      # Retrieve delivery, verification, and expiry state for an OTP transaction.
+      #
+      # @param payload [Hash, Inttegro::OTP::LookupRequest] transaction identifier
+      # @return [Inttegro::OTP::Transaction] matching OTP transaction
       def lookup(payload)
-        @http.post_resource("/otp/lookup", Inttegro::OTPTransaction, :transaction, payload)
+        @http.post_resource("/otp/lookup", Inttegro::OTP::Transaction, :transaction, payload)
       end
 
+      # Cancel an OTP transaction.
+      #
+      # @param payload [Hash] transaction identifier and request fields accepted by the endpoint
+      # @return [Inttegro::OTP::Transaction] canceled OTP transaction
       def cancel(payload)
-        @http.post_resource("/otp/cancel", Inttegro::OTPTransaction, :transaction, payload)
+        @http.post_resource("/otp/cancel", Inttegro::OTP::Transaction, :transaction, payload)
       end
     end
   end

data/lib/inttegro/resources/payment_methods.rb

@@ -11,6 +11,7 @@ module Inttegro
     #
     # @see https://studio.inttegro.com/payment-methods for detailed guides
     class PaymentMethods
+      # @param http [Inttegro::HTTPClient] configured transport used for each request
       def initialize(http)
         @http = T.let(http, Inttegro::HTTPClient)
       end
@@ -24,7 +25,7 @@ module Inttegro
       # After tokenization, you can optionally verify the payment method to confirm customer ownership
       # and enable frictionless charging.
       #
-      # @param payload [Hash] Tokenization parameters
+      # @param payload [Hash, Inttegro::PaymentMethod::TokenizeMobileMoneyRequest] Tokenization parameters
       # @option payload [String] :customer_id Customer who will own this payment method (required)
       # @option payload [Hash] :payment_method_data Payment method details (required)
       # @option payload [Boolean] :verify_immediately Send verification OTP immediately (default: false)
@@ -64,7 +65,7 @@ module Inttegro
       # @param payment_method_id [String] ID of the payment method to verify (required)
       # @param request_meta [Hash, nil] Request controls such as idempotency_key (optional)
       #
-      # @return [Inttegro::PaymentMethodVerification] Verification details
+      # @return [Inttegro::PaymentMethod::Verification] Verification details
       #
       # @example Verify a payment method
       #   result = client.payment_methods.verify(
@@ -77,7 +78,7 @@ module Inttegro
       def verify(payment_method_id:, request_meta: nil)
         @http.post_resource(
           "/payment_methods/verify",
-          Inttegro::PaymentMethodVerification, :verification,
+          Inttegro::PaymentMethod::Verification, :verification,
           {
             payment_method_id: payment_method_id,
             request_meta: request_meta || stable_payment_method_request_meta("verify", payment_method_id)
@@ -140,14 +141,22 @@ module Inttegro
         )
       end
 
+      # Retrieve a page of payment methods.
+      #
+      # @param payload [Hash, Inttegro::PaymentMethod::PageRequest] pagination and filter fields
+      # @return [Inttegro::PaymentMethod::Page] typed page of payment methods
       def page(payload = {})
         @http.post_resource(
           "/payment_methods/page",
-          Inttegro::PaymentMethodPage, :page,
+          Inttegro::PaymentMethod::Page, :page,
           payload || {}
         )
       end
 
+      # Update mutable metadata on a payment method.
+      #
+      # @param payload [Hash, Inttegro::PaymentMethod::UpdateRequest] payment method identifier and fields to change
+      # @return [Inttegro::PaymentMethod] updated payment method
       def update(payload)
         @http.post_resource(
           "/payment_methods/update",
@@ -156,6 +165,10 @@ module Inttegro
         )
       end
 
+      # Mark an inactive payment method active.
+      #
+      # @param payment_method_id [String] unique payment method identifier
+      # @return [Inttegro::PaymentMethod] activated payment method
       def activate(payment_method_id:)
         @http.post_resource(
           "/payment_methods/activate",
@@ -164,6 +177,10 @@ module Inttegro
         )
       end
 
+      # Mark an active payment method inactive.
+      #
+      # @param payment_method_id [String] unique payment method identifier
+      # @return [Inttegro::PaymentMethod] deactivated payment method
       def disactivate(payment_method_id:)
         @http.post_resource(
           "/payment_methods/disactivate",
@@ -174,6 +191,10 @@ module Inttegro
 
       alias deactivate disactivate
 
+      # Archive a payment method.
+      #
+      # @param payment_method_id [String] unique payment method identifier
+      # @return [Inttegro::PaymentMethod] archived payment method
       def archive(payment_method_id:)
         @http.post_resource(
           "/payment_methods/archive",
@@ -182,6 +203,10 @@ module Inttegro
         )
       end
 
+      # Restore an archived payment method so it can be updated again.
+      #
+      # @param payment_method_id [String] unique payment method identifier
+      # @return [Inttegro::PaymentMethod] unarchived payment method
       def unarchive(payment_method_id:)
         @http.post_resource(
           "/payment_methods/unarchive",
@@ -198,7 +223,7 @@ module Inttegro
       # @param payment_method_id [String] ID of the payment method to delete (required)
       # @param request_meta [Hash, nil] Request controls such as idempotency_key (optional)
       #
-      # @return [Inttegro::PaymentMethodDeletion] Deletion confirmation
+      # @return [Inttegro::PaymentMethod::Deletion] Deletion confirmation
       #
       # @example Delete a payment method
       #   result = client.payment_methods.delete(
@@ -209,7 +234,7 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/payment-methods for API reference
       def delete(payment_method_id:, request_meta: nil)
-        @http.post_model("/payment_methods/delete", Inttegro::PaymentMethodDeletion,
+        @http.post_model("/payment_methods/delete", Inttegro::PaymentMethod::Deletion,
           {
             payment_method_id: payment_method_id,
             request_meta: request_meta || stable_payment_method_request_meta("delete", payment_method_id)
@@ -222,7 +247,7 @@ module Inttegro
       # Returns settings that control payment method behavior, including whether verification
       # is required before charging and supported payment method types.
       #
-      # @return [Inttegro::PaymentMethodSettings] Payment method settings
+      # @return [Inttegro::PaymentMethod::Settings] Payment method settings
       #
       # @example Get payment method settings
       #   result = client.payment_methods.settings
@@ -233,7 +258,7 @@ module Inttegro
       def settings
         @http.post_resource(
           "/payment_methods/settings",
-          Inttegro::PaymentMethodSettings, :settings,
+          Inttegro::PaymentMethod::Settings, :settings,
           {}
         )
       end