paygate_pk 0.2.3 → 1.1.0

data/lib/paygate_pk/pay_fast.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  # PayFast integration.
+  #
+  # Public API (1.0):
+  #
+  #   PaygatePk::PayFast::Redirect.build(...)  # => Contracts::RedirectRequest
+  #   PaygatePk::PayFast::Callback.verify!(p)  # => Contracts::CallbackEvent
+  #
+  # Internal helpers (Auth, Endpoints) are loaded but not part of the
+  # advertised surface — they may change without a major version bump.
+  module PayFast
+    # Shortcut to the provider-scoped config block.
+    def self.config
+      PaygatePk.config.pay_fast
+    end
+  end
+end

data/lib/paygate_pk/rails/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "view_helpers"
+
+module PaygatePk
+  module Rails
+    # Wires ViewHelpers into ActionView when the gem boots inside a
+    # Rails app. Loaded conditionally from lib/paygate_pk.rb so that
+    # non-Rails consumers don't have to install Rails to use the gem.
+    class Railtie < ::Rails::Railtie
+      initializer "paygate_pk.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include PaygatePk::Rails::ViewHelpers
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/rails/view_helpers.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Rails
+    # Action View helpers, auto-included into ActionView::Base by the
+    # Railtie when the gem boots inside a Rails app.
+    module ViewHelpers
+      DEFAULT_FORM_ID = "paygate-pk-redirect-form"
+      SUBMIT_LABEL    = "Pay now"
+
+      OTC_VOUCHER_SUCCESS_CLASS = "paygate-pk-otc-voucher rounded-2xl border border-emerald-200 bg-emerald-50 p-6"
+      OTC_VOUCHER_FAILURE_CLASS = "paygate-pk-otc-voucher paygate-pk-otc-voucher--failed " \
+                                  "rounded-2xl border border-rose-200 bg-rose-50 p-6"
+
+      # Renders the auto-submitting redirect form for any provider that
+      # produces a Contracts::RedirectRequest.
+      #
+      #   <%= paygate_pk_redirect_form(@redirect) %>
+      #
+      # Options:
+      #   autosubmit: true (default) — emits a script tag that submits
+      #               the form on page load. Set to false to render a
+      #               visible "Pay now" button instead.
+      #   html:       { id:, class:, data: { ... }, ... } — passed
+      #               straight to the <form> tag. `id` falls back to
+      #               "paygate-pk-redirect-form".
+      #   submit_label: button label when autosubmit is false.
+      def paygate_pk_redirect_form(redirect, autosubmit: true, html: {}, submit_label: SUBMIT_LABEL)
+        form_id   = html[:id] || DEFAULT_FORM_ID
+        form_html = render_form(redirect, form_id, html, autosubmit, submit_label)
+        return form_html unless autosubmit
+
+        form_html + autosubmit_script(form_id)
+      end
+
+      # Renders a printable Easypaisa OTC voucher from a
+      # Contracts::ChargeResult (from PaygatePk::EasyPaisa::OTC.create).
+      #
+      #   <%= paygate_pk_otc_voucher(@voucher) %>
+      #
+      # Options:
+      #   html:   { class:, ... } — outer container overrides
+      #   title:  heading text (default "Pay at any Easypaisa shop")
+      #   instructions: array of bullet strings; falls back to a sane
+      #                 default that mentions the expiry time
+      def paygate_pk_otc_voucher(result, html: {}, title: "Pay at any Easypaisa shop", instructions: nil)
+        return otc_voucher_failure(result, html) unless result.success? && result.payment_token.present?
+
+        container_attrs = otc_voucher_attrs(html, success: true)
+        body = otc_voucher_success_body(result, title: title,
+                                                instructions: instructions || default_otc_instructions(result))
+
+        content_tag(:div, body, container_attrs)
+      end
+
+      private
+
+      def render_form(redirect, form_id, html, autosubmit, submit_label)
+        attrs = {
+          id: form_id,
+          action: redirect.action_url,
+          method: redirect.http_method.to_s,
+          accept_charset: "UTF-8"
+        }.merge(html.except(:id))
+
+        content_tag(:form, attrs) do
+          hidden = redirect.fields.map do |name, value|
+            tag.input(type: "hidden", name: name.to_s, value: value.to_s)
+          end
+          submit = autosubmit ? "".html_safe : tag.button(submit_label, type: "submit")
+          safe_join(hidden + [submit])
+        end
+      end
+
+      def autosubmit_script(form_id)
+        javascript_tag(
+          "document.getElementById(#{form_id.to_json}).submit();",
+          nonce: respond_to?(:content_security_policy_nonce) ? content_security_policy_nonce : nil
+        )
+      end
+
+      # ── OTC voucher rendering ─────────────────────────────────────
+
+      def otc_voucher_attrs(html, success:)
+        default_class = success ? OTC_VOUCHER_SUCCESS_CLASS : OTC_VOUCHER_FAILURE_CLASS
+        html.merge(class: [default_class, html[:class]].compact.join(" "))
+      end
+
+      def otc_voucher_success_body(result, title:, instructions:)
+        safe_join([
+                    content_tag(:h3, title, class: "text-base font-bold text-slate-900 mb-4"),
+                    otc_voucher_token_block(result),
+                    otc_voucher_meta(result),
+                    otc_voucher_instructions(instructions)
+                  ])
+      end
+
+      def otc_voucher_token_block(result)
+        content_tag(:div, class: "rounded-xl bg-white border border-emerald-200 px-5 py-4 mb-4 text-center") do
+          safe_join([
+                      content_tag(:p, "Payment token",
+                                  class: "text-xs font-semibold uppercase tracking-wide text-slate-500"),
+                      content_tag(:p, result.payment_token,
+                                  class: "mt-1 font-mono text-2xl font-bold tracking-widest text-slate-900")
+                    ])
+        end
+      end
+
+      def otc_voucher_meta(result)
+        rows = []
+        rows << ["Amount",  "PKR #{result.amount}"]
+        rows << ["Mobile",  result.customer[:msisdn]] if result.customer[:msisdn].present?
+        rows << ["Expires", otc_voucher_format_time(result.expires_at)] if result.expires_at
+        rows << ["Order",   result.basket_id]
+
+        content_tag(:dl, class: "grid grid-cols-2 gap-y-2 text-sm mb-4") do
+          safe_join(rows.flat_map do |label, value|
+            [
+              content_tag(:dt, label, class: "text-slate-500"),
+              content_tag(:dd, value, class: "text-right font-semibold text-slate-900")
+            ]
+          end)
+        end
+      end
+
+      def otc_voucher_instructions(instructions)
+        content_tag(:ul, class: "list-disc pl-5 space-y-1 text-xs text-slate-600") do
+          safe_join(instructions.map { |line| content_tag(:li, line) })
+        end
+      end
+
+      def default_otc_instructions(result)
+        expiry = result.expires_at ? otc_voucher_format_time(result.expires_at) : nil
+        [
+          "Visit any Easypaisa shop with the token above.",
+          "Pay PKR #{result.amount} in cash and quote your token to the agent.",
+          expiry ? "Pay before #{expiry} — the token expires after that." : nil
+        ].compact
+      end
+
+      def otc_voucher_failure(result, html)
+        container_attrs = otc_voucher_attrs(html, success: false)
+        message = result.response_message.presence || "Easypaisa did not issue a token for this order."
+        body = safe_join([
+                           content_tag(:h3, "Voucher unavailable", class: "text-base font-bold text-rose-900 mb-2"),
+                           content_tag(:p, message, class: "text-sm text-rose-700")
+                         ])
+        content_tag(:div, body, container_attrs)
+      end
+
+      def otc_voucher_format_time(value)
+        return value if value.is_a?(String)
+        return nil unless value.respond_to?(:strftime)
+
+        value.strftime("%d %b %Y, %I:%M %p")
+      end
+    end
+  end
+end

