paygate_pk 0.2.3 → 1.0.0

data/lib/paygate_pk/config.rb

@@ -1,45 +1,89 @@
 # frozen_string_literal: true
 
 module PaygatePk
-  # Global configuration for PaygatePk
+  # Global gem configuration.
+  #
+  # Typical Rails usage:
+  #   PaygatePk.configure do |c|
+  #     c.default_currency = "PKR"
+  #     c.pay_fast.environment   = Rails.env.production? ? :production : :sandbox
+  #     c.pay_fast.merchant_id   = ENV["PAYFAST_MERCHANT_ID"]
+  #     c.pay_fast.secured_key   = ENV["PAYFAST_SECURED_KEY"]
+  #     c.pay_fast.merchant_name = "Acme Store"
+  #     c.pay_fast.store_id      = ENV["PAYFAST_STORE_ID"]
+  #   end
+  #
+  # After `configure`, the config object is frozen — mutating it raises.
   class Config
-    attr_accessor :logger, :default_currency, :timeouts, :retry, :user_agent
+    attr_accessor :default_currency, :timeouts, :retry, :user_agent, :logger
     attr_reader   :pay_fast
 
     def initialize
-      @logger = nil
       @default_currency = "PKR"
-      @timeouts = { open_timeout: 5, read_timeout: 10 }
-      @retry = { max: 2, interval: 0.2, backoff_factor: 2.0, retry_statuses: [429, 500, 502, 503, 504] }
-      @user_agent = "paygate_pk/#{PaygatePk::VERSION}"
-
-      @pay_fast = ProviderConfig.new
-      @frozen = false
+      @timeouts         = { open_timeout: 5, read_timeout: 10 }
+      @retry            = {
+        max: 2, interval: 0.2, backoff_factor: 2.0,
+        retry_statuses: [429, 500, 502, 503, 504]
+      }
+      @user_agent       = "paygate_pk/#{PaygatePk::VERSION}"
+      @logger           = nil
+      @pay_fast         = PayFastConfig.new
+      @configured       = false
     end
 
+    # Mark as configured and deep-freeze. Called automatically by
+    # PaygatePk.configure after the block runs.
     def freeze!
-      @frozen = true
+      @configured = true
+      @pay_fast.freeze
+      freeze
       self
     end
 
-    def frozen?
-      @frozen
+    def configured?
+      @configured
     end
 
-    # Provider-specific configuration
-    class ProviderConfig
-      attr_accessor :api_base_url, :base_url, :merchant_id, :secured_key, :checkout_mode, :username, :password,
-                    :store_id
+    # Per-provider config for PayFast.
+    #
+    # `environment` selects the base URL via PayFast::Endpoints.
+    # `base_url` and `api_base_url` can override the env-derived URLs
+    # (useful for staging hosts PayFast hands out on request).
+    class PayFastConfig
+      ENVIRONMENTS = %i[sandbox production].freeze
+      DEFAULT_TRAN_TYPE = "ECOMM_PURCHASE"
+
+      attr_accessor :merchant_id, :secured_key, :merchant_name, :store_id,
+                    :version_string, :tran_type, :base_url, :api_base_url
+      attr_reader :environment
 
       def initialize
-        @base_url = nil
-        @merchant_id = nil
-        @secured_key = nil
-        @checkout_mode = :immediate
-        @username = nil
-        @password = nil
-        @store_id = nil
-        @api_base_url = nil
+        @environment    = :sandbox
+        @merchant_id    = nil
+        @secured_key    = nil
+        @merchant_name  = nil
+        @store_id       = nil
+        @version_string = nil
+        @tran_type      = DEFAULT_TRAN_TYPE
+        @base_url       = nil
+        @api_base_url   = nil
+      end
+
+      def environment=(env)
+        sym = env&.to_sym
+        unless ENVIRONMENTS.include?(sym)
+          raise ArgumentError,
+                "environment must be one of #{ENVIRONMENTS.inspect}, got #{env.inspect}"
+        end
+        @environment = sym
+      end
+
+      # Resolves the host URL used for redirect form action + token API.
+      # Explicit base_url wins; otherwise derived from environment.
+      def resolved_base_url
+        return base_url if base_url
+
+        PaygatePk::PayFast::Endpoints.base_url(environment)
       end
     end
   end

