paystack_sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a18abe45774bda30eff6f91a3e93ba55066d9ef4f04ddfc690792edc8b005d94
-  data.tar.gz: 652cc2b936ac3a7211290ad6a6f561d57132fd825588232fab724a0b2378cfa7
+  metadata.gz: 7771d8c6ca4931f237e71c171c7507cfcd9ca5b6159974ee4a4a37d3d667a0e7
+  data.tar.gz: e2c83863b81cd30f7fed5380f145ccfa283a25ea334a30e33cb86170636f0b50
 SHA512:
-  metadata.gz: 5fcb8324376b91af1c71e894309789fb69a4eeefff5d4a1fa93c190a66c9c01489d5a8a9b4003f8416fbff3ffe5d3474ec6ec49ab9c1a58ed7fb16ebf095c04a
-  data.tar.gz: b094c91f15744f8c02ca9e493d7aa6ab7b9c24f6f0e25cc8e1a94d32bc9d3101aa713a97ff074000e365e1f1857d26735bd99016e82a480b7da839e6be9b349e
+  metadata.gz: aeeef1dcbfd223247142cfa6ee3ffb85624f2cc392ba5a993f9224ab5a4166273f386b1bf4a6fc4d0571dd30b3a626f08a1d0234cbe3808124e350c88228bebb
+  data.tar.gz: f8af0ecc7ef80cd7cfd0ab4858365bdce1b244115402869e5b1b29e3a6018816f19224ed0df2483d2fd732d6babd12a75764f4c324cdc55ee32bc35212d83654

data/lib/paystack_sdk/client.rb

@@ -6,6 +6,7 @@ require_relative "resources/transfer_recipients"
 require_relative "resources/transfers"
 require_relative "resources/banks"
 require_relative "resources/verification"
+require_relative "resources/charges"
 require_relative "utils/connection_utils"
 
 module PaystackSdk
@@ -121,5 +122,19 @@ module PaystackSdk
     def verification
       @verification ||= Resources::Verification.new(@connection)
     end
+
+    # Provides access to the `Charges` resource.
+    #
+    # @return [PaystackSdk::Resources::Charges] An instance of the
+    #  `Charges` resource.
+    #
+    # @example
+    # ```ruby
+    #   charges = client.charges
+    #   response = charges.mobile_money(payload)
+    # ```
+    def charges
+      @charges ||= Resources::Charges.new(@connection)
+    end
   end
 end

data/lib/paystack_sdk/resources/charges.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # The `Charges` resource exposes helpers for initiating and managing charges
+    # through alternative payment channels such as Mobile Money.
+    #
+    # At the moment the SDK focuses on supporting the Mobile Money channel which
+    # requires posting to the `/charge` endpoint with the customer's email,
+    # amount, currency, and the provider specific `mobile_money` payload.
+    class Charges < PaystackSdk::Resources::Base
+      MOBILE_MONEY_PROVIDERS = %w[mtn atl vod mpesa orange wave].freeze
+
+      # Initiates a Mobile Money payment.
+      #
+      # @param payload [Hash] The payload containing charge details.
+      # @option payload [String] :email Customer's email address (required)
+      # @option payload [Integer] :amount Amount in the lowest currency unit (required)
+      # @option payload [String] :currency ISO currency code (default: GHS)
+      # @option payload [String] :reference Optional reference supplied by the merchant
+      # @option payload [String] :callback_url Optional callback URL for Paystack to redirect to
+      # @option payload [Hash] :metadata Optional metadata to attach to the transaction
+      # @option payload [Hash] :mobile_money The mobile money details (required)
+      #   - :phone [String] Customer's mobile money phone number (required)
+      #   - :provider [String] Mobile money provider code (required)
+      #
+      # @return [PaystackSdk::Response] The wrapped API response.
+      # @raise [PaystackSdk::ValidationError] If the payload is invalid.
+      def mobile_money(payload)
+        validate_mobile_money_payload!(payload)
+
+        normalized_payload = normalize_mobile_money_provider(payload)
+        response = @connection.post("/charge", normalized_payload)
+        handle_response(response)
+      end
+
+      # Submits an OTP for authorising a pending Mobile Money charge (e.g. Vodafone).
+      #
+      # @param payload [Hash] Payload containing the OTP and charge reference.
+      # @option payload [String] :otp The OTP supplied by the customer (required)
+      # @option payload [String] :reference The charge reference returned from initiation (required)
+      #
+      # @return [PaystackSdk::Response] The wrapped API response.
+      # @raise [PaystackSdk::ValidationError] If the payload is invalid.
+      def submit_otp(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            otp: {type: :string, required: true},
+            reference: {type: :reference, required: true}
+          }
+        )
+
+        response = @connection.post("/charge/submit_otp", payload)
+        handle_response(response)
+      end
+
+      private
+
+      def validate_mobile_money_payload!(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            email: {type: :email, required: true},
+            amount: {type: :positive_integer, required: true},
+            currency: {type: :currency, required: false},
+            reference: {type: :reference, required: false},
+            callback_url: {required: false},
+            metadata: {required: false},
+            mobile_money: {required: true}
+          }
+        )
+
+        mobile_money = payload[:mobile_money] || payload["mobile_money"]
+        validate_hash!(input: mobile_money, name: "mobile_money")
+
+        phone = mobile_money[:phone] || mobile_money["phone"]
+        validate_presence!(value: phone, name: "mobile_money phone")
+
+        provider = mobile_money[:provider] || mobile_money["provider"]
+        validate_mobile_money_provider!(provider)
+      end
+
+      def validate_mobile_money_provider!(provider)
+        normalized = provider&.to_s&.downcase
+        validate_allowed_values!(
+          value: normalized,
+          allowed_values: MOBILE_MONEY_PROVIDERS,
+          name: "mobile_money provider",
+          allow_nil: false
+        )
+      end
+
+      def normalize_mobile_money_provider(payload)
+        mm = payload[:mobile_money] || payload["mobile_money"] || {}
+        provider = mm[:provider] || mm["provider"]
+        normalized_provider = provider&.to_s&.downcase
+        # Avoid mutating the caller's payload
+        payload.merge(mobile_money: mm.merge(provider: normalized_provider))
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/customers.rb