data/lib/paygate_pk/util/credentials.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module PaygatePk
+  module Util
+    # Header-credential helpers used by REST providers that authenticate
+    # with a static username/password pair.
+    #
+    # Easypaisa: header key "Credentials", value is Base64Strict of
+    # "username:password" -- HTTP-Basic style but WITHOUT the literal
+    # "Basic " scheme prefix.
+    module Credentials
+      module_function
+
+      # Returns Base64Strict("user:pass"). Raises if either is blank
+      # -- empty credentials would silently authenticate as a different
+      # principal and produce baffling 401s downstream.
+      def basic(username, password)
+        raise PaygatePk::ConfigurationError, "username is required" if Coercions.blank?(username)
+        raise PaygatePk::ConfigurationError, "password is required" if Coercions.blank?(password)
+
+        Base64.strict_encode64("#{username}:#{password}")
+      end
+    end
+  end
+end

data/lib/paygate_pk/util/signature/pay_fast.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module PaygatePk
+  module Util
+    module Signature
+      # PayFast IPN/return validation_hash computation.
+      #
+      # Per Merchant Integration Guide v2.3 §3.2.3:
+      #   validation_hash = SHA256("basket_id|secured_key|merchant_id|err_code")
+      #
+      # Returned as a hex digest. Compared in constant time on the receiving
+      # side via PaygatePk::Util::Security.secure_compare.
+      module PayFast
+        SEPARATOR = "|"
+
+        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(SEPARATOR)
+          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.2.3"
+  VERSION = "1.1.0"
 end