data/lib/paygate_pk/contracts/access_token.rb

@@ -1,8 +1,14 @@
-# lib/paygate_pk/contracts/access_token.rb
 # frozen_string_literal: true
 
 module PaygatePk
   module Contracts
-    AccessToken = Struct.new(:token, :raw, keyword_init: true)
+    # A PayFast ACCESS_TOKEN, fetched server-to-server via Auth#call,
+    # then plugged into the redirect form.
+    #
+    # `value` is the bare token string. `token` is kept as an alias so
+    # old call sites continue to read naturally (`access_token.token`).
+    AccessToken = Struct.new(:value, :raw, keyword_init: true) do
+      alias_method :token, :value
+    end
   end
 end

data/lib/paygate_pk/contracts/callback_event.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Normalised IPN / browser-return notification.
+    #
+    # Built by PaygatePk::PayFast::Callback.verify!(params). Will also
+    # be returned by Easypaisa's callback handler in 1.1, with the same
+    # fields populated where applicable. This is the gem's universal
+    # contract for "the gateway told us something about a transaction".
+    #
+    # Numeric-looking fields (amount, merchant_amount, discounted_amount)
+    # are surfaced as Strings — exactly as PayFast sent them. The host
+    # app converts to BigDecimal/Money on its side.
+    CallbackEvent = Struct.new(
+      :provider,           # Symbol e.g. :pay_fast
+      :transaction_id,     # String or nil
+      :basket_id,          # String
+      :order_date,         # String "YYYY-MM-DD"
+      :approved,           # Boolean — true if code == provider's success code
+      :code,               # String — err_code or responseCode
+      :message,            # String — err_msg or responseDesc
+      :amount,             # String — transaction_amount
+      :merchant_amount,    # String
+      :discounted_amount,  # String
+      :currency,           # String "PKR" etc.
+      :payment_method,     # String — PaymentName ("account", "card", "wallet")
+      :instrument_token,   # String or nil
+      :recurring,          # Boolean
+      :raw,                # Hash — original params, unmodified
+      keyword_init: true
+    ) do
+      def approved?
+        !!approved
+      end
+    end
+  end
+end

data/lib/paygate_pk/contracts/redirect_request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Everything a host application needs to render a browser-side
+    # redirect to the gateway's checkout page.
+    #
+    # Built by PaygatePk::PayFast::Redirect.build(...). Consumed by the
+    # Rails view helper paygate_pk_redirect_form (or by hand-rolled
+    # HTML in non-Rails apps).
+    #
+    #   redirect.action_url    # => "https://ipguat.apps.net.pk/Ecommerce/api/Transaction/PostTransaction"
+    #   redirect.http_method   # => :post
+    #   redirect.fields        # => { "MERCHANT_ID" => "...", "TOKEN" => "...", ... }
+    #
+    # `fields` keys are the exact PayFast field names (UPPER_SNAKE_CASE)
+    # so the host app doesn't need to know the wire format.
+    RedirectRequest = Struct.new(
+      :provider,    # Symbol, e.g. :pay_fast
+      :action_url,  # String
+      :http_method, # Symbol, typically :post
+      :fields,      # Hash<String,String>
+      :basket_id,   # String — echoed for convenience
+      :amount,      # String — echoed for convenience
+      :token,       # String — the underlying ACCESS_TOKEN
+      :raw,         # Hash   — the raw token-API response
+      keyword_init: true
+    )
+  end
+end

data/lib/paygate_pk/errors.rb

