paygate_pk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06b7bfef5146c0fffbe72c7f1c173b08abb1873ec492a25b7b6e2366ebfbd45
-  data.tar.gz: d44d8b3169b624f1a0aa2b2e06c4754fc90136b4d055aad1b90121cc6d2faee1
+  metadata.gz: 5e12304e544277a26c17f5ce400fc0e43ea411fccd80976dc44f5262540f2fd2
+  data.tar.gz: 8eb47d711ec0dad930b961006168528b29d37aa076011f835781e79f6890840c
 SHA512:
-  metadata.gz: f7f8bb5aea01aac11d7579b384e9c7d4e63a03d367e77bc05d9ff48aed3959255f4f3aa54119a39cbe04be82d86ea80e2d3e5c8dfb842e697d31f1bd4fba91c0
-  data.tar.gz: 23131a34e78b2fb40bfe1ae582276766cccd997b3bcdbbef95b4d5021340c7dc28e59d6ce7f48b8049add3950082d13590b658f0b80ff5d47aca4151f1706369
+  metadata.gz: 5c32927ed495619815a9760f12c23e40f327d8122f079f66c28a45ed6fc9448a8d3b4344fbbec9f99c51888155dd42537272b1c1b629578f40c5e541f0cbdf76
+  data.tar.gz: 5b85b0f2ccd4c03a703480cf3dfa1ee3c207f97f708be8e66b6a7e90eefbb5e12c3e13bb3ad39ccca638345e2a0c72022c1e234b9f7a09e6ef43dc5fec675414

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.2.0] - 2025-10-10
+
+- Added: IPN verification, Tokenization 3.1 & 3.15.
+- Changed: renamed token methods (old name deprecated).
+- Security: switched to stdlib constant-time compare (no Rack dep).
+
 ## [0.1.0] - 2025-10-01
 
 - Initial release.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paygate_pk (0.1.0)
+    paygate_pk (0.2.0)
       faraday (>= 2.7)
       faraday-retry (>= 2.0)
       json
@@ -14,6 +14,7 @@ GEM
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
     bigdecimal (3.2.3)
+    byebug (12.0.0)
     crack (1.0.0)
       bigdecimal
       rexml
@@ -36,6 +37,8 @@ GEM
       uri
     nokogiri (1.18.9-x86_64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.9-x86_64-linux-gnu)
+      racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -79,8 +82,10 @@ GEM
 
 PLATFORMS
   x86_64-darwin-24
+  x86_64-linux
 
 DEPENDENCIES
+  byebug
   minitest (~> 5.0)
   paygate_pk!
   rake (~> 13.0)

data/README.md

@@ -15,11 +15,11 @@ This gem provides a clean, provider-agnostic interface to obtain access tokens a
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add "paygate_pk", "~> 0.1.0"
+    $ bundle add "paygate_pk", "~> 0.2.0"
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install "paygate_pk", "~> 0.1.0"
+    $ gem install "paygate_pk", "~> 0.2.0"
 
 ## Usage
 
@@ -34,10 +34,10 @@ PaygatePk.configure do |c|
 
   # PayFast base host only; endpoints include /Ecommerce/api internally
 
-  c.payfast.base_url = "https://ipguat.apps.net.pk"
-  c.payfast.merchant_id = ENV.fetch("PAYFAST_MERCHANT_ID")
-  c.payfast.secured_key = ENV.fetch("PAYFAST_SECURED_KEY")
-  c.payfast.checkout_mode = :immediate # or :delayed
+  c.pay_fast.base_url = "https://ipguat.apps.net.pk"
+  c.pay_fast.merchant_id = ENV.fetch("PAYFAST_MERCHANT_ID")
+  c.pay_fast.secured_key = ENV.fetch("PAYFAST_SECURED_KEY")
+  c.pay_fast.api_base_url = "https://api.getfrompayfast.com"
 
   # Optional: tune timeouts & retries
 
@@ -51,7 +51,8 @@ end
 # 1) Get Access Token (PayFast)
 
 ```ruby
-auth = PaygatePk::Providers::PayFast::Auth.new(config: PaygatePk.config.payfast)
+
+client = PaygatePk::Providers::PayFast::Auth.new
 
 token_obj = auth.get_access_token(
 basket_id: "B-1001",
@@ -67,25 +68,24 @@ puts token_obj.token # => "ACCESS_TOKEN_STRING"
 
 ```
 
