paystack-gateway 0.1.0 → 0.2.0

data/lib/paystack_gateway/dispute.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/dispute
+  #
+  # Disputes
+  # A collection of endpoints for managing transactions complaint made by customers
+  module Dispute
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #list.
+    class ListResponse < PaystackGateway::Response; end
+
+    # Error response from #list.
+    class ListError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#list
+    # List Disputes: GET /dispute
+    # List transaction disputes filed by customers
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The section to retrieve
+    # @param status ["awaiting-merchant-feedback", "awaiting-bank-feedback", "pending", "resolved"]
+    #        Dispute status
+    # @param transaction [String]
+    #        Transaction ID
+    # @param from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(
+      per_page: nil,
+      page: nil,
+      status: nil,
+      transaction: nil,
+      from: nil,
+      to: nil
+    )
+      use_connection do |connection|
+        connection.get(
+          '/dispute',
+          {
+            perPage: per_page,
+            page:,
+            status:,
+            transaction:,
+            from:,
+            to:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :id,
+               :refund_amount,
+               :currency,
+               :resolution,
+               :domain,
+               :transaction,
+               :transaction_reference,
+               :category,
+               :customer,
+               :bin,
+               :last4,
+               :dueAt,
+               :resolvedAt,
+               :evidence,
+               :attachments,
+               :note,
+               :history,
+               :messages,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#fetch
+    # Fetch Dispute: GET /dispute/{id}
+    # Fetch a transaction dispute
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the dispute
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(id:)
+      use_connection do |connection|
+        connection.get(
+          "/dispute/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response
+      delegate :id,
+               :refund_amount,
+               :currency,
+               :resolution,
+               :domain,
+               :transaction,
+               :transaction_reference,
+               :category,
+               :customer,
+               :bin,
+               :last4,
+               :dueAt,
+               :resolvedAt,
+               :evidence,
+               :attachments,
+               :note,
+               :history,
+               :messages,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#update
+    # Update Dispute: PUT /dispute/{id}
+    # Update a transaction dispute
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the dispute
+    # @param refund_amount [Integer] (required)
+    #        The amount to refund, in the subunit of your currency
+    # @param uploaded_filename [String]
+    #        Filename of attachment returned via response from the Dispute upload URL
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(id:, refund_amount:, uploaded_filename: nil)
+      use_connection do |connection|
+        connection.put(
+          "/dispute/#{id}",
+          { refund_amount:, uploaded_filename: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #upload_url.
+    class UploadUrlResponse < PaystackGateway::Response
+      delegate :signedUrl, :fileName, to: :data
+    end
+
+    # Error response from #upload_url.
+    class UploadUrlError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#upload_url
+    # Fetch Upload URL: GET /dispute/{id}/upload_url
+    # Get the URL to upload a dispute evidence
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the dispute
+    #
+    # @return [UploadUrlResponse] successful response
+    # @raise [UploadUrlError] if the request fails
+    api_method def self.upload_url(id:)
+      use_connection do |connection|
+        connection.get(
+          "/dispute/#{id}/upload_url",
+        )
+      end
+    end
+
+    # Successful response from calling #download.
+    class DownloadResponse < PaystackGateway::Response
+      delegate :path, :expiresAt, to: :data
+    end
+
+    # Error response from #download.
+    class DownloadError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#download
+    # Export Disputes: GET /dispute/export
+    # Export the disputes available on your integration
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The section to retrieve
+    # @param status ["awaiting-merchant-feedback", "awaiting-bank-feedback", "pending", "resolved"]
+    # @param from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [DownloadResponse] successful response
+    # @raise [DownloadError] if the request fails
+    api_method def self.download(per_page: nil, page: nil, status: nil, from: nil, to: nil)
+      use_connection do |connection|
+        connection.get(
+          '/dispute/export',
+          { perPage: per_page, page:, status:, from:, to: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #transaction.
+    class TransactionResponse < PaystackGateway::Response
+      delegate :history,
+               :messages,
+               :currency,
+               :last4,
+               :bin,
+               :transaction_reference,
+               :merchant_transaction_reference,
+               :refund_amount,
+               :domain,
+               :resolution,
+               :category,
+               :note,
+               :attachments,
+               :id,
+               :integration,
+               :transaction,
+               :created_by,
+               :evidence,
+               :resolvedAt,
+               :createdAt,
+               :updatedAt,
+               :dueAt, to: :data
+    end
+
+    # Error response from #transaction.
+    class TransactionError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#transaction
+    # List Transaction Disputes: GET /dispute/transaction/{id}
+    # List all disputes filed for a transaction
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the transaction
+    #
+    # @return [TransactionResponse] successful response
+    # @raise [TransactionError] if the request fails
+    api_method def self.transaction(id:)
+      use_connection do |connection|
+        connection.get(
+          "/dispute/transaction/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #resolve.
+    class ResolveResponse < PaystackGateway::Response
+      delegate :currency,
+               :last4,
+               :bin,
+               :transaction_reference,
+               :merchant_transaction_reference,
+               :refund_amount,
+               :domain,
+               :resolution,
+               :category,
+               :note,
+               :attachments,
+               :id,
+               :integration,
+               :transaction,
+               :created_by,
+               :evidence,
+               :resolvedAt,
+               :createdAt,
+               :updatedAt,
+               :dueAt, to: :data
+    end
+
+    # Error response from #resolve.
+    class ResolveError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#resolve
+    # Resolve Dispute: PUT /dispute/{id}/resolve
+    # Resolve a transaction dispute
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the dispute
+    # @param resolution [String] (required)
+    #        Dispute resolution. Accepted values, merchant-accepted, declined
+    # @param message [String] (required)
+    #        Reason for resolving
+    # @param refund_amount [Integer] (required)
+    #        The amount to refund, in the subunit of your integration currency
+    # @param uploaded_filename [String] (required)
+    #        Filename of attachment returned via response from the Dispute upload URL
+    # @param evidence [Integer]
+    #        Evidence Id for fraud claims
+    #
+    # @return [ResolveResponse] successful response
+    # @raise [ResolveError] if the request fails
+    api_method def self.resolve(
+      id:,
+      resolution:,
+      message:,
+      refund_amount:,
+      uploaded_filename:,
+      evidence: nil
+    )
+      use_connection do |connection|
+        connection.put(
+          "/dispute/#{id}/resolve",
+          { resolution:, message:, refund_amount:, uploaded_filename:, evidence: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #evidence.
+    class EvidenceResponse < PaystackGateway::Response
+      delegate :customer_email,
+               :customer_name,
+               :customer_phone,
+               :service_details,
+               :delivery_address,
+               :delivery_date,
+               :dispute,
+               :id,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #evidence.
+    class EvidenceError < ApiError; end
+
+    # https://paystack.com/docs/api/dispute/#evidence
+    # Add Evidence: POST /dispute/{id}/evidence
+    # Provide evidence for a dispute
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the dispute
+    # @param customer_email [String] (required)
+    #        Customer email
+    # @param customer_name [String] (required)
+    #        Customer name
+    # @param customer_phone [String] (required)
+    #        Customer mobile number
+    # @param service_details [String] (required)
+    #        Details of service offered
+    # @param delivery_address [String]
+    #        Delivery address
+    # @param delivery_date [Time]
+    #        ISO 8601 representation of delivery date (YYYY-MM-DD)
+    #
+    # @return [EvidenceResponse] successful response
+    # @raise [EvidenceError] if the request fails
+    api_method def self.evidence(
+      id:,
+      customer_email:,
+      customer_name:,
+      customer_phone:,
+      service_details:,
+      delivery_address: nil,
+      delivery_date: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          "/dispute/#{id}/evidence",
+          {
+            customer_email:,
+            customer_name:,
+            customer_phone:,
+            service_details:,
+            delivery_address:,
+            delivery_date:,
+          }.compact,
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/extensions/customer_extensions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+return if !PaystackGateway.use_extensions
+
+module PaystackGateway
+  module Customer
+    # Helpers for PaystackGateway::Customer::FetchResponse
+    class FetchResponse
+      def active_subscriptions = subscriptions.select { _1.status == 'active' }
+      def active_subscription_codes = active_subscriptions.map(&:subscription_code)
+      def reusable_authorizations = authorizations.select(&:reusable)
+    end
+  end
+end

data/lib/paystack_gateway/extensions/plan_extensions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+return if !PaystackGateway.use_extensions
+
+module PaystackGateway
+  module Plan
+    # Helpers for PaystackGateway::Plan::CreateResponse
+    class CreateResponse
+      def plan_id = data.id
+    end
+
+    # Helpers for PaystackGateway::Plan::ListResponse
+    class ListResponse
+      def active_plans = data.select { |plan| !plan.is_deleted && !plan.is_archived }
+
+      def find_active_plan_by_name(name)
+        active_plans.sort_by { -Time.parse(_1.createdAt).to_i }.find { _1.name == name }
+      end
+    end
+
+    # Helpers for PaystackGateway::Plan::FetchResponse
+    class FetchResponse
+      def active_subscriptions = subscriptions.select { _1.status.to_sym == :active }
+
+      def active_subscription_codes(email: nil)
+        subscriptions =
+          if email
+            active_subscriptions.select { _1.customer.email.casecmp?(email) }
+          else
+            active_subscriptions
+          end
+        subscriptions.map(&:subscription_code)
+      end
+    end
+  end
+end

data/lib/paystack_gateway/extensions/refund_extensions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+return if !PaystackGateway.use_extensions
+
+require_relative 'transaction_response_extension'
+
+module PaystackGateway
+  module Refund
+    # Helpers for PaystackGateway::Refund::ListResponse
+    class ListResponse
+      def pending_or_successful
+        filtered = data.select { _1.status&.to_sym.in?(%i[processed pending processing]) }
+
+        ListResponse.new({ **self, data: filtered })
+      end
+
+      def with_amount(amount)
+        filtered = data.select { _1.amount == amount * 100 }
+
+        ListResponse.new({ **self, data: filtered })
+      end
+    end
+
+    # Helpers for responses from refunds endpoints
+    module TransactionRefundResponse
+      include PaystackGateway::Extensions::TransactionResponseExtension
+
+      def refund_success? = transaction_status == :processed
+      def refund_failed? = transaction_status == :failed
+      def refund_pending? = transaction_status.in?(%i[pending processing])
+    end
+
+    # Helpers for PaystackGateway::Refund::CreateResponse
+    class CreateResponse
+      include TransactionRefundResponse
+    end
+
+    # Helpers for PaystackGateway::Refund::FetchResponse
+    class FetchResponse
+      include TransactionRefundResponse
+    end
+  end
+end

data/lib/paystack_gateway/extensions/transaction_extensions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+return if !PaystackGateway.use_extensions
+
+require_relative 'transaction_response_extension'
+
+module PaystackGateway
+  module Transaction
+    # Helpers for PaystackGateway::Transaction::InitializeTransactionResponse
+    class InitializeTransactionResponse
+      def payment_url
+        authorization_url
+      end
+    end
+
+    # Helpers for PaystackGateway::Transaction::InitializeTransactionError
+    class InitializeTransactionError
+      def cancellable? = network_error?
+    end
+
+    # Helpers for PaystackGateway::Transaction::VerifyResponse
+    class VerifyResponse
+      include PaystackGateway::Extensions::TransactionResponseExtension
+
+      def transaction_completed_at = paid_at || super
+    end
+
+    # Helpers for PaystackGateway::Transaction::VerifyError
+    class VerifyError
+      def transaction_not_found?
+        parsed_response_body[:status] == false &&
+          parsed_response_body[:message]&.match?(/transaction reference not found/i)
+      end
+    end
+
+    class ChargeAuthorizationResponse
+      include PaystackGateway::Extensions::TransactionResponseExtension
+    end
+  end
+end

data/lib/paystack_gateway/extensions/transaction_response_extension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module PaystackGateway
+  module Extensions
+    # Helpers for various responses around transactions.
+    module TransactionResponseExtension
+      def transaction_success? = %i[success reversed reversal_pending].include?(transaction_status)
+      def transaction_abandoned? = transaction_status == :abandoned
+      def transaction_failed? = transaction_status == :failed
+      def transaction_pending? = %i[pending ongoing].include?(transaction_status)
+
+      def transaction_status = data.status.to_sym
+      def transaction_amount_in_major_units = amount / BigDecimal(100)
+      def transaction_completed_at = data[:updatedAt]
+
+      def subaccount_amount_in_major_units
+        return if !subaccount || !fees_split
+
+        fees_split.subaccount / BigDecimal(100)
+      end
+
+      def failure_reason
+        return if !transaction_failed? && !transaction_abandoned?
+
+        data.gateway_response || transaction_status || message
+      end
+    end
+  end
+end

data/lib/paystack_gateway/extensions/transfer_extensions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+return if !PaystackGateway.use_extensions
+
+require_relative 'transaction_response_extension'
+
+module PaystackGateway
+  module Transfer
+    # Helpers for PaystackGateway::Transfer::InitiateResponse
+    class InitiateResponse
+      include PaystackGateway::Extensions::TransactionResponseExtension
+
+      def transaction_completed_at = transferred_at || super
+    end
+
+    # Helpers for PaystackGateway::Transfer::InitiateError
+    class InitiateError
+      def transaction_failed? = parsed_response_body[:status] == false && http_code == 400
+      def failure_reason = parsed_response_body[:message]
+    end
+
+    # Helpers for PaystackGateway::Transfer::VerifyResponse
+    class VerifyResponse
+      def transaction_completed_at = transferred_at || super
+    end
+
+    # Helpers for PaystackGateway::Transfer::VerifyError
+    class VerifyError
+      def transaction_not_found?
+        parsed_response_body[:status] == false && parsed_response_body[:message]&.match?(/transfer not found/i)
+      end
+    end
+  end
+end

data/lib/paystack_gateway/integration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/integration
+  #
+  # Integration
+  # A collection of endpoints for managing some settings on an integration
+  module Integration
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #fetch_payment_session_timeout.
+    class FetchPaymentSessionTimeoutResponse < PaystackGateway::Response
+      delegate :payment_session_timeout, to: :data
+    end
+
+    # Error response from #fetch_payment_session_timeout.
+    class FetchPaymentSessionTimeoutError < ApiError; end
+
+    # https://paystack.com/docs/api/integration/#fetch_payment_session_timeout
+    # Fetch Payment Session Timeout: GET /integration/payment_session_timeout
+    # Fetch the session timeout of a transaction
+    #
+    #
+    # @return [FetchPaymentSessionTimeoutResponse] successful response
+    # @raise [FetchPaymentSessionTimeoutError] if the request fails
+    api_method def self.fetch_payment_session_timeout
+      use_connection do |connection|
+        connection.get(
+          '/integration/payment_session_timeout',
+        )
+      end
+    end
+
+    # Successful response from calling #update_payment_session_timeout.
+    class UpdatePaymentSessionTimeoutResponse < PaystackGateway::Response
+      delegate :payment_session_timeout, to: :data
+    end
+
+    # Error response from #update_payment_session_timeout.
+    class UpdatePaymentSessionTimeoutError < ApiError; end
+
+    # https://paystack.com/docs/api/integration/#update_payment_session_timeout
+    # Update Payment Session Timeout: PUT /integration/payment_session_timeout
+    # Update the session timeout of a transaction
+    #
+    # @param timeout [Integer] (required)
+    #        Time in seconds before a transaction becomes invalid
+    #
+    # @return [UpdatePaymentSessionTimeoutResponse] successful response
+    # @raise [UpdatePaymentSessionTimeoutError] if the request fails
+    api_method def self.update_payment_session_timeout(timeout:)
+      use_connection do |connection|
+        connection.put(
+          '/integration/payment_session_timeout',
+          { timeout: }.compact,
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/legacy/customers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage customers https://paystack.com/docs/api/customer/
+  #
+  # @deprecated Use PaystackGateway::Customer instead.
+  module Customers
+    include PaystackGateway::RequestModule
+
+    # Common helpers for response from customer endpoints
+    module CustomerResponse
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :id, :customer_code, to: :data
+      end
+    end
+
+    class CreateCustomerResponse < PaystackGateway::Response
+      include CustomerResponse
+    end
+
+    api_method def self.create_customer(email:, first_name:, last_name:)
+      use_connection do |connection|
+        connection.post('/customer', { email:, first_name:, last_name: })
+      end
+    end
+
+    # Response from GET /customer/:email_or_id
+    class FetchCustomerResponse < PaystackGateway::Response
+      include CustomerResponse
+
+      delegate :subscriptions, :authorizations, to: :data
+
+      def active_subscriptions = subscriptions.select { _1.status == 'active' }
+      def active_subscription_codes = active_subscriptions.map(&:subscription_code)
+      def reusable_authorizations = authorizations.select(&:reusable)
+    end
+
+    api_method def self.fetch_customer(email:)
+      use_connection do |connection|
+        connection.get("/customer/#{email}")
+      end
+    end
+  end
+end