@@ -2,9 +2,11 @@
 
 module PaygatePk
   class Error < StandardError; end
+
   class ConfigurationError < Error; end
 
-  # Raised when a request validation fails.
+  class CapabilityNotSupported < Error; end
+
   class ValidationError < Error
     attr_reader :details
 
@@ -14,7 +16,6 @@ module PaygatePk
     end
   end
 
-  # Raised for HTTP errors, e.g. non-2xx responses.
   class HTTPError < Error
     attr_reader :status, :body
 
@@ -25,7 +26,19 @@ module PaygatePk
     end
   end
 
+  class TimeoutError < HTTPError; end
+  class ConnectionError < HTTPError; end
+
   class AuthError < Error; end
   class SignatureError < Error; end
-  class ProviderError < Error; end
+
+  class ProviderError < Error
+    attr_reader :code, :response
+
+    def initialize(message = "provider error", code: nil, response: nil)
+      @code = code
+      @response = response
+      super(message)
+    end
+  end
 end

data/lib/paygate_pk/http/client.rb

@@ -7,24 +7,31 @@ require "securerandom"
 
 module PaygatePk
   module HTTP
-    # Simple HTTP client using Faraday
+    # Thin Faraday wrapper used by every provider endpoint class.
+    #
+    # Responsibilities:
+    # - Build a single memoised Faraday connection per Client instance.
+    # - Map every Faraday::Error subclass to a typed PaygatePk error so
+    #   consumers can rescue PaygatePk::Error and catch everything.
+    # - Optional info-level logging with secret redaction.
+    # - Decode JSON response bodies opportunistically; passes through raw
+    #   String when the body isn't valid JSON (some PayFast endpoints
+    #   return text/HTML on error pages).
     class Client
-      def initialize(base_url:, headers: {}, timeouts: {}, retry_conf: {}, logger: nil)
-        @conn = Faraday.new(url: base_url) do |f|
-          f.request :retry,
-                    max: retry_conf[:max] || 2,
-                    interval: retry_conf[:interval] || 0.2,
-                    backoff_factor: retry_conf[:backoff_factor] || 2.0,
-                    retry_statuses: retry_conf[:retry_statuses] || [429, 500, 502, 503, 504]
-
-          f.request :url_encoded
-          f.response :raise_error
-          f.adapter Faraday.default_adapter
-        end
-
-        @headers  = headers
-        @timeouts = timeouts
-        @logger   = logger
+      # Field/header names whose values get masked in log output.
+      SENSITIVE_KEYS = %w[
+        SECURED_KEY secured_key password Password
+        Credentials credentials Authorization authorization
+      ].freeze
+
+      MASK = "[REDACTED]"
+
+      def initialize(base_url:, headers: {}, timeouts: nil, retry_conf: nil, logger: nil)
+        @base_url   = base_url
+        @headers    = headers
+        @timeouts   = timeouts   || PaygatePk.config.timeouts
+        @retry_conf = retry_conf || PaygatePk.config.retry
+        @logger     = logger     || PaygatePk.config.logger
       end
 
       def post(path, json: nil, form: nil, headers: {})
@@ -37,89 +44,95 @@ module PaygatePk
 
       private
 
-      # rubocop:disable Metrics/ParameterLists
-      def request(method, path, json: nil, form: nil, params: nil, headers: {})
-        resp = execute_request(method, path, params, headers) do |req|
-          configure_timeouts(req)
-          set_request_body(req, json, form)
+      def conn
+        @conn ||= Faraday.new(url: @base_url) do |f|
+          f.request :retry,
+                    max: @retry_conf[:max] || 2,
+                    interval: @retry_conf[:interval] || 0.2,
+                    backoff_factor: @retry_conf[:backoff_factor] || 2.0,
+                    retry_statuses: @retry_conf[:retry_statuses] || [429, 500, 502, 503, 504]
+          f.request :url_encoded
+          f.response :raise_error
+          f.adapter Faraday.default_adapter
         end