-# 2) Create Hosted Checkout (PayFast)
+# 2) Verify IPN
 
 ```ruby
-checkout = PaygatePk::Providers::PayFast::Checkout.new(config: PaygatePk.config.payfast)
-
-hc = checkout.create!(opts: {
-  token:       token_obj.token,
-  basket_id:   "B-1001",
-  amount:      1500, # paisa (Rs 15.00)
-  customer:    { mobile: "03001234567", email: "buyer@example.com" },
-  success_url: "https://your-app.example.com/payments/success",
-  failure_url: "https://your-app.example.com/payments/failure",
-  description: "Order #1001"
-  # checkout_mode: :immediate,  # optional; default from config
-  # endpoint: "/Ecommerce/api/Transaction/PostTransaction" # optional override
-})
-
-hc.url # => "https://gateway.payfast/redirect/ABC123"
-# Redirect the buyer to hc.url
+verified_data  = client.verify_ipn!(request.params)
+
+:provider,          # Symbol e.g., :payfast
+:transaction_id,    # String or nil
+:basket_id,         # String
+:order_date,        # String (YYYY-MM-DD) or Time/Date if you coerce later
+:approved,          # Boolean (true if err_code == "000")
+:code,              # Provider code, e.g., "000"
+:message,           # Human-readable message
+:amount,            # String/Integer (as received)
+:currency,          # String "PKR" etc.
+:instrument_token,  # String or nil (for tokenized flows)
+:recurring,         # Boolean
+:raw,               # Original params Hash (unmodified input)
+
 ```
 
 # Error handling

data/lib/paygate_pk/config.rb

@@ -28,7 +28,8 @@ module PaygatePk
 
     # Provider-specific configuration
     class ProviderConfig
-      attr_accessor :base_url, :merchant_id, :secured_key, :checkout_mode, :username, :password, :store_id
+      attr_accessor :api_base_url, :base_url, :merchant_id, :secured_key, :checkout_mode, :username, :password,
+                    :store_id
 
       def initialize
         @base_url = nil
@@ -38,6 +39,7 @@ module PaygatePk
         @username = nil
         @password = nil
         @store_id = nil
+        @api_base_url = nil
       end
     end
   end

data/lib/paygate_pk/contracts/bearer_token.rb

@@ -0,0 +1,18 @@
+# lib/paygate_pk/contracts/access_token.rb
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Normalized wrapper for /token response.
+    # Some docs show only "refresh_token"; we expose both.
+    BearerToken = Struct.new(
+      :access_token,  # String or nil
+      :refresh_token, # String or nil
+      :expiry,        # Integer seconds or nil
+      :code,          # Provider code string or nil
+      :message,       # Provider message string or nil
+      :raw,           # Full response Hash
+      keyword_init: true
+    )
+  end
+end

data/lib/paygate_pk/contracts/instrument.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    Instrument = Struct.new(
+      :instrument_token, :account_type, :description, :instrument_alias, :raw,
+      keyword_init: true
+    )
+  end
+end

data/lib/paygate_pk/contracts/webhook_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Normalized server-side notification from PayFast (IPN) or other providers.
+    WebhookEvent = Struct.new(
+      :provider,          # Symbol e.g., :payfast
+      :transaction_id,    # String or nil
+      :basket_id,         # String
+      :order_date,        # String (YYYY-MM-DD) or Time/Date if you coerce later
+      :approved,          # Boolean (true if err_code == "000")
+      :code,              # Provider code, e.g., "000"
+      :message,           # Human-readable message
+      :amount,            # String/Integer (as received)
+      :currency,          # String "PKR" etc.
+      :instrument_token,  # String or nil (for tokenized flows)
+      :recurring,         # Boolean
+      :raw,               # Original params Hash (unmodified input)
+      keyword_init: true
+    )
+  end
+end

data/lib/paygate_pk/providers/pay_fast/auth.rb

@@ -27,6 +27,10 @@ module PaygatePk
 
         private
 
