inttegro 1.0.0 → 3.0.0

data/lib/inttegro/resources/orders.rb

@@ -38,10 +38,10 @@ module Inttegro
       # @option payload [String] :statement_descriptor_prefix Static prefix, 2-10 characters, used to build prefix*order_id; mutually exclusive with statement_descriptor
       # @option payload [Boolean] :finalize Whether to explicitly finalize order (default: false)
       #
-      # @return [Inttegro::Models::OrderResponse] Response containing the created order
+      # @return [Inttegro::Order] Created order
       #
       # @example Create order with new customer and execute payment
-      #   result = client.orders.create(
+      #   order = client.orders.create(
       #     request_meta: {
       #       idempotency_key: 'order_2025_001'
       #     },
@@ -77,7 +77,7 @@ module Inttegro
       #     }
       #   )
       #
-      #   puts "Created order: #{result.order.id}"
+      #   puts "Created order: #{order.id}"
       #
       # @example Create order with existing customer
       #   result = client.orders.create(
@@ -100,11 +100,11 @@ module Inttegro
       # @see https://studio.inttegro.com/accept-a-payment for payment flow guide
       # @see https://studio.inttegro.com/order-lifecycle for order states
       def create(payload)
-        @http.post_model("/orders/create", Inttegro::Models::OrderResponse, payload)
+        @http.post_resource("/orders/create", Inttegro::Order, :order, payload)
       end
 
       def new(payload)
-        @http.post_model("/orders/new", Inttegro::Models::OrderResponse, payload)
+        @http.post_resource("/orders/new", Inttegro::Order, :order, payload)
       end
 
       # Retrieve an existing order by its ID.
@@ -115,23 +115,23 @@ module Inttegro
       # @param order_id [String] Unique identifier of the order to retrieve (required)
       # @param options [Hash] Additional options (currently unused)
       #
-      # @return [Inttegro::Models::OrderResponse] Response containing the complete order object
+      # @return [Inttegro::Order] Complete order object
       #
       # @example Lookup an order
-      #   result = client.orders.lookup(
+      #   order = client.orders.lookup(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
       #   )
       #
-      #   puts "Order status: #{result.order.status.serialize}"
+      #   puts "Order status: #{order.status.serialize}"
       #
       # @see https://studio.inttegro.com/orders for API reference
       def lookup(order_id:, **options)
         body = { order_id: order_id }.merge(options)
-        @http.post_model("/orders/lookup", Inttegro::Models::OrderResponse, body)
+        @http.post_resource("/orders/lookup", Inttegro::Order, :order, body)
       end
 
       def update(payload)
-        @http.post_model("/orders/update", Inttegro::Models::OrderResponse, payload)
+        @http.post_resource("/orders/update", Inttegro::Order, :order, payload)
       end
 
       # Initiate payment for an existing order.
@@ -141,7 +141,7 @@ module Inttegro
       # 2. New payment method: Include payment_method_data with inline payment details
       # 3. Offline payment: Set paid_out_of_band to true for cash, bank transfer, or check payments
       #
-      # When payment requires customer confirmation (e.g., OTP), the response includes a next_action field.
+      # When payment requires customer confirmation (e.g., OTP), the returned order includes a next_action field.
       #
       # @param payload [Hash] Payment parameters
       # @option payload [String] :order_id Unique identifier of the order to pay (required)
@@ -149,10 +149,10 @@ module Inttegro
       # @option payload [String] :payment_method_id ID of a saved payment method to use
       # @option payload [Boolean] :paid_out_of_band Set to true if payment received outside Inttegro (default: false)
       #
-      # @return [Inttegro::Models::OrderResponse] Response containing order and payment state
+      # @return [Inttegro::Order] Updated order and payment state
       #
       # @example Pay with inline mobile money
-      #   result = client.orders.pay(
+      #   order = client.orders.pay(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
       #     payment_method_data: {
       #       type: 'mobile_money',
@@ -163,8 +163,7 @@ module Inttegro
       #     }
       #   )
       #