data/lib/paygate_pk.rb

@@ -2,37 +2,73 @@
 
 require_relative "paygate_pk/version"
 require_relative "paygate_pk/errors"
+require_relative "paygate_pk/coercions"
 require_relative "paygate_pk/config"
+
+require_relative "paygate_pk/util/security"
+require_relative "paygate_pk/util/signature/pay_fast"
+require_relative "paygate_pk/util/credentials"
+
 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/webhook"
-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"
+require_relative "paygate_pk/contracts/redirect_request"
+require_relative "paygate_pk/contracts/callback_event"
+require_relative "paygate_pk/contracts/charge_result"
+require_relative "paygate_pk/contracts/inquiry_result"
+
+require_relative "paygate_pk/pay_fast"
+require_relative "paygate_pk/pay_fast/endpoints"
+require_relative "paygate_pk/pay_fast/auth"
+require_relative "paygate_pk/pay_fast/redirect"
+require_relative "paygate_pk/pay_fast/callback"
 
-# Main module for PaygatePk
+require_relative "paygate_pk/easy_paisa"
+require_relative "paygate_pk/easy_paisa/endpoints"
+require_relative "paygate_pk/easy_paisa/client"
+require_relative "paygate_pk/easy_paisa/mobile_account"
+require_relative "paygate_pk/easy_paisa/otc"
+require_relative "paygate_pk/easy_paisa/inquiry"
+
+require_relative "paygate_pk/rails/railtie" if defined?(Rails::Railtie)
+
+# Unified Ruby/Rails client for Pakistani payment gateways.
+#
+#   PaygatePk.configure do |c|
+#     # PayFast (hosted checkout / redirection)
+#     c.pay_fast.environment   = :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"
+#
+#     # Easypaisa (REST APIs)
+#     c.easy_paisa.environment = :sandbox
+#     c.easy_paisa.username    = ENV["EASYPAISA_USERNAME"]
+#     c.easy_paisa.password    = ENV["EASYPAISA_PASSWORD"]
+#     c.easy_paisa.store_id    = ENV["EASYPAISA_STORE_ID"]
+#   end
+#
+#   redirect = PaygatePk::PayFast::Redirect.build(...)
+#   event    = PaygatePk::PayFast::Callback.verify!(request.parameters)
+#   result   = PaygatePk::EasyPaisa::MobileAccount.charge(...)
+#   voucher  = PaygatePk::EasyPaisa::OTC.create(...)
+#   status   = PaygatePk::EasyPaisa::Inquiry.fetch(...)
 module PaygatePk
   class << self
     def configure
       yield(config)
       config.freeze!
+      config
     end
 
     def config
-      @config ||= PaygatePk::Config.new
+      @config ||= Config.new
+    end
+
+    # Test/dev helper. Discards the current (possibly frozen) config so
+    # that a fresh PaygatePk.configure call can re-seed it.
+    def reset_config!
+      @config = Config.new
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paygate_pk
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Talha Junaid
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-10 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -53,25 +53,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: actionview
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.16'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
+        version: '7.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.16'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -156,9 +150,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |-
-  Provider-agnostic Ruby/Rails client for PayFast: checkout, webhooks/IPN verification,
-                        tokenized & recurring payments.
+description: PaygatePk is a provider-agnostic Ruby/Rails client for payment gateways
+  operating in Pakistan. 1.0 ships PayFast hosted-checkout (redirection) and callback
+  verification with a one-line Rails view helper. Easypaisa REST (MA/OTC/Inquiry)
+  lands in 1.1.
 email:
 - talhajunaid65@gmail.com
 executables: []
@@ -174,43 +169,50 @@ files:
 - README.md
 - Rakefile
 - lib/paygate_pk.rb