+        def base_url
+          config.base_url
+        end
+
         def ensure_config!
           missing = []
           missing << :merchant_id if @config.merchant_id.to_s.strip.empty?

data/lib/paygate_pk/providers/pay_fast/checkout.rb

@@ -62,6 +62,10 @@ module PaygatePk
 
         private
 
+        def base_url
+          config.base_url
+        end
+
         # -- Validation ---------------------------------------------------------
 
         def validate_config!

data/lib/paygate_pk/providers/pay_fast/client.rb

@@ -12,6 +12,26 @@ module PaygatePk
           @config = config
         end
 
+        def get_access_token(**params)
+          Auth.new(config: @config).get_access_token(**params)
+        end
+
+        def verify_ipn!(params)
+          Webhook.new(config: @config).verify!(params)
+        end
+
+        def create_checkout(**params)
+          Checkout.new(config: @config).create!(**params)
+        end
+
+        def get_bearer_token(**params)
+          Tokenization::Token.new(config: @config).get(**params)
+        end
+
+        def instruments(**params)
+          Tokenization::Instrument.new(config: @config).list(**params)
+        end
+
         private
 
         attr_reader :config
@@ -20,7 +40,7 @@ module PaygatePk
           raise ConfigurationError, "PayFast base_url not set" unless config.base_url
 
           PaygatePk::HTTP::Client.new(
-            base_url: config.base_url,
+            base_url: base_url,
             headers: { "Accept" => "application/json" },
             timeouts: PaygatePk.config.timeouts,
             retry_conf: PaygatePk.config.retry,

data/lib/paygate_pk/providers/pay_fast/tokenization/instrument.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Providers
+    module PayFast
+      module Tokenization
+        # used to generate the bearer_token
+        class Instrument < PaygatePk::Providers::PayFast::Client
+          INSTRUMENTS_ENDPOINT = "/api/user/instruments"
+
+          def list(token:, user_id:, mobile_number:, options: {})
+            ensure_present!(token: token,
+                            user_id: user_id,
+                            mobile_number: mobile_number)
+
+            resp = http.get(INSTRUMENTS_ENDPOINT,
+                            params: body(user_id, mobile_number, options),
+                            headers: { "Authorization" => "Bearer #{token}" })
+
+            # Response is an array of hashes with instrument_token, account_type, description, instrument_alias
+            Array(resp).map do |h|
+              PaygatePk::Contracts::Instrument.new(
+                instrument_token: h["instrument_token"],
+                account_type: h["account_type"],
+                description: h["description"],
+                instrument_alias: h["instrument_alias"],
+                raw: h
+              )
+            end
+          end
+
+          private
+
+          def base_url
+            config.api_base_url
+          end
+
+          def body(user_id, mobile_no, options)
+            attrs = {
+              "merchant_user_id" => user_id,
+              "user_mobile_number" => mobile_no
+            }
+
+            # rubocop:disable Naming/VariableNumber
+            attrs["customer_ip"] = options[:customer_ip] if options[:customer_ip]
+            attrs["reserved_1"]  = options[:reserved_1] if options[:reserved_1]
+            attrs["reserved_2"]  = options[:reserved_2] if options[:reserved_2]
+            attrs["reserved_3"]  = options[:reserved_3] if options[:reserved_3]
+            attrs["api_version"] = options[:api_version] if options[:api_version]
+            # rubocop:enable Naming/VariableNumber
+
+            attrs
+          end
+
+          def ensure_present!(**pairs)
+            missing = pairs.select { |_k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }.keys
+            raise PaygatePk::ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/providers/pay_fast/tokenization/token.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module PaygatePk
+  module Providers
+    module PayFast
+      module Tokenization
+        # used to generate the bearer_token
+        class Token < PaygatePk::Providers::PayFast::Client
+          TOKEN_ENDPOINT = "/api/token"
+          DEFAULT_GRANT_TYPE = "client_credentials"
+
+          # 3.1 Authentication Access Token
+          # Required: merchant_id, secured_key, grant_type
+          # Optional: customer_ip, reserved_1..3, api_version
+          # Returns: PaygatePk::Contracts::BearerToken
+          def get(grant_type: DEFAULT_GRANT_TYPE, options: {})
+            mid = config.merchant_id
+            sec = config.secured_key
+
+            ensure_present!(merchant_id: mid, secured_key: sec, grant_type: grant_type)
+
+            resp = http.post(TOKEN_ENDPOINT, form: body(mid, sec, grant_type, options))
+
+            PaygatePk::Contracts::BearerToken.new(
+              access_token: resp["token"], # if present
+              refresh_token: resp["refresh_token"], # shown in doc example
+              expiry: resp["expiry"],
+              code: resp["code"],
+              message: resp["message"],
+              raw: resp
+            )
+          end
+
+          private
+
+          def base_url
+            config.api_base_url
+          end
+
+          def body(mid, sec, grant_type, options)
+            attrs = {
+              "merchant_id" => mid,
+              "secured_key" => sec,
+              "grant_type" => grant_type
+            }
+            attrs["customer_ip"] = options[:customer_ip] if options[:customer_ip]
+            attrs["reserved_1"]  = options[:reserved1] if options[:reserved1]
+            attrs["reserved_2"] = options[:reserved2] if options[:reserved2]
+            attrs["reserved_3"]  = options[:reserved3] if options[:reserved3]
+            attrs["api_version"] = options[:api_version] if options[:api_version]
+
+            attrs
+          end
+
+          def ensure_present!(**pairs)
+            missing = pairs.select { |_k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }.keys
+            raise PaygatePk::ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/providers/pay_fast/webhook.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Providers
+    module PayFast
+      # Verifies PayFast IPN/notification params (GET to your CHECKOUT_URL)
+      # Returns PaygatePk::Contracts::WebhookEvent on success, raises on failure.
+      class Webhook
+        def verify!(raw_params)
+          params = normalize_keys(raw_params)
+
+          validate_required_params(params)
+          verify_signature(params)
+          build_webhook(params, raw_params)
+        end
+
+        private
+
+        def verify_signature(params)
+          expected = PaygatePk::Util::Signature::Payfast.validation_hash(
+            basket_id: params["basket_id"],
+            merchant_secret_key: PaygatePk.config.pay_fast.secured_key,
+            merchant_id: PaygatePk.config.pay_fast.merchant_id,
+            payfast_err_code: params["err_code"]
+          )
+          return if PaygatePk::Util::Security.secure_compare(expected, params["validation_hash"])
+
+          raise PaygatePk::SignatureError, "invalid validation_hash"
+        end
+
+        def validate_required_params(params)
+          %w[basket_id err_code validation_hash].each do |k|
+            raise PaygatePk::SignatureError, "missing #{k}" unless present?(params[k])
+          end
+        end
+
+        def normalize_keys(hash)
+          hash.transform_keys(&:to_s).tap do |x|
+            # common aliases to lowercase
+            x["instrument_token"] ||= x["Instrument_token"]
+            x["recurring_txn"]    ||= x["Recurring_txn"] || x["RECURRING_TXN"]
+          end
+        end
+
+        def present?(val)
+          !(val.nil? || (val.respond_to?(:empty?) && val.empty?))
+        end
+
+        def truthy?(val)
+          [true, "true", "TRUE", "1", 1].include?(val)
+        end
+
+        def build_webhook(params, raw_params)
+          PaygatePk::Contracts::WebhookEvent.new(
+            provider: :payfast,
+            transaction_id: params["transaction_id"],
+            basket_id: params["basket_id"],
+            order_date: params["order_date"],
+            approved: params["err_code"] == "000",
+            code: params["err_code"],
+            message: params["err_msg"],
+            amount: params["amount"],
+            currency: params["currency"],
+            instrument_token: params["instrument_token"] || params["Instrument_token"],
+            recurring: truthy?(params["recurring_txn"]) || truthy?(params["RECURRING_TXN"]),
+            raw: raw_params
+          )
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/util/security.rb

@@ -0,0 +1,27 @@
+# lib/paygate_pk/util/security.rb
+# frozen_string_literal: true
+
+require "openssl"
+
+module PaygatePk
+  module Util
+    # Constant-time string compare without Rack/ActiveSupport
+    module Security
+      module_function
+
+      # Constant-time string compare without Rack/ActiveSupport
+      def secure_compare(expected_hash, incoming_hash)
+        return false unless expected_hash.is_a?(String) && incoming_hash.is_a?(String)
+        return false unless expected_hash.bytesize == incoming_hash.bytesize
+
+        OpenSSL.fixed_length_secure_compare(expected_hash, incoming_hash)
+      rescue NoMethodError
+        # Fallback if Ruby/OpenSSL is too old (very rare on modern Ruby)
+        # XOR-based constant-time fallback
+        diff = 0
+        expected_hash.bytes.zip(incoming_hash.bytes) { |x, y| diff |= (x ^ y) }
+        diff.zero?
+      end
+    end
+  end
+end

data/lib/paygate_pk/util/signature.rb

@@ -0,0 +1,18 @@
+# lib/paygate_pk/util/signature.rb
+# frozen_string_literal: true
+
+require "openssl"
+
+module PaygatePk
+  module Util
+    module Signature
+      # validation_hash = SHA256("basket_id|merchant_secret_key|merchant_id|payfast_err_code")
+      module Payfast
+        def self.validation_hash(basket_id:, merchant_secret_key:, merchant_id:, payfast_err_code:)
+          data = [basket_id, merchant_secret_key, merchant_id, payfast_err_code].join("|")
+          OpenSSL::Digest::SHA256.hexdigest(data)
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/version.rb

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

data/lib/paygate_pk.rb

@@ -8,13 +8,19 @@ require_relative "paygate_pk/http/client"
 # Contracts used by the endpoint
 require_relative "paygate_pk/contracts/access_token"
 require_relative "paygate_pk/contracts/hosted_checkout"
+require_relative "paygate_pk/contracts/bearer_token"
+require_relative "paygate_pk/contracts/instrument"
+require_relative "paygate_pk/contracts/webhook_event"
 
 # PayFast
 require_relative "paygate_pk/providers/pay_fast/client"
 require_relative "paygate_pk/providers/pay_fast/auth"
 require_relative "paygate_pk/providers/pay_fast/checkout"
+require_relative "paygate_pk/providers/pay_fast/tokenization/token"
 
 require_relative "paygate_pk/util/html"
+require_relative "paygate_pk/util/signature"
+require_relative "paygate_pk/util/security"
 
 # Main module for PaygatePk
 module PaygatePk

data/paygate_pk.gemspec

@@ -35,10 +35,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "faraday", ">= 2.7"
   spec.add_dependency "faraday-retry", ">= 2.0"
   spec.add_dependency "json"
+  spec.add_dependency "nokogiri", ">= 1.16", "< 2.0"
 
-  # spec.add_development_dependency "byebug"
+  spec.add_development_dependency "byebug"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_dependency "nokogiri", ">= 1.16", "< 2.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rubocop", "~> 1.21"
   spec.add_development_dependency "simplecov", ">= 0.22"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paygate_pk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Talha Junaid
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-02 00:00:00.000000000 Z
+date: 2025-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -52,20 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +72,34 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -162,13 +176,21 @@ files:
 - lib/paygate_pk.rb
 - lib/paygate_pk/config.rb
 - lib/paygate_pk/contracts/access_token.rb
+- lib/paygate_pk/contracts/bearer_token.rb
 - lib/paygate_pk/contracts/hosted_checkout.rb
+- lib/paygate_pk/contracts/instrument.rb
+- lib/paygate_pk/contracts/webhook_event.rb
 - lib/paygate_pk/errors.rb
 - lib/paygate_pk/http/client.rb
 - lib/paygate_pk/providers/pay_fast/auth.rb
 - lib/paygate_pk/providers/pay_fast/checkout.rb
 - lib/paygate_pk/providers/pay_fast/client.rb
+- lib/paygate_pk/providers/pay_fast/tokenization/instrument.rb
+- lib/paygate_pk/providers/pay_fast/tokenization/token.rb
+- lib/paygate_pk/providers/pay_fast/webhook.rb
 - lib/paygate_pk/util/html.rb
+- lib/paygate_pk/util/security.rb
+- lib/paygate_pk/util/signature.rb
 - lib/paygate_pk/version.rb
 - paygate_pk.gemspec
 - sig/paygate_pk.rbs