-
-        log_response(resp)
-        parse_body(resp)
-      rescue Faraday::ClientError => e
-        handle_client_error(e)
       end
-      # rubocop:enable Metrics/ParameterLists
 
-      def execute_request(method, path, params, headers)
-        @conn.run_request(method, path, nil, merged_headers(headers)) do |req|
-          req.params.update(params) if params
-          yield req if block_given?
+      # rubocop:disable Metrics/AbcSize
+      def request(method, path, json: nil, form: nil, params: nil, headers: {})
+        resp = conn.run_request(method, path, nil, merged_headers(headers)) do |req|
+          apply_timeouts(req)
+          req.params.update(params) if params && !params.empty?
+          apply_body(req, json: json, form: form)
         end
+
+        log_response(method, path, resp.status, form: form, json: json)
+        parse_body(resp)
+      rescue Faraday::TimeoutError => e
+        raise PaygatePk::TimeoutError.new(e.message, status: nil, body: nil)
+      rescue Faraday::ConnectionFailed => e
+        raise PaygatePk::ConnectionError.new(e.message, status: nil, body: nil)
+      rescue Faraday::Error => e
+        raise PaygatePk::HTTPError.new(
+          e.message,
+          status: e.response&.dig(:status),
+          body: e.response&.dig(:body)
+        )
       end
+      # rubocop:enable Metrics/AbcSize
 
       def merged_headers(headers)
         base_headers.merge(headers)
       end
 
-      def configure_timeouts(req)
-        req.options.timeout = @timeouts[:read_timeout] if @timeouts[:read_timeout]
+      def apply_timeouts(req)
         req.options.open_timeout = @timeouts[:open_timeout] if @timeouts[:open_timeout]
+        req.options.timeout      = @timeouts[:read_timeout] if @timeouts[:read_timeout]
       end
 
-      def set_request_body(req, json, form)
+      def apply_body(req, json:, form:)
         if json
-          set_json_body(req, json)
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(json)
         elsif form
-          set_form_body(req, form)
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = URI.encode_www_form(form)
         end
       end
 
-      def set_json_body(req, json)
-        req.headers["Content-Type"] = "application/json"
-        req.body = JSON.generate(json)
-      end
-
-      def set_form_body(req, form)
-        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-        req.body = URI.encode_www_form(form)
-      end
-
-      def handle_client_error(error)
-        body = error.response&.dig(:body)
-        status = error.response&.dig(:status)
-
-        raise PaygatePk::HTTPError.new(
-          error.message,
-          status: status,
-          body: body
-        )
-      end
-
       def base_headers
+        ua = PaygatePk.config.user_agent.to_s
+        ua = "paygate_pk" if ua.empty? # PayFast rejects empty user agents
         {
-          "User-Agent" => PaygatePk.config.user_agent || "paygate_pk",
+          "User-Agent" => ua,
           "X-Request-Id" => SecureRandom.uuid
         }.merge(@headers)
       end
 
       def parse_body(resp)
-        b = resp.body
-        if b.is_a?(String) && !b.empty?
-          begin
-            JSON.parse(b)
-          rescue StandardError
-            b
-          end
-        else
-          b
-        end
+        body = resp.body
+        return body unless body.is_a?(String) && !body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
       end
 
-      def log_response(resp)
+      def log_response(method, path, status, form:, json:)
         return unless @logger
 
-        @logger.info("paygate_pk http #{resp.env.method.upcase} #{resp.env.url} -> #{resp.status}")
+        sanitised = redact(form || json)
+        @logger.info(
+          "paygate_pk #{method.to_s.upcase} #{path} status=#{status} body=#{sanitised.inspect}"
+        )
+      end
+
+      def redact(body)
+        return nil if body.nil?
+        return body unless body.is_a?(Hash)
+
+        body.each_with_object({}) do |(k, v), acc|
+          acc[k] = SENSITIVE_KEYS.include?(k.to_s) ? MASK : v
+        end
       end
     end
   end