+- lib/paygate_pk/coercions.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/contracts/callback_event.rb
+- lib/paygate_pk/contracts/charge_result.rb
+- lib/paygate_pk/contracts/inquiry_result.rb
+- lib/paygate_pk/contracts/redirect_request.rb
+- lib/paygate_pk/easy_paisa.rb
+- lib/paygate_pk/easy_paisa/client.rb
+- lib/paygate_pk/easy_paisa/endpoints.rb
+- lib/paygate_pk/easy_paisa/inquiry.rb
+- lib/paygate_pk/easy_paisa/mobile_account.rb
+- lib/paygate_pk/easy_paisa/otc.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/pay_fast.rb
+- lib/paygate_pk/pay_fast/auth.rb
+- lib/paygate_pk/pay_fast/callback.rb
+- lib/paygate_pk/pay_fast/endpoints.rb
+- lib/paygate_pk/pay_fast/redirect.rb
+- lib/paygate_pk/rails/railtie.rb
+- lib/paygate_pk/rails/view_helpers.rb
+- lib/paygate_pk/util/credentials.rb
 - lib/paygate_pk/util/security.rb
-- lib/paygate_pk/util/signature.rb
+- lib/paygate_pk/util/signature/pay_fast.rb
 - lib/paygate_pk/version.rb
-- paygate_pk.gemspec
 - sig/paygate_pk.rbs
 homepage: https://github.com/qbitechs/paygate_pk
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/qbitechs/paygate_pk
-  changelog_uri: https://github.com/qbitechs/paygate_pk/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/qbitechs/paygate_pk/blob/master/CHANGELOG.md
   homepage_url: https://github.com/qbitechs/paygate_pk
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
 - lib
-- test
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -220,5 +222,5 @@ requirements: []
 rubygems_version: 3.4.3
 signing_key:
 specification_version: 4
-summary: Unified Ruby wrapper for PayFast
+summary: Unified Ruby/Rails client for Pakistani payment gateways (PayFast, Easypaisa)
 test_files: []

data/lib/paygate_pk/contracts/bearer_token.rb

@@ -1,18 +0,0 @@
-# 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/hosted_checkout.rb

@@ -1,8 +0,0 @@
-# lib/paygate_pk/contracts/access_token.rb
-# frozen_string_literal: true
-
-module PaygatePk
-  module Contracts
-    HostedCheckout = Struct.new(:provider, :basket_id, :amount, :url, :raw, :form, keyword_init: true)
-  end
-end

data/lib/paygate_pk/contracts/instrument.rb

@@ -1,10 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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
-      :payment_method,
-      :merchant_amount,
-      :raw,               # Original params Hash (unmodified input)
-      keyword_init: true
-    )
-  end
-end

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

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "date"
-
-module PaygatePk
-  module Providers
-    module PayFast
-      # Auth client for PayFast API
-      class Auth < Client
-        ENDPOINT = "/Ecommerce/api/Transaction/GetAccessToken"
-
-        # Returns Contracts::AccessToken
-        # Required by PayFast: MERCHANT_ID, SECURED_KEY, BASKET_ID, TXNAMT, CURRENCY_CODE
-        #
-        def get_access_token(basket_id:, amount:, currency: PaygatePk.config.default_currency, endpoint: ENDPOINT)
-          ensure_config!
-          ensure_args!(basket_id: basket_id, amount: amount, currency: currency)
-
-          # Guide endpoint: .../Ecommerce/api/Transaction/GetAccessToken
-          resp  = http.post(endpoint,
-                            form: payload(basket_id, amount, currency))
-          token = resp.is_a?(Hash) ? (resp["ACCESS_TOKEN"] || resp["access_token"]) : nil
-          raise AuthError, "missing ACCESS_TOKEN in response" unless token
-
-          Contracts::AccessToken.new(token: token, raw: resp)
-        end
-
-        private
-
-        def base_url
-          config.base_url
-        end
-
-        def ensure_config!
-          missing = []
-          missing << :merchant_id if @config.merchant_id.to_s.strip.empty?
-          missing << :secured_key if @config.secured_key.to_s.strip.empty?
-          raise ConfigurationError, "PayFast config missing: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        def ensure_args!(basket_id:, amount:, currency:)
-          missing = []
-          missing << :basket_id if basket_id.to_s.strip.empty?
-          missing << :amount if amount.nil?
-          missing << :currency if currency.to_s.strip.empty?
-          raise ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        def payload(basket_id, amount, currency)
-          {
-            "MERCHANT_ID" => @config.merchant_id,
-            "SECURED_KEY" => @config.secured_key,
-            "BASKET_ID" => basket_id,
-            "TXNAMT" => amount.to_s,
-            "CURRENCY_CODE" => currency
-          }
-        end
-      end
-    end
-  end
-end