inttegro 1.0.0

data/lib/inttegro/resources/payment_methods.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    # Payment Methods resource for tokenizing and managing customer payment instruments.
+    #
+    # Payment methods are saved payment instruments (mobile money wallets, cards, bank accounts)
+    # that customers can reuse across purchases. Use this resource to tokenize new payment methods,
+    # verify ownership, and manage the payment method lifecycle.
+    #
+    # @see https://studio.inttegro.com/payment-methods for detailed guides
+    class PaymentMethods
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      # Save a new payment method for a customer without charging it.
+      #
+      # Tokenizes and stores payment details for future use. Currently supports mobile money wallets.
+      # Use this to collect payment details during customer onboarding, let customers save multiple
+      # payment instruments, or set up payment methods before subscription billing.
+      #
+      # After tokenization, you can optionally verify the payment method to confirm customer ownership
+      # and enable frictionless charging.
+      #
+      # @param payload [Hash] 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)
+      #
+      # @return [Inttegro::Models::TokenizePaymentMethodResponse] Tokenized payment method
+      #
+      # @example Tokenize a mobile money payment method
+      #   result = client.payment_methods.tokenize(
+      #     customer_id: 'cu_abc123',
+      #     payment_method_data: {
+      #       type: 'mobile_money',
+      #       mobile_money: {
+      #         network: 'mtn',
+      #         account_number: '0544998605'
+      #       }
+      #     },
+      #     verify_immediately: true
+      #   )
+      #
+      #   puts "Tokenized payment method: #{result.payment_method&.id}"
+      #
+      # @see https://studio.inttegro.com/charge-repeat-customers for usage guide
+      def tokenize(payload)
+        @http.post_model(
+          "/payment_methods/tokenize",
+          Inttegro::Models::TokenizePaymentMethodResponse,
+          payload
+        )
+      end
+
+      # Send an OTP to confirm customer ownership of a payment method.
+      #
+      # For mobile money, a 6-digit code is sent via SMS to the registered wallet number. The customer
+      # submits the token to complete verification. Verified payment methods can be charged without
+      # additional OTP confirmation, meet network provider requirements, and have better authorization rates.
+      #
+      # @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::Models::PaymentMethodVerificationResponse] Verification details
+      #
+      # @example Verify a payment method
+      #   result = client.payment_methods.verify(
+      #     payment_method_id: 'pm_xyz789'
+      #   )
+      #
+      #   puts "Verification request: #{result.verification&.request_id}"
+      #
+      # @see https://studio.inttegro.com/charge-repeat-customers for verification flow
+      def verify(payment_method_id:, request_meta: nil)
+        @http.post_model(
+          "/payment_methods/verify",
+          Inttegro::Models::PaymentMethodVerificationResponse,
+          {
+            payment_method_id: payment_method_id,
+            request_meta: request_meta || stable_payment_method_request_meta("verify", payment_method_id)
+          }
+        )
+      end
+
+      # Submit the OTP received by the customer to complete payment method verification.
+      #
+      # On success, the payment method's verified flag is set to true. Tokens expire after 8 minutes,
+      # and after 5 failed attempts, verification is locked—call verify() again to restart.
+      #
+      # @param payload [Hash] Confirmation parameters
+      # @option payload [String] :payment_method_id ID of the payment method being verified (required)
+      # @option payload [String] :token OTP code provided by customer (required, typically 6 digits)
+      #
+      # @return [Inttegro::Models::PaymentMethodResponse] Verified payment method
+      #
+      # @example Confirm verification with OTP
+      #   result = client.payment_methods.confirm_verification(
+      #     payment_method_id: 'pm_xyz789',
+      #     token: '123456'
+      #   )
+      #
+      #   if result.payment_method&.verified_at
+      #     puts 'Payment method verified successfully!'
+      #   end
+      #
+      # @see https://studio.inttegro.com/charge-repeat-customers for verification flow
+      def confirm_verification(payload)
+        @http.post_model(
+          "/payment_methods/confirm_verification",
+          Inttegro::Models::LookupPaymentMethodResponse,
+          payload
+        )
+      end
+
+      # Retrieve details of a saved payment method by its ID.
+      #
+      # Returns full payment method information including type, verification status, and associated customer.
+      # Use this to display saved payment methods to customers or verify payment method status.
+      #
+      # @param payment_method_id [String] ID of the payment method to retrieve (required)
+      #
+      # @return [Inttegro::Models::LookupPaymentMethodResponse] Payment method details
+      #
+      # @example Lookup a payment method
+      #   result = client.payment_methods.lookup(
+      #     payment_method_id: 'pm_xyz789'
+      #   )
+      #
+      #   puts "Payment method type: #{result.payment_method&.type&.serialize}"
+      #
+      # @see https://studio.inttegro.com/payment-methods for API reference
+      def lookup(payment_method_id:)
+        @http.post_model(
+          "/payment_methods/lookup",
+          Inttegro::Models::LookupPaymentMethodResponse,
+          { payment_method_id: payment_method_id }
+        )
+      end
+
+      def page(payload = {})
+        @http.post_model(
+          "/payment_methods/page",
+          Inttegro::Models::PaymentMethodPageResponse,
+          payload || {}
+        )
+      end
+
+      def update(payload)
+        @http.post_model(
+          "/payment_methods/update",
+          Inttegro::Models::UpdatePaymentMethodResponse,
+          payload
+        )
+      end
+
+      def activate(payment_method_id:)
+        @http.post_model(
+          "/payment_methods/activate",
+          Inttegro::Models::ActivatePaymentMethodResponse,
+          { payment_method_id: payment_method_id }
+        )
+      end
+
+      def disactivate(payment_method_id:)
+        @http.post_model(
+          "/payment_methods/disactivate",
+          Inttegro::Models::DisactivatePaymentMethodResponse,
+          { payment_method_id: payment_method_id }
+        )
+      end
+
+      alias deactivate disactivate
+
+      def archive(payment_method_id:)
+        @http.post_model(
+          "/payment_methods/archive",
+          Inttegro::Models::ArchivePaymentMethodResponse,
+          { payment_method_id: payment_method_id }
+        )
+      end
+
+      def unarchive(payment_method_id:)
+        @http.post_model(
+          "/payment_methods/unarchive",
+          Inttegro::Models::UnarchivePaymentMethodResponse,
+          { payment_method_id: payment_method_id }
+        )
+      end
+
+      # Delete a saved payment method, removing it from the customer's account.
+      #
+      # Permanently deletes the payment method. This action cannot be undone. Use when a customer
+      # requests removal of their payment details or when a payment method is no longer valid.
+      #
+      # @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::Models::PaymentMethodDeleteResponse] Deletion confirmation
+      #
+      # @example Delete a payment method
+      #   result = client.payment_methods.delete(
+      #     payment_method_id: 'pm_xyz789'
+      #   )
+      #
+      #   puts "Payment method deleted"
+      #
+      # @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::Models::PaymentMethodDeleteResponse,
+          {
+            payment_method_id: payment_method_id,
+            request_meta: request_meta || stable_payment_method_request_meta("delete", payment_method_id)
+          }
+        )
+      end
+
+      # Get configuration settings for payment methods in your application.
+      #
+      # Returns settings that control payment method behavior, including whether verification
+      # is required before charging and supported payment method types.
+      #
+      # @return [Inttegro::Models::GetPaymentMethodSettingsResponse] Payment method settings
+      #
+      # @example Get payment method settings
+      #   result = client.payment_methods.settings
+      #
+      #   puts "Mobile money enabled: #{result.settings&.mobile_money&.enabled}"
+      #
+      # @see https://studio.inttegro.com/payment-methods for API reference
+      def settings
+        @http.post_model(
+          "/payment_methods/settings",
+          Inttegro::Models::GetPaymentMethodSettingsResponse,
+          {}
+        )
+      end
+
+      private
+
+      def stable_payment_method_request_meta(action, payment_method_id)
+        { idempotency_key: "payment_methods_#{action}_#{payment_method_id}" }
+      end
+    end
+  end
+end