data/lib/paygate_pk/pay_fast/auth.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module PayFast
+    # Server-to-server PayFast token fetch (Merchant Integration Guide
+    # v2.3 §3.1). Internal: invoked by Redirect#build. Not advertised
+    # on the 1.0 public surface; use Redirect.build, which calls this
+    # automatically.
+    class Auth
+      def self.call(**kwargs)
+        new.call(**kwargs)
+      end
+
+      def initialize(config: PaygatePk::PayFast.config, http: nil)
+        @config = config
+        @http   = http
+      end
+
+      def call(basket_id:, amount:, currency: nil)
+        currency ||= PaygatePk.config.default_currency
+        ensure_config!
+        ensure_args!(basket_id: basket_id, amount: amount, currency: currency)
+
+        resp  = http.post(Endpoints::GET_ACCESS_TOKEN_PATH, form: payload(basket_id, amount, currency))
+        token = extract_token(resp)
+        raise PaygatePk::AuthError, "missing ACCESS_TOKEN in PayFast token response" if Coercions.blank?(token)
+
+        Contracts::AccessToken.new(value: token, raw: resp)
+      end
+
+      private
+
+      def http
+        @http ||= PaygatePk::HTTP::Client.new(
+          base_url: @config.resolved_base_url,
+          headers: { "Accept" => "application/json" }
+        )
+      end
+
+      def ensure_config!
+        missing = []
+        missing << :merchant_id if Coercions.blank?(@config.merchant_id)
+        missing << :secured_key if Coercions.blank?(@config.secured_key)
+        return if missing.empty?
+
+        raise PaygatePk::ConfigurationError, "PayFast config missing: #{missing.join(", ")}"
+      end
+
+      def ensure_args!(basket_id:, amount:, currency:)
+        missing = []
+        missing << :basket_id if Coercions.blank?(basket_id)
+        missing << :amount    if amount.nil?
+        missing << :currency  if Coercions.blank?(currency)
+        return if missing.empty?
+
+        raise PaygatePk::ValidationError.new(
+          "missing required args: #{missing.join(", ")}",
+          details: { missing: missing }
+        )
+      end
+
+      def payload(basket_id, amount, currency)
+        {
+          "MERCHANT_ID" => @config.merchant_id,
+          "SECURED_KEY" => @config.secured_key,
+          "BASKET_ID" => basket_id.to_s,
+          "TXNAMT" => Coercions.to_amount_string(amount),
+          "CURRENCY_CODE" => currency
+        }
+      end
+
+      def extract_token(resp)
+        return nil unless resp.is_a?(Hash)
+
+        resp["ACCESS_TOKEN"] || resp["access_token"]
+      end
+    end
+  end
+end