@@ -68,13 +68,9 @@ module PaystackSdk
         validate_positive_integer!(value: per_page, name: "per_page", allow_nil: true)
         validate_positive_integer!(value: page, name: "page", allow_nil: true)
 
-        if params[:from]
-          validate_date_format!(date_str: params[:from], name: "from")
-        end
+        validate_date_format!(date_str: params[:from], name: "from") if params[:from]
 
-        if params[:to]
-          validate_date_format!(date_str: params[:to], name: "to")
-        end
+        validate_date_format!(date_str: params[:to], name: "to") if params[:to]
 
         query_params = {perPage: per_page, page: page}.merge(params)
         response = @connection.get("customer", query_params)

data/lib/paystack_sdk/response.rb

@@ -85,9 +85,7 @@ module PaystackSdk
           @error_message = @api_message || "Client error"
 
           # Still raise for authentication issues as these are usually config problems
-          if @status_code == 401
-            raise AuthenticationError.new(@api_message || "Authentication failed")
-          end
+          raise AuthenticationError.new(@api_message || "Authentication failed") if @status_code == 401
         when 429
           # Rate limiting - raise as users need to implement retry logic
           retry_after = response.headers["Retry-After"]
@@ -211,7 +209,7 @@ module PaystackSdk
     # @yield [key, value] For hashes, passes each key-value pair
     # @yield [value] For arrays, passes each item
     # @return [Response, Enumerator] Self for chaining or Enumerator if no block given
-    def each(&block)
+    def each
       return enum_for(:each) unless block_given?
 
       if @raw_data.is_a?(Hash)
@@ -231,7 +229,7 @@ module PaystackSdk
     #   @return [Integer] The number of items
     # @!method empty?
     #   @return [Boolean] Whether the collection is empty
-    [:size, :length, :count, :empty?].each do |method_name|
+    %i[size length count empty?].each do |method_name|
       define_method(method_name) do
         @raw_data.send(method_name) if @raw_data.respond_to?(method_name)
       end
@@ -242,9 +240,10 @@ module PaystackSdk
     #   @return [Object, Response] The first item, wrapped if necessary
     # @!method last
     #   @return [Object, Response] The last item, wrapped if necessary
-    [:first, :last].each do |method_name|
+    %i[first last].each do |method_name|
       define_method(method_name) do
         return nil unless @raw_data.is_a?(Array)
+
         wrap_value(@raw_data.send(method_name))
       end
     end
@@ -261,9 +260,7 @@ module PaystackSdk
 
       # First try to get identifier from the message
       message = body["message"].to_s.downcase