-      #   order = result.order
-      #   if order.payment&.next_action&.type == Inttegro::Enums::PaymentNextActionType::CONFIRM_PAYMENT
+      #   if order.payment&.next_action&.type == Inttegro::PaymentNextActionType::CONFIRM_PAYMENT
       #     # Customer needs to provide OTP sent to their phone
       #     puts 'Please enter the OTP sent to your phone'
       #   end
@@ -184,7 +183,7 @@ module Inttegro
       # @see https://studio.inttegro.com/accept-a-payment for payment flow guide
       # @see https://studio.inttegro.com/charge-repeat-customers for saved payment methods
       def pay(payload)
-        @http.post_model("/orders/pay", Inttegro::Models::OrderResponse, payload)
+        @http.post_resource("/orders/pay", Inttegro::Order, :order, payload)
       end
 
       # Confirm a pending payment using a verification token (e.g., OTP sent to customer's phone).
@@ -196,22 +195,21 @@ module Inttegro
       # @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)
       #
-      # @return [Inttegro::Models::OrderResponse] Updated order with payment status
+      # @return [Inttegro::Order] Updated order with payment status
       #
       # @example Confirm payment with OTP
-      #   result = client.orders.confirm_payment(
+      #   order = client.orders.confirm_payment(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb',
       #     token: '123456'
       #   )
       #
-      #   order = result.order
-      #   if order.payment&.status == Inttegro::Enums::OrderPaymentStatus::PAID
+      #   if order.payment&.status == Inttegro::OrderPaymentStatus::PAID
       #     puts 'Payment confirmed successfully!'
       #   end
       #
       # @see https://studio.inttegro.com/accept-a-payment for complete payment flow
       def confirm_payment(payload)
-        @http.post_model("/orders/confirm_payment", Inttegro::Models::OrderResponse, payload)
+        @http.post_resource("/orders/confirm_payment", Inttegro::Order, :order, payload)
       end
 
       # Request a new confirmation token to be sent to the customer (e.g., resend OTP).
@@ -222,7 +220,7 @@ module Inttegro
       # @param order_id [String] Unique identifier of the order requiring confirmation (required)
       # @param request_meta [Hash, nil] Request controls such as idempotency_key (optional)
       #
-      # @return [Inttegro::Models::OrderResponse] Updated order
+      # @return [Inttegro::Order] Updated order
       #
       # @example Resend OTP to customer
       #   result = client.orders.request_confirmation(
@@ -233,9 +231,10 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/accept-a-payment for payment confirmation flow
       def request_confirmation(order_id:, request_meta: nil)
