paygate_pk 0.2.3 → 1.0.0

data/lib/paygate_pk/pay_fast/redirect.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "date"
+require "securerandom"
+
+module PaygatePk
+  module PayFast
+    # Builds the redirect form that the customer's browser submits to
+    # PayFast's hosted checkout page.
+    #
+    # Flow (Merchant Integration Guide v2.3 §3.2):
+    #   1. Fetch ACCESS_TOKEN server-to-server (delegated to Auth)
+    #   2. Assemble all the PostTransaction form fields (mandatory +
+    #      optional), with PayFast's UPPER_SNAKE_CASE naming
+    #   3. Return a Contracts::RedirectRequest the host app renders
+    #      as an auto-submitting <form>
+    #
+    # Usage:
+    #
+    #   redirect = PaygatePk::PayFast::Redirect.build(
+    #     basket_id:    "sp-#{payment.id}",
+    #     amount:       1500,
+    #     description:  "Subscription",
+    #     customer:     { mobile: "03001234567", email: "buyer@x.com", name: "Talha" },
+    #     success_url:  success_url,
+    #     failure_url:  failure_url,
+    #     checkout_url: webhooks_pay_fast_url,  # optional, IPN backend ping
+    #     recurring:    false
+    #   )
+    class Redirect
+      # Address-block field mapping. Preserves the SHIPPING_ADDRESS_CITU
+      # typo from the PayFast spec — we mirror what the gateway accepts,
+      # not what looks correct.
+      SHIPPING_FIELDS = {
+        name: "SHIPPING_CUSTOMER_NAME",
+        address_1: "SHIPPING_ADDRESS_1",
+        address_2: "SHIPPING_ADDRESS_2",
+        state: "SHIPPING_STATE_PROVINCE",
+        city: "SHIPPING_ADDRESS_CITU",
+        postal_code: "SHIPPING_POSTALCODE",
+        method: "SHIPPING_METHOD"
+      }.freeze
+
+      BILLING_FIELDS = {
+        name: "BILLING_CUSTOMER_NAME",
+        city: "BILLING_ADDRESS_CITY",
+        address_1: "BILLING_ADDRESS_1",
+        address_2: "BILLING_ADDRESS_2",
+        state: "BILLING_STATE_PROVINCE",
+        postal_code: "BILLING_POSTALCODE"
+      }.freeze
+
+      def self.build(**kwargs)
+        new.build(**kwargs)
+      end
+
+      def initialize(config: PaygatePk::PayFast.config, auth: nil)
+        @config = config
+        @auth   = auth
+      end
+
+      def build(basket_id:, amount:, customer:, success_url:, failure_url:, description:,
+                currency: nil, order_date: nil, checkout_url: nil, store_id: nil,
+                items: [], recurring: false, tran_type: nil, processing_type: nil,
+                instrument_token: nil, shipping: nil, billing: nil, country: nil,
+                customer_ip: nil, merchant_customer_id: nil, merchant_user_agent: nil,
+                transaction_instrument: nil, extra_fields: {})
+        currency ||= PaygatePk.config.default_currency
+        order_date_str = Coercions.to_iso_date(order_date) || Date.today.strftime("%Y-%m-%d")
+
+        ensure_config!
+        ensure_args!(basket_id: basket_id, amount: amount, customer: customer,
+                     success_url: success_url, failure_url: failure_url, description: description)
+
+        token = auth.call(basket_id: basket_id, amount: amount, currency: currency)
+
+        fields = build_fields(
+          token: token.value,
+          basket_id: basket_id,
+          amount: amount,
+          currency: currency,
+          customer: customer,
+          success_url: success_url,
+          failure_url: failure_url,
+          checkout_url: checkout_url,
+          description: description,
+          order_date_str: order_date_str,
+          store_id: store_id,
+          items: items,
+          recurring: recurring,
+          tran_type: tran_type,
+          processing_type: processing_type,
+          instrument_token: instrument_token,
+          transaction_instrument: transaction_instrument,
+          shipping: shipping,
+          billing: billing,
+          country: country,
+          customer_ip: customer_ip,
+          merchant_customer_id: merchant_customer_id,
+          merchant_user_agent: merchant_user_agent,
+          extra_fields: extra_fields
+        )
+
+        Contracts::RedirectRequest.new(
+          provider: :pay_fast,
+          action_url: Endpoints.post_transaction_url(@config.resolved_base_url),
+          http_method: :post,
+          fields: fields,
+          basket_id: basket_id.to_s,
+          amount: Coercions.to_amount_string(amount),
+          token: token.value,
+          raw: token.raw
+        )
+      end
+
+      private
+
+      def auth
+        @auth ||= Auth.new(config: @config)
+      end
+
+      def ensure_config!
+        missing = []
+        missing << :merchant_id   if Coercions.blank?(@config.merchant_id)
+        missing << :secured_key   if Coercions.blank?(@config.secured_key)
+        missing << :merchant_name if Coercions.blank?(@config.merchant_name)
+        return if missing.empty?
+
+        raise PaygatePk::ConfigurationError, "PayFast config missing: #{missing.join(", ")}"
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def ensure_args!(basket_id:, amount:, customer:, success_url:, failure_url:, description:)
+        missing = []
+        missing << :basket_id   if Coercions.blank?(basket_id)
+        missing << :amount      if amount.nil?
+        missing << :success_url if Coercions.blank?(success_url)
+        missing << :failure_url if Coercions.blank?(failure_url)
+        missing << :description if Coercions.blank?(description)
+        missing << "customer.mobile" if !customer.is_a?(Hash) || Coercions.blank?(customer[:mobile])
+        missing << "customer.email" if !customer.is_a?(Hash) || Coercions.blank?(customer[:email])
+        return if missing.empty?
+
+        raise PaygatePk::ValidationError.new(
+          "missing required args: #{missing.join(", ")}",
+          details: { missing: missing }
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def build_fields(**opts)
+        fields = {}
+        add_mandatory_fields!(fields, opts)
+        add_optional_simple_fields!(fields, opts)
+        add_address_fields!(fields, "SHIPPING", opts[:shipping]) if opts[:shipping]
+        add_address_fields!(fields, "BILLING",  opts[:billing])  if opts[:billing]
+        add_items_fields!(fields, opts[:items]) if opts[:items].is_a?(Array) && !opts[:items].empty?
+        add_extra_fields!(fields, opts[:extra_fields])
+        fields
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def add_mandatory_fields!(fields, opts)
+        fields["MERCHANT_ID"]            = @config.merchant_id
+        fields["MERCHANT_NAME"]          = @config.merchant_name
+        fields["TOKEN"]                  = opts[:token]
+        fields["PROCCODE"]               = "00"
+        fields["TXNAMT"]                 = Coercions.to_amount_string(opts[:amount])
+        fields["CUSTOMER_MOBILE_NO"]     = opts[:customer][:mobile].to_s
+        fields["CUSTOMER_EMAIL_ADDRESS"] = opts[:customer][:email].to_s
+        # SIGNATURE and VERSION are documented as "A random string value"
+        # in Merchant Integration Guide v2.3 §3.2 — they are not crypto
+        # signatures. We generate a fresh random per request.
+        fields["SIGNATURE"]              = SecureRandom.hex(16)
+        fields["VERSION"]                = @config.version_string || "paygate_pk/#{PaygatePk::VERSION}"
+        fields["TXNDESC"]                = opts[:description]
+        fields["SUCCESS_URL"]            = opts[:success_url]
+        fields["FAILURE_URL"]            = opts[:failure_url]
+        fields["BASKET_ID"]              = opts[:basket_id].to_s
+        fields["ORDER_DATE"]             = opts[:order_date_str]
+        fields["CURRENCY_CODE"]          = opts[:currency]
+        fields["TRAN_TYPE"]              = opts[:tran_type] || @config.tran_type
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def add_optional_simple_fields!(fields, opts)
+        fields["CHECKOUT_URL"]           = opts[:checkout_url] if opts[:checkout_url]
+        store_id                         = opts[:store_id] || @config.store_id
+        fields["STORE_ID"]               = store_id if Coercions.present?(store_id)
+        fields["RECURRING_TXN"]          = opts[:recurring] ? "TRUE" : "FALSE"
+        fields["CUSTOMER_NAME"]          = opts[:customer][:name].to_s          if opts[:customer][:name]
+        fields["CUSTOMER_IPADDRESS"]     = opts[:customer_ip]                   if opts[:customer_ip]
+        fields["MERCHANT_CUSTOMER_ID"]   = opts[:merchant_customer_id]          if opts[:merchant_customer_id]
+        fields["MERCHANT_USERAGENT"]     = opts[:merchant_user_agent]           if opts[:merchant_user_agent]
+        fields["COUNTRY"]                = opts[:country]                       if opts[:country]
+        fields["PROCESSING_TYPE"]        = opts[:processing_type]               if opts[:processing_type]
+        fields["INSTRUMENT_TOKEN"]       = opts[:instrument_token]              if opts[:instrument_token]
+        fields["Transaction_Instrument"] = opts[:transaction_instrument].to_s   if opts[:transaction_instrument]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def add_address_fields!(fields, prefix, hash)
+        map = prefix == "SHIPPING" ? SHIPPING_FIELDS : BILLING_FIELDS
+        map.each do |key, payfast_name|
+          v = hash[key]
+          fields[payfast_name] = v.to_s if Coercions.present?(v)
+        end
+      end
+
+      def add_items_fields!(fields, items)
+        items.each_with_index do |item, i|
+          fields["ITEMS[#{i}][SKU]"]   = item[:sku].to_s                       if item[:sku]
+          fields["ITEMS[#{i}][NAME]"]  = item[:name].to_s                      if item[:name]
+          fields["ITEMS[#{i}][PRICE]"] = Coercions.to_amount_string(item[:price]) if item[:price]
+          fields["ITEMS[#{i}][QTY]"]   = item[:qty].to_s if item[:qty]
+        end
+      end
+
+      def add_extra_fields!(fields, extras)
+        return unless extras.is_a?(Hash)
+
+        extras.each { |k, v| fields[k.to_s] = v.to_s }
+      end
+    end
+  end
+end

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,59 @@
+# 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"
+
+      # 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
+
+      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
+    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.0.0"
 end

data/lib/paygate_pk.rb

@@ -2,37 +2,53 @@
 
 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/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"
 
-# Main module for PaygatePk
+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"
+
+require_relative "paygate_pk/rails/railtie" if defined?(Rails::Railtie)
+
+# Unified Ruby/Rails client for Pakistani payment gateways.
+#
+#   PaygatePk.configure do |c|
+#     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"
+#   end
+#
+#   redirect = PaygatePk::PayFast::Redirect.build(...)
+#   event    = PaygatePk::PayFast::Callback.verify!(request.parameters)
 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.0.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,41 @@ 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/redirect_request.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/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 +213,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