-      if message =~ /with (id|code|reference|email): ([^\s]+)/i
-        return $2
-      end
+      return ::Regexp.last_match(2) if message =~ /with (id|code|reference|email): ([^\s]+)/i
 
       # If not found in message, try to extract from error code
       if body["code"]&.match?(/^(transaction|customer)_/)
@@ -288,6 +285,7 @@ module PaystackSdk
     # @return [Hash, Array, nil] The data from the response
     def extract_data_from_body(body)
       return body unless body.is_a?(Hash)
+
       body["data"] || body
     end
 

data/lib/paystack_sdk/validations.rb

@@ -37,9 +37,9 @@ module PaystackSdk
     # @param name [String] Name of the parameter for error messages
     # @raise [PaystackSdk::InvalidFormatError] If input is not a hash
     def validate_hash!(input:, name: "Payload")
-      unless input.is_a?(Hash)
-        raise PaystackSdk::InvalidFormatError.new(name, "Hash")
-      end
+      return if input.is_a?(Hash)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "Hash")
     end
 
     # Validates that required parameters are present in a payload.
@@ -53,10 +53,10 @@ module PaystackSdk
         !payload.key?(param) && !payload.key?(param.to_s)
       end
 
-      unless missing_params.empty?
-        param = missing_params.first
-        raise PaystackSdk::MissingParamError.new(param)
-      end
+      return if missing_params.empty?
+
+      param = missing_params.first
+      raise PaystackSdk::MissingParamError.new(param)
     end
 
     # Validates that a value is present (not nil or empty).
@@ -91,9 +91,9 @@ module PaystackSdk
     # @param name [String] Name of the parameter for error messages
     # @raise [PaystackSdk::InvalidFormatError] If reference format is invalid
     def validate_reference_format!(reference:, name: "Reference")
-      unless reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
-        raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
-      end
+      return if reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "alphanumeric characters and the following: -, ., =")
     end
 
     # Validates a date string format.
@@ -106,6 +106,7 @@ module PaystackSdk
     def validate_date_format!(date_str:, name: "Date", allow_nil: true)
       if date_str.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
@@ -136,13 +137,14 @@ module PaystackSdk
     def validate_allowed_values!(value:, allowed_values:, name: "Parameter", allow_nil: true)
       if value.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless allowed_values.include?(value)
-        allowed_list = allowed_values.join(", ")
-        raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
-      end
+      return if allowed_values.include?(value)
+
+      allowed_list = allowed_values.join(", ")
+      raise PaystackSdk::InvalidValueError.new(name, "must be one of: #{allowed_list}")
     end
 
     # Validates an email format.
@@ -154,12 +156,13 @@ module PaystackSdk
     def validate_email!(email:, name: "Email", allow_nil: false)
       if email.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
-        raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
-      end
+      return if email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "valid email address")
     end
 
     # Validates a currency code format.
@@ -171,12 +174,13 @@ module PaystackSdk
     def validate_currency!(currency:, name: "Currency", allow_nil: true)
       if currency.nil?
         raise PaystackSdk::MissingParamError.new(name) unless allow_nil
+
         return
       end
 
-      unless currency.to_s.match?(/\A[A-Z]{3}\z/)
-        raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
-      end
+      return if currency.to_s.match?(/\A[A-Z]{3}\z/)
+
+      raise PaystackSdk::InvalidFormatError.new(name, "3-letter ISO code (e.g., NGN, USD, GHS)")
     end
 
     # Validates multiple fields at once.

data/lib/paystack_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackSdk
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
@@ -24,75 +24,75 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.13.1
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 1.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 1.9.0
 - !ruby/object:Gem::Dependency
-  name: standard
+  name: irb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.15.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.15.1
 - !ruby/object:Gem::Dependency
-  name: irb
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.15.1
+        version: 13.2.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.15.1
+        version: 13.2.1
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 13.2.1
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 13.2.1
+        version: '3.13'
 - !ruby/object:Gem::Dependency
-  name: debug
+  name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.0
+        version: 1.49.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.0
+        version: 1.49.0
 description: |
   The `paystack_sdk` gem provides a simple and intuitive interface for
   interacting with Paystack's payment gateway API. It allows developers to
@@ -117,6 +117,7 @@ files:
 - lib/paystack_sdk/client.rb
 - lib/paystack_sdk/resources/banks.rb
 - lib/paystack_sdk/resources/base.rb
+- lib/paystack_sdk/resources/charges.rb
 - lib/paystack_sdk/resources/customers.rb
 - lib/paystack_sdk/resources/transactions.rb
 - lib/paystack_sdk/resources/transfer_recipients.rb