-        @http.post_model(
+        @http.post_resource(
           "/orders/request_confirmation",
-          Inttegro::Models::OrderResponse,
+          Inttegro::Order,
+          :order,
           {
             order_id: order_id,
             request_meta: request_meta || stable_order_request_meta("request_confirmation", order_id)
@@ -251,20 +250,21 @@ module Inttegro
       # @param order_id [String] Unique identifier of the order to finalize (required)
       # @param request_meta [Hash, nil] Request controls such as idempotency_key (optional)
       #
-      # @return [Inttegro::Models::FinalizeOrderResponse] Finalized order object
+      # @return [Inttegro::Order] Finalized order object
       #
       # @example Finalize an order
-      #   result = client.orders.finalize(
+      #   order = client.orders.finalize(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
       #   )
       #
-      #   puts "Order finalized at: #{result.order&.sealed_at}"
+      #   puts "Order finalized at: #{order.sealed_at}"
       #
       # @see https://studio.inttegro.com/order-lifecycle for order states
       def finalize(order_id:, request_meta: nil)
-        @http.post_model(
+        @http.post_resource(
           "/orders/finalize",
-          Inttegro::Models::FinalizeOrderResponse,
+          Inttegro::Order,
+          :order,
           {
             order_id: order_id,
             request_meta: request_meta || stable_order_request_meta("finalize", order_id)
@@ -276,11 +276,11 @@ module Inttegro
       #
       # @param order_id [String] Unique identifier of the order whose invoice should be sent (required)
       #
-      # @return [Inttegro::Models::OrderDocumentDeliveryResponse] Order and delivery details
+      # @return [Inttegro::OrderDocumentDeliveryResult] Order and delivery details
       def send_invoice(order_id:)
         @http.post_model(
           "/orders/send_invoice",
-          Inttegro::Models::OrderDocumentDeliveryResponse,
+          Inttegro::OrderDocumentDeliveryResult,
           { order_id: order_id }
         )
       end
@@ -289,11 +289,11 @@ module Inttegro
       #
       # @param order_id [String] Unique identifier of the paid order whose receipt should be sent (required)
       #
-      # @return [Inttegro::Models::OrderDocumentDeliveryResponse] Order and delivery details
+      # @return [Inttegro::OrderDocumentDeliveryResult] Order and delivery details
       def send_receipt(order_id:)
         @http.post_model(
           "/orders/send_receipt",
-          Inttegro::Models::OrderDocumentDeliveryResponse,
+          Inttegro::OrderDocumentDeliveryResult,
           { order_id: order_id }
         )
       end
@@ -308,14 +308,14 @@ module Inttegro
       # @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)
       #
-      # @return [Inttegro::Models::CompleteOrderResponse] Completed order object
+      # @return [Inttegro::Order] Completed order object
       #
       # @example Complete order after fulfillment
-      #   result = client.orders.complete(
+      #   order = client.orders.complete(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
       #   )
       #
-      #   puts "Order completed at: #{result.order&.completed_at}"
+      #   puts "Order completed at: #{order.completed_at}"
       #
       # @example Complete order with offline payment
       #   result = client.orders.complete(
@@ -325,7 +325,7 @@ module Inttegro
       #
       # @see https://studio.inttegro.com/order-lifecycle for order states
       def complete(payload)
-        @http.post_model("/orders/complete", Inttegro::Models::CompleteOrderResponse, payload)
+        @http.post_resource("/orders/complete", Inttegro::Order, :order, payload)
       end
 
       # Cancel an order, stopping payment execution and preventing further processing.
@@ -336,20 +336,21 @@ module Inttegro
       # @param order_id [String] Unique identifier of the order to cancel (required)
       # @param request_meta [Hash, nil] Request controls such as idempotency_key (optional)
       #
-      # @return [Inttegro::Models::OrderResponse] Cancelled order object
+      # @return [Inttegro::Order] Cancelled order object
       #
       # @example Cancel an order
-      #   result = client.orders.cancel(
+      #   order = client.orders.cancel(
       #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
       #   )
       #
-      #   puts "Order #{result.order.id} has been cancelled"
+      #   puts "Order #{order.id} has been cancelled"
       #
       # @see https://studio.inttegro.com/order-lifecycle for order states
       def cancel(order_id:, request_meta: nil)
-        @http.post_model(
+        @http.post_resource(
           "/orders/cancel",
-          Inttegro::Models::OrderResponse,
+          Inttegro::Order,
+          :order,
           {
             order_id: order_id,
             request_meta: request_meta || stable_order_request_meta("cancel", order_id)
@@ -357,59 +358,61 @@ module Inttegro
         )
       end
 
-      # Refund a paid order, returning funds to the customer.
+      # Create a refund through the /orders/refund compatibility alias.
       #
-      # Refunds the payment associated with an order, sending funds back to the customer's original payment
-      # method. The order must have been successfully paid before it can be refunded.
+      # 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 order_id [String] Unique identifier of the order to refund (required)
+      # @param payload [Hash] Create-refund payload containing order_id, reason, and line_items
       #
-      # @return [Inttegro::Models::RefundResponse] Created refund
+      # @return [Inttegro::Refund] Created refund
       #
       # @example Refund an order
-      #   result = client.orders.refund(
-      #     order_id: 'GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb'
+      #   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: #{result.refund&.id}"
+      #   puts "Refund created: #{refund.id}"
       #
-      # @see https://studio.inttegro.com/retry-a-payment for payment retry guide
+      # @see https://studio.inttegro.com/refunds
       def refund(payload)
-        @http.post_model("/orders/refund", Inttegro::Models::RefundResponse, 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). Use the has_more field
-      # and page parameter to navigate through results. Supports filtering by status and time range.
+      # Returns orders in reverse chronological order (most recent first).
       #
       # @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 order status (e.g., 'paid', 'requires_payment', 'completed')
-      # @option payload [String] :created_after Filter orders created after this timestamp (ISO 8601)
-      # @option payload [String] :created_before Filter orders created before this timestamp (ISO 8601)
+      # @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::Models::PageOrdersResponse] Paginated list of orders
+      # @return [Inttegro::OrderPage] Paginated list of orders
       #
       # @example Get first page of orders
-      #   result = client.orders.page(
-      #     per_page: 25,
-      #     page: 1
+      #   page = client.orders.page(
+      #     page_size: 25,
+      #     page_number: 0
       #   )
       #
-      #   puts "Retrieved #{result.page&.orders&.length || 0} orders"
+      #   puts "Retrieved #{page.orders&.length || 0} orders"
       #
-      # @example Filter by status
-      #   paid_orders = client.orders.page(
-      #     status: 'paid',
-      #     per_page: 50
+      # @example Restrict the page to one customer
+      #   customer_orders = client.orders.page(
+      #     customer_id: 'cu_123',
+      #     page_size: 50
       #   )
       #
       # @see https://studio.inttegro.com/pagination for pagination guide
       # @see https://studio.inttegro.com/orders for API reference
       def page(payload = {})
-        @http.post_model("/orders/page", Inttegro::Models::PageOrdersResponse, payload || {})
+        @http.post_resource("/orders/page", Inttegro::OrderPage, :page, payload || {})
       end
 
       private

data/lib/inttegro/resources/otp.rb

@@ -9,21 +9,21 @@ module Inttegro
       end
 
       def initiate(payload)
-        @http.post_model("/otp/initiate", Inttegro::Models::InitiateOTPResponse, payload)
+        @http.post_resource("/otp/initiate", Inttegro::OTPTransaction, :transaction, payload)
       end
 
       alias_method :initialize_session, :initiate
 
       def verify(payload)
-        @http.post_model("/otp/verify", Inttegro::Models::VerifyOTPResponse, payload)
+        @http.post_model("/otp/verify", Inttegro::OTPVerification, payload)
       end
 
       def lookup(payload)
-        @http.post_model("/otp/lookup", Inttegro::Models::LookupOTPResponse, payload)
+        @http.post_resource("/otp/lookup", Inttegro::OTPTransaction, :transaction, payload)
       end
 
       def cancel(payload)
-        @http.post_model("/otp/cancel", Inttegro::Models::CancelOtpResponse, payload)
+        @http.post_resource("/otp/cancel", Inttegro::OTPTransaction, :transaction, payload)
       end
     end
   end

data/lib/inttegro/resources/payment_methods.rb

@@ -29,7 +29,7 @@ module Inttegro
       # @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
+      # @return [Inttegro::PaymentMethod] Tokenized payment method
       #
       # @example Tokenize a mobile money payment method
       #   result = client.payment_methods.tokenize(
@@ -44,13 +44,13 @@ module Inttegro
       #     verify_immediately: true
       #   )
       #
-      #   puts "Tokenized payment method: #{result.payment_method&.id}"
+      #   puts "Tokenized payment method: #{result.id}"
       #
       # @see https://studio.inttegro.com/charge-repeat-customers for usage guide
       def tokenize(payload)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/tokenize",
-          Inttegro::Models::TokenizePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           payload
         )
       end
@@ -64,20 +64,20 @@ 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::Models::PaymentMethodVerificationResponse] Verification details
+      # @return [Inttegro::PaymentMethodVerification] Verification details
       #
       # @example Verify a payment method
       #   result = client.payment_methods.verify(
       #     payment_method_id: 'pm_xyz789'
       #   )
       #
-      #   puts "Verification request: #{result.verification&.request_id}"
+      #   puts "Verification request: #{result.request_id}"
       #
       # @see https://studio.inttegro.com/charge-repeat-customers for verification flow
       def verify(payment_method_id:, request_meta: nil)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/verify",
-          Inttegro::Models::PaymentMethodVerificationResponse,
+          Inttegro::PaymentMethodVerification, :verification,
           {
             payment_method_id: payment_method_id,
             request_meta: request_meta || stable_payment_method_request_meta("verify", payment_method_id)
@@ -94,7 +94,7 @@ module Inttegro
       # @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
+      # @return [Inttegro::PaymentMethod] Verified payment method
       #
       # @example Confirm verification with OTP
       #   result = client.payment_methods.confirm_verification(
@@ -102,15 +102,15 @@ module Inttegro
       #     token: '123456'
       #   )
       #
-      #   if result.payment_method&.verified_at
+      #   if result.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(
+        @http.post_resource(
           "/payment_methods/confirm_verification",
-          Inttegro::Models::LookupPaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           payload
         )
       end
@@ -122,52 +122,52 @@ module Inttegro
       #
       # @param payment_method_id [String] ID of the payment method to retrieve (required)
       #
-      # @return [Inttegro::Models::LookupPaymentMethodResponse] Payment method details
+      # @return [Inttegro::PaymentMethod] 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}"
+      #   puts "Payment method type: #{result.type&.serialize}"
       #
       # @see https://studio.inttegro.com/payment-methods for API reference
       def lookup(payment_method_id:)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/lookup",
-          Inttegro::Models::LookupPaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           { payment_method_id: payment_method_id }
         )
       end
 
       def page(payload = {})
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/page",
-          Inttegro::Models::PaymentMethodPageResponse,
+          Inttegro::PaymentMethodPage, :page,
           payload || {}
         )
       end
 
       def update(payload)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/update",
-          Inttegro::Models::UpdatePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           payload
         )
       end
 
       def activate(payment_method_id:)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/activate",
-          Inttegro::Models::ActivatePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           { payment_method_id: payment_method_id }
         )
       end
 
       def disactivate(payment_method_id:)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/disactivate",
-          Inttegro::Models::DisactivatePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           { payment_method_id: payment_method_id }
         )
       end
@@ -175,17 +175,17 @@ module Inttegro
       alias deactivate disactivate
 
       def archive(payment_method_id:)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/archive",
-          Inttegro::Models::ArchivePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           { payment_method_id: payment_method_id }
         )
       end
 
       def unarchive(payment_method_id:)
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/unarchive",
-          Inttegro::Models::UnarchivePaymentMethodResponse,
+          Inttegro::PaymentMethod, :payment_method,
           { payment_method_id: payment_method_id }
         )
       end