data/lib/inttegro/resources/payouts.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    # Payouts resource for configuring and managing automatic balance payouts.
+    #
+    # Payouts transfer available balance from Inttegro to your financial accounts. Use this resource
+    # to configure payout destinations, manage payout schedules, enable foreign exchange conversion,
+    # and retrieve payout history.
+    #
+    # @see https://studio.inttegro.com/payouts for detailed guides
+    class Payouts
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      # Configure which financial account should be used for payouts in each currency.
+      #
+      # Sets payout destinations by mapping currency codes to financial account IDs. Each financial
+      # account must be owned by your application, have push operations enabled, and its currency
+      # must match the currency key in the destinations map.
+      #
+      # @param destinations [Hash] Map of currency codes to financial account IDs (required)
+      #
+      # @return [Inttegro::Models::SetPayoutDestinationsResponse] Updated payout settings
+      #
+      # @example Set payout destinations for multiple currencies
+      #   result = client.payouts.set_destinations(
+      #     destinations: {
+      #       'ghs' => 'fa_1234567890abcdef',
+      #       'usd' => 'fa_0987654321fedcba'
+      #     }
+      #   )
+      #
+      #   puts "Destinations configured: #{result.settings&.destinations}"
+      #
+      # @see https://studio.inttegro.com/enable-automatic-payouts for configuration guide
+      def set_destinations(destinations:)
+        @http.post_model(
+          "/payouts/set_destinations",
+          Inttegro::Models::SetPayoutDestinationsResponse,
+          { destinations: destinations }
+        )
+      end
+
+      # Retrieve the current payout settings for your application.
+      #
+      # Returns payout settings including configured payout destinations, schedule information,
+      # and whether foreign exchange is enabled.
+      #
+      # @return [Inttegro::Models::GetPayoutSettingsResponse] Current payout settings
+      #
+      # @example Get payout settings
+      #   result = client.payouts.settings
+      #
+      #   puts "Payout schedule: #{result.settings&.schedule&.name}"
+      #
+      # @see https://studio.inttegro.com/product-payouts for payouts overview
+      def settings
+        @http.post_model("/payouts/settings", Inttegro::Models::GetPayoutSettingsResponse, {})
+      end
+
+      # Disable automatic payouts by switching to manual payout mode.
+      #
+      # Disables automatic payouts for your application. When automatic payouts are disabled, the system
+      # will not automatically schedule payouts—you must manually trigger them. Balance transactions must
+      # still be at least 7 days old before they can be paid out, but the payout will only occur when you
+      # explicitly request it.
+      #
+      # @return [Inttegro::Models::DisableAutomaticPayoutsResponse] Updated payout settings
+      #
+      # @example Disable automatic payouts
+      #   result = client.payouts.disable_automatic
+      #
+      #   puts "Schedule type: #{result.settings&.schedule&.type}"
+      #
+      # @see https://studio.inttegro.com/disable-automatic-payouts for manual payout guide
+      def disable_automatic
+        @http.post_model(
+          "/payouts/disable",
+          Inttegro::Models::DisableAutomaticPayoutsResponse,
+          {}
+        )
+      end
+
+      def enable_automatic
+        @http.post_model(
+          "/payouts/enable",
+          Inttegro::Models::EnableAutomaticPayoutsResponse,
+          {}
+        )
+      end
+
+      alias enable enable_automatic
+
+      # Enable foreign exchange conversion for payouts.
+      #
+      # Enables FX conversion for payouts. When FX is enabled, Inttegro can automatically convert payout
+      # funds from one currency to another when routing to destination accounts. This allows you to
+      # consolidate multiple currencies into a single operating account or hold funds in a preferred currency.
+      #
+      # With FX disabled (default), payouts only transfer funds to accounts matching the transaction currency.
+      # With FX enabled, GHS balance can be converted and paid out to USD accounts, for example.
+      #
+      # Important: FX conversion incurs additional fees beyond standard payout fees, and exchange rates are
+      # determined at payout execution time. FX-enabled payouts require approval and special configuration.
+      #
+      # @return [Inttegro::Models::PayoutSettingsResponse] Updated payout settings
+      #
+      # @example Enable foreign exchange for payouts
+      #   result = client.payouts.enable_fx
+      #
+      #   puts "FX enabled: #{result.settings&.fx_enabled}"
+      #
+      # @see https://studio.inttegro.com/enable-fx-payouts for FX payout guide
+      def enable_fx
+        @http.post_model("/payouts/enable_fx", Inttegro::Models::PayoutSettingsResponse, {})
+      end
+
+      # Disable foreign exchange conversion for payouts.
+      #
+      # Disables FX conversion, restricting payouts to accounts that match the transaction currency.
+      # After disabling FX, GHS balance can only be paid out to GHS accounts, USD balance only to USD accounts, etc.
+      #
+      # @return [Inttegro::Models::PayoutSettingsResponse] Updated payout settings
+      #
+      # @example Disable foreign exchange for payouts
+      #   result = client.payouts.disable_fx
+      #
+      #   puts "FX enabled: #{result.settings&.fx_enabled}"
+      #
+      # @see https://studio.inttegro.com/disable-fx-payouts for FX payout guide
+      def disable_fx
+        @http.post_model("/payouts/disable_fx", Inttegro::Models::PayoutSettingsResponse, {})
+      end
+
+      # Retrieve a paginated list of payouts.
+      #
+      # Returns payouts in reverse chronological order (most recent first). Use the has_more field
+      # and page parameter to navigate through results. Supports filtering by status and time range.
+      #
+      # @param payload [Hash] Pagination and filter parameters (optional)
+      # @option payload [Integer] :page Page number to retrieve (minimum 1, default: 1)
+      # @option payload [Integer] :per_page Number of results per page (minimum 1, maximum 100, default: 10)
+      # @option payload [String] :status Filter by payout status (e.g., 'pending', 'paid', 'failed')
+      # @option payload [String] :created_after Filter payouts created after this timestamp (ISO 8601)
+      # @option payload [String] :created_before Filter payouts created before this timestamp (ISO 8601)
+      #
+      # @return [Inttegro::Models::PagePayoutsResponse] Paginated list of payouts
+      #
+      # @example Get first page of payouts
+      #   result = client.payouts.page(
+      #     per_page: 25,
+      #     page: 1
+      #   )
+      #
+      #   puts "Retrieved #{result.page&.payouts&.length || 0} payouts"
+      #
+      # @example Filter by status
+      #   paid_payouts = client.payouts.page(
+      #     status: 'paid',
+      #     per_page: 50
+      #   )
+      #
+      # @see https://studio.inttegro.com/pagination for pagination guide
+      # @see https://studio.inttegro.com/product-payouts for payouts overview
+      def page(payload = {})
+        @http.post_model("/payouts/page", Inttegro::Models::PagePayoutsResponse, payload || {})
+      end
+
+      def schedule(payload)
+        @http.post_model("/payouts/schedule", Inttegro::Models::SchedulePayoutResponse, payload)
+      end
+
+      def lookup(payout_id:)
+        @http.post_model(
+          "/payouts/lookup",
+          Inttegro::Models::LookupPayoutResponse,
+          { payout_id: payout_id }
+        )
+      end
+
+      # Cancel a scheduled payout before execution.
+      #
+      # Only payouts in scheduled status with a future execution time can be canceled.
+      #
+      # @param payout_id [String] Scheduled payout ID
+      #
+      # @return [Inttegro::Models::CancelPayoutResponse] Canceled payout
+      def cancel(payout_id:)
+        @http.post_model(
+          "/payouts/cancel",
+          Inttegro::Models::CancelPayoutResponse,
+          { payout_id: payout_id }
+        )
+      end
+    end
+  end
+end