data/lib/paygate_pk/pay_fast/callback.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module PayFast
+    # Verifies the IPN / browser-return notification PayFast sends to
+    # SUCCESS_URL, FAILURE_URL, or the configured CHECKOUT_URL.
+    #
+    # Per Merchant Integration Guide v2.3 §3.2.3:
+    # - PayFast posts/redirects with mixed-case keys: `basket_id`,
+    #   `err_code`, `validation_hash` are lower; `Instrument_token`,
+    #   `Recurring_txn`, `PaymentName` are PascalCase. We down-case
+    #   everything internally so consumers don't have to care.
+    # - validation_hash = SHA256("basket_id|secured_key|merchant_id|err_code")
+    #   compared in constant time via Util::Security.secure_compare.
+    #
+    # Returns Contracts::CallbackEvent on success, raises SignatureError
+    # on missing fields or hash mismatch.
+    class Callback
+      REQUIRED_KEYS = %w[basket_id err_code validation_hash].freeze
+      SUCCESS_CODE  = "000"
+
+      def self.verify!(params, config: PaygatePk::PayFast.config)
+        new(config: config).verify!(params)
+      end
+
+      def initialize(config: PaygatePk::PayFast.config)
+        @config = config
+      end
+
+      def verify!(raw_params)
+        params = normalize_keys(raw_params)
+        ensure_required!(params)
+        ensure_signature!(params)
+        build_event(params, raw_params)
+      end
+
+      private
+
+      def normalize_keys(hash)
+        # ActionController::Parameters and HashWithIndifferentAccess both
+        # respond to #to_h; fall back to dup for plain Hashes.
+        source = hash.respond_to?(:to_unsafe_h) ? hash.to_unsafe_h : hash.to_h
+        source.transform_keys { |k| k.to_s.downcase }
+      end
+
+      def ensure_required!(params)
+        missing = REQUIRED_KEYS.select { |k| Coercions.blank?(params[k]) }
+        return if missing.empty?
+
+        raise PaygatePk::SignatureError, "missing required callback param(s): #{missing.join(", ")}"
+      end
+
+      def ensure_signature!(params)
+        expected = PaygatePk::Util::Signature::PayFast.validation_hash(
+          basket_id: params["basket_id"],
+          merchant_secret_key: @config.secured_key,
+          merchant_id: @config.merchant_id,
+          payfast_err_code: params["err_code"]
+        )
+        return if PaygatePk::Util::Security.secure_compare(expected, params["validation_hash"].to_s)
+
+        raise PaygatePk::SignatureError, "invalid validation_hash"
+      end
+
+      def build_event(params, raw)
+        Contracts::CallbackEvent.new(
+          provider: :pay_fast,
+          transaction_id: params["transaction_id"],
+          basket_id: params["basket_id"],
+          order_date: params["order_date"],
+          approved: params["err_code"] == SUCCESS_CODE,
+          code: params["err_code"],
+          message: params["err_msg"],
+          amount: params["transaction_amount"],
+          merchant_amount: params["merchant_amount"],
+          discounted_amount: params["discounted_amount"],
+          currency: params["transaction_currency"],
+          payment_method: params["paymentname"],
+          instrument_token: params["instrument_token"],
+          recurring: truthy?(params["recurring_txn"]),
+          raw: raw
+        )
+      end
+
+      def truthy?(value)
+        return false if value.nil?
+
+        %w[true 1 yes].include?(value.to_s.downcase)
+      end
+    end
+  end
+end

data/lib/paygate_pk/pay_fast/endpoints.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module PayFast
+    # Centralised URL map. Selecting between sandbox and production is a
+    # config flag (PayFastConfig#environment); callers never hand-type
+    # hostnames.
+    #
+    # If/when PayFast hands you a bespoke staging host, set
+    #   PaygatePk.config.pay_fast.base_url = "https://..."
+    # to override the env-derived value.
+    module Endpoints
+      URLS = {
+        sandbox: "https://ipguat.apps.net.pk",
+        # PayFast has not published an official production base URL in
+        # the v2.3 doc; merchants typically receive it on go-live.
+        # Configure via `c.pay_fast.base_url = "..."` until then.
+        production: "https://ipg1.apps.net.pk"
+      }.freeze
+
+      GET_ACCESS_TOKEN_PATH = "/Ecommerce/api/Transaction/GetAccessToken"
+      POST_TRANSACTION_PATH = "/Ecommerce/api/Transaction/PostTransaction"
+
+      module_function
+
+      def base_url(env)
+        URLS.fetch(env) do
+          raise PaygatePk::ConfigurationError, "unknown PayFast environment: #{env.inspect}"
+        end
+      end
+
+      def post_transaction_url(env_or_base)
+        host = URLS[env_or_base] || env_or_base
+        "#{host}#{POST_TRANSACTION_PATH}"
+      end
+    end
+  end
+end