@@ -198,7 +198,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::Models::PaymentMethodDeleteResponse] Deletion confirmation
+      # @return [Inttegro::PaymentMethodDeletion] Deletion confirmation
       #
       # @example Delete a payment method
       #   result = client.payment_methods.delete(
@@ -209,9 +209,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::Models::PaymentMethodDeleteResponse,
+        @http.post_model("/payment_methods/delete", Inttegro::PaymentMethodDeletion,
           {
             payment_method_id: payment_method_id,
             request_meta: request_meta || stable_payment_method_request_meta("delete", payment_method_id)
@@ -224,18 +222,18 @@ module Inttegro
       # 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
+      # @return [Inttegro::PaymentMethodSettings] Payment method settings
       #
       # @example Get payment method settings
       #   result = client.payment_methods.settings
       #
-      #   puts "Mobile money enabled: #{result.settings&.mobile_money&.enabled}"
+      #   puts "Mobile money enabled: #{result.mobile_money&.enabled}"
       #
       # @see https://studio.inttegro.com/payment-methods for API reference
       def settings
-        @http.post_model(
+        @http.post_resource(
           "/payment_methods/settings",
-          Inttegro::Models::GetPaymentMethodSettingsResponse,
+          Inttegro::PaymentMethodSettings, :settings,
           {}
         )
       end