data/lib/inttegro/resources/prices.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class Prices
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def create(payload)
+        @http.post_model("/prices/create", Inttegro::Models::PriceResponse, payload)
+      end
+
+      def lookup(price_id:)
+        @http.post_model("/prices/lookup", Inttegro::Models::PriceResponse, { price_id: price_id })
+      end
+
+      def page(payload = {})
+        @http.post_model("/prices/page", Inttegro::Models::PricePageResponse, payload || {})
+      end
+
+      def update(payload)
+        @http.post_model("/prices/update", Inttegro::Models::PriceResponse, payload)
+      end
+
+      def activate(price_id:)
+        @http.post_model("/prices/activate", Inttegro::Models::PriceResponse, { price_id: price_id })
+      end
+
+      def deactivate(price_id:)
+        @http.post_model("/prices/deactivate", Inttegro::Models::PriceResponse, { price_id: price_id })
+      end
+
+      def archive(price_id:)
+        @http.post_model("/prices/archive", Inttegro::Models::PriceResponse, { price_id: price_id })
+      end
+    end
+  end
+end

data/lib/inttegro/resources/products.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class Products
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def create(payload)
+        @http.post_model("/products/create", Inttegro::Models::ProductResponse, payload)
+      end
+
+      def add_price(payload)
+        @http.post_model("/products/add_price", Inttegro::Models::AddProductPriceResponse, payload)
+      end
+
+      def set_default_unit_price(payload)
+        @http.post_model("/products/set_default_unit_price", Inttegro::Models::ProductResponse, payload)
+      end
+
+      def lookup(product_id:)
+        @http.post_model("/products/lookup", Inttegro::Models::ProductResponse, { product_id: product_id })
+      end
+
+      def update(payload)
+        @http.post_model("/products/update", Inttegro::Models::UpdateProductResponse, payload)
+      end
+
+      def publish(product_id:)
+        @http.post_model("/products/publish", Inttegro::Models::ProductResponse, { product_id: product_id })
+      end
+
+      def unpublish(product_id:)
+        @http.post_model("/products/unpublish", Inttegro::Models::ProductResponse, { product_id: product_id })
+      end
+
+      def archive(product_id:)
+        @http.post_model("/products/archive", Inttegro::Models::ProductResponse, { product_id: product_id })
+      end
+
+      def page(payload = {})
+        @http.post_model("/products/page", Inttegro::Models::PageProductsResponse, payload || {})
+      end
+    end
+  end
+end

data/lib/inttegro/resources/purchase_intents.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class PurchaseIntents
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def create(payload)
+        @http.post_model("/purchase_intents/create", Inttegro::Models::PurchaseIntentResponse, payload)
+      end
+
+      def update(payload)
+        @http.post_model("/purchase_intents/update", Inttegro::Models::PurchaseIntentResponse, payload)
+      end
+
+      def cancel(id:)
+        @http.post_model(
+          "/purchase_intents/cancel",
+          Inttegro::Models::PurchaseIntentResponse,
+          { id: id }
+        )
+      end
+
+      def lookup(id:)
+        @http.post_model(
+          "/purchase_intents/lookup",
+          Inttegro::Models::PurchaseIntentResponse,
+          { id: id }
+        )
+      end
+
+      def page(payload = {})
+        @http.post_model(
+          "/purchase_intents/page",
+          Inttegro::Models::PagePurchaseIntentsResponse,
+          payload || {}
+        )
+      end
+    end
+  end
+end

data/lib/inttegro/resources/refunds.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class Refunds
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def create(payload)
+        @http.post_model("/refunds/create", Inttegro::Models::RefundResponse, payload)
+      end
+
+      def cancel(refund_id:)
+        @http.post_model(
+          "/refunds/cancel",
+          Inttegro::Models::RefundResponse,
+          { refund_id: refund_id }
+        )
+      end
+
+      def lookup(refund_id:)
+        @http.post_model(
+          "/refunds/lookup",
+          Inttegro::Models::RefundResponse,
+          { refund_id: refund_id }
+        )
+      end
+
+      def page(payload)
+        @http.post_model("/refunds/page", Inttegro::Models::RefundPageResponse, payload)
+      end
+    end
+  end
+end

data/lib/inttegro/resources/schedules.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class Schedules
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def lookup(schedule_id:)
+        @http.post_model(
+          "/schedules/lookup",
+          Inttegro::Models::ScheduleLookupResponse,
+          { schedule_id: schedule_id }
+        )
+      end
+
+      def cancel(schedule_id:)
+        @http.post_model(
+          "/schedules/cancel",
+          Inttegro::Models::ScheduleCancelResponse,
+          { schedule_id: schedule_id }
+        )
+      end
+    end
+  end
+end

data/lib/inttegro/resources/spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Inttegro
+  module Resources
+    class Spec
+      def initialize(http)
+        @http = T.let(http, Inttegro::HTTPClient)
+      end
+
+      def countries
+        @http.post_model("/spec/countries", Inttegro::Models::ListCountrySpecsResponse, {})
+      end
+    end
+  end
+end