paygate_pk 0.2.3 → 1.1.0

data/README.md

@@ -1,118 +1,345 @@
 # PaygatePk
 
-Unified Ruby wrapper for PayFast (and soon Easypaisa) payments in Pakistan.
+Unified Ruby/Rails client for Pakistani payment gateways.
 
-This gem provides a clean, provider-agnostic interface to obtain access tokens and create hosted checkouts with PayFast. It wraps HTTP details, validates required fields, and exposes simple, Ruby-friendly objects. Rails-friendly configuration is included; IPN verification and recurring/tokenized flows are on the roadmap.
+**1.0 ships:** PayFast hosted-checkout (redirection flow) and callback verification, with a one-line Rails view helper.
+**1.1 ships:** Easypaisa REST APIs — Mobile Account, OTC voucher, Inquiry — plus a Rails OTC voucher helper.
+**1.2 will ship:** PayFast tokenization / saved-instrument charge and Easypaisa IPN verification.
+
+The gem wraps every documented field from the *PayFast Merchant Integration Guide v2.3* and the *Easypaisa REST APIs without RSA Integration Guide*, validates required inputs, normalises dates and amounts, and returns plain Struct value objects you can pass around your Rails app.
 
 ## Requirements
 
 - Ruby ≥ 3.1
-- Faraday (runtime, included by gemspec)
-- Nokogiri (runtime, for HTML redirect parsing, included)
-- (Dev) Byebug, SimpleCov, RuboCop — optional
+- Faraday ≥ 2.7
+- (Rails apps) ActionView ≥ 7.0 for the view helper
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add "paygate_pk", "~> 0.2.0"
-
-If bundler is not being used to manage dependencies, install the gem by executing:
+```sh
+bundle add paygate_pk
+```
 
-    $ gem install "paygate_pk", "~> 0.2.0"
+Or in a Gemfile:
 
-## Usage
+```ruby
+gem "paygate_pk", "~> 1.1"
+```
 
-# Initializer
+## Configure
 
 ```ruby
 # config/initializers/paygate_pk.rb
-
 PaygatePk.configure do |c|
   c.default_currency = "PKR"
-  c.user_agent = "paygate_pk/#{PaygatePk::VERSION}"
 
-  # PayFast base host only; endpoints include /Ecommerce/api internally
+  # PayFast (hosted checkout / redirection)
+  c.pay_fast.environment   = Rails.env.production? ? :production : :sandbox
+  c.pay_fast.merchant_id   = Rails.application.credentials.dig(:pay_fast, :merchant_id)
+  c.pay_fast.secured_key   = Rails.application.credentials.dig(:pay_fast, :secured_key)
+  c.pay_fast.merchant_name = "Acme Store"
+  c.pay_fast.store_id      = Rails.application.credentials.dig(:pay_fast, :store_id)  # optional
+
+  # Easypaisa (REST: Mobile Account / OTC / Inquiry)
+  c.easy_paisa.environment = Rails.env.production? ? :production : :sandbox
+  c.easy_paisa.username    = Rails.application.credentials.dig(:easy_paisa, :username)
+  c.easy_paisa.password    = Rails.application.credentials.dig(:easy_paisa, :password)
+  c.easy_paisa.store_id    = Rails.application.credentials.dig(:easy_paisa, :store_id)
+  c.easy_paisa.account_num = Rails.application.credentials.dig(:easy_paisa, :account_num)  # required for Inquiry
+end
+```
+
+Sandbox URLs are built in for both providers. If either hands you a bespoke staging or production host, override with `c.pay_fast.base_url = "https://..."` / `c.easy_paisa.base_url = "https://..."`.
+
+After the block runs the config is deep-frozen for the lifetime of the process. Use `PaygatePk.reset_config!` in console/tests to start over.
 
-  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"
+## Take a one-time payment via PayFast redirect
 
-  # Optional: tune timeouts & retries
+### 1. Build the redirect
 
-  c.timeouts = { open_timeout: 5, read_timeout: 10 }
-  c.retry = { max: 2, interval: 0.2, backoff_factor: 2.0, retry_statuses: [429, 500, 502, 503, 504] }
+```ruby
+class Subscription::PaymentsController < ApplicationController
+  def create
+    @redirect = PaygatePk::PayFast::Redirect.build(
+      basket_id:    "sp-#{payment.id}",
+      amount:       1500,                                # rupees
+      description:  "Pro plan — monthly",
+      customer:     {
+        mobile: current_user.mobile,                     # real 03xx mobile (mandatory)
+        email:  current_user.email,
+        name:   current_user.name                        # optional
+      },
+      success_url:  success_subscription_payments_url,
+      failure_url:  failed_subscription_payments_url,
+      checkout_url: webhooks_pay_fast_url,               # optional backend IPN ping
+      recurring:    false
+    )
+  end
 end
 ```
 
-## QuickStart
+### 2. Render the auto-submitting form
 
-# 1) Get Access Token (PayFast)
+```erb
+<%# app/views/subscription/payments/create.html.erb %>
+<%= paygate_pk_redirect_form(@redirect, autosubmit: true) %>
+```
 
-```ruby
+The customer's browser is now on PayFast. They pick a bank/card/wallet, enter their OTP, and PayFast redirects them back to your `success_url` (or `failure_url`).
 
-client = PaygatePk::Providers::PayFast::Auth.new
+### 3. Verify the return / IPN
 
-token_obj = auth.get_access_token(
-basket_id: "B-1001",
-amount: 1500
+```ruby
+class Subscription::PaymentsController < ApplicationController
+  def success
+    event = PaygatePk::PayFast::Callback.verify!(request.parameters)
+    if event.approved?
+      payment = SubscriptionPayment.find_by(basket_id: event.basket_id)
+      payment&.mark_completed!(transaction_id: event.transaction_id, amount: event.amount)
+      redirect_to dashboard_path, notice: "Payment received."
+    else
+      redirect_to dashboard_path, alert: "Payment failed: #{event.message}"
+    end
+  rescue PaygatePk::SignatureError
+    head :bad_request
+  end
+end
+```
 
-# currency: "PKR", # optional; defaults to PaygatePk.config.default_currency
+For the server-to-server IPN (PayFast also POSTs to `CHECKOUT_URL`), wire the same call into your webhook controller — it's the more reliable source of truth (it doesn't depend on the customer's browser making it back).
 
-# endpoint: "/Ecommerce/api/Transaction/GetAccessToken" # optional override
+## All redirect options
 
+```ruby
+PaygatePk::PayFast::Redirect.build(
+  basket_id:    "B-1001",
+  amount:       1500,
+  description:  "Order #1001",
+  customer:     { mobile: "03001234567", email: "buyer@x.com", name: "Talha" },
+  success_url:  "https://app/success",
+  failure_url:  "https://app/failure",
+
+  # — optional —
+  currency:               "PKR",            # defaults to config.default_currency
+  order_date:             Date.today,       # Date / Time / String, coerced to YYYY-MM-DD
+  checkout_url:           "https://app/ipn",
+  store_id:               "102-ABC",        # overrides config.pay_fast.store_id
+  recurring:              false,
+  tran_type:              "ECOMM_PURCHASE", # overrides config.pay_fast.tran_type
+  processing_type:        "HYBRID_TOKEN",
+  instrument_token:       "tok-from-saved-card",
+  transaction_instrument: 3,                # 1=bank, 2=UnionPay, 3=card, 4=wallet
+
+  items: [
+    { sku: "SKU-1", name: "Widget", price: 100, qty: 2 },
+    { sku: "SKU-2", name: "Gizmo",  price: 50,  qty: 1 }
+  ],
+
+  shipping: {
+    name: "Talha", address_1: "House 9", address_2: "St 4",
+    state: "Punjab", city: "Lahore", postal_code: "54000", method: "Courier"
+  },
+  billing:  { name: "Talha", city: "Lahore", address_1: "House 9" },
+
+  country:              "PK",
+  customer_ip:          request.remote_ip,
+  merchant_customer_id: current_user.id.to_s,
+  merchant_user_agent:  request.user_agent,
+
+  extra_fields:         { "CUSTOM_X" => "value" }  # forward-compatible passthrough
 )
+```
+
+## Take a payment via Easypaisa (REST)
+
+Easypaisa offers two flavours; pick per use case:
 
-puts token_obj.token # => "ACCESS_TOKEN_STRING"
+- **Mobile Account (MA)** — customer authorises in their Easypaisa app via OTP push; merchant gets paid immediately. No redirect, no voucher.
+- **OTC (Over-the-Counter)** — merchant issues a payment token; customer pays cash at any Easypaisa shop within the expiry window.
 
+### Mobile Account
+
+```ruby
+result = PaygatePk::EasyPaisa::MobileAccount.charge(
+  order_id:          "lawzo-#{payment.id}",
+  amount:            1500,
+  mobile_account_no: "03001234567",
+  email:             "client@example.com",
+  optional:          { "1" => "tenant-42" }  # optional1..5 passthrough
+)
+
+if result.success?
+  payment.update!(external_transaction_id: result.transaction_id, status: :pending)
+  # customer now sees the OTP prompt on their Easypaisa app
+else
+  flash[:alert] = "Easypaisa: #{result.response_message} (code #{result.response_code})"
+end
 ```
 
-# 2) Verify IPN
+### OTC voucher
 
 ```ruby
-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)
+voucher = PaygatePk::EasyPaisa::OTC.create(
+  order_id:     "lawzo-#{payment.id}",
+  amount:       1500,
+  msisdn:       "03001234567",
+  email:        "client@example.com",
+  token_expiry: 7.days.from_now    # Date / Time / DateTime / pre-formatted String
+)
+voucher.payment_token   # => "40933012" — print or show this
+voucher.expires_at      # => Time
+```
 
+```erb
+<%# Rails: one-line printable voucher %>
+<%= paygate_pk_otc_voucher(@voucher) %>
 ```
 
-# Error handling
+### Inquiry (poll status)
+
+Use this after issuing an OTC voucher (or for any MA transaction you didn't catch via IPN):
+
+```ruby
+status = PaygatePk::EasyPaisa::Inquiry.fetch(
+  order_id:    "lawzo-#{payment.id}",
+  account_num: PaygatePk.config.easy_paisa.account_num    # falls back to config
+)
+
+case status.transaction_status
+when "PAID"     then payment.mark_completed!(amount: status.transaction_amount)
+when "FAILED", "EXPIRED", "BLOCKED", "REVERSED" then payment.mark_failed!(reason: status.transaction_status)
+when "PENDING"  then # customer hasn't visited a shop yet -- check again later
+end
+```
 
-All errors inherit from PaygatePk::Error:
+Predicates available on the result: `paid?`, `failed?`, `pending?`, `expired?`, `blocked?`, `reversed?`, `successful_lookup?`.
+
+> **Note on IPN.** Easypaisa supports merchant-portal-configured IPN callbacks, but the wire spec isn't published in the REST guide. Until 1.2 ships `EasyPaisa::Callback.verify!`, poll `Inquiry.fetch` from a background job for OTC and on-demand for MA.
+
+## Contracts
+
+### `Contracts::RedirectRequest`
+
+What `Redirect.build` returns, what the view helper consumes.
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:pay_fast` |
+| `action_url` | `String` | Where the browser POSTs |
+| `http_method` | `Symbol` | `:post` |
+| `fields` | `Hash<String,String>` | Every PayFast form field |
+| `basket_id` | `String` | Echo |
+| `amount` | `String` | Echo |
+| `token` | `String` | The access token |
+| `raw` | `Hash` | Raw token-API response |
+
+### `Contracts::CallbackEvent`
+
+What `Callback.verify!` returns.
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:pay_fast` |
+| `transaction_id` | `String?` |  |
+| `basket_id` | `String` |  |
+| `order_date` | `String` | `YYYY-MM-DD` |
+| `approved` / `approved?` | `Boolean` | `true` iff `err_code == "000"` |
+| `code` | `String` | PayFast `err_code` |
+| `message` | `String` | PayFast `err_msg` |
+| `amount` | `String` | `transaction_amount` |
+| `merchant_amount` | `String` |  |
+| `discounted_amount` | `String` |  |
+| `currency` | `String` |  |
+| `payment_method` | `String` | "card", "account", "wallet" |
+| `instrument_token` | `String?` |  |
+| `recurring` | `Boolean` |  |
+| `raw` | `Hash` | Original params, unmodified |
+
+### `Contracts::ChargeResult` *(Easypaisa MA / OTC)*
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:easy_paisa` |
+| `basket_id` | `String` | Easypaisa `orderId` echo |
+| `transaction_id` | `String?` | Ericsson EWP id (MA only) |
+| `payment_token` | `String?` | Cash-redemption token (OTC only) |
+| `payment_mode` | `Symbol` | `:mobile_account` or `:otc` |
+| `expires_at` | `Time?` | OTC token expiry |
+| `transacted_at` | `Time?` |  |
+| `amount` | `String` |  |
+| `currency` | `String` |  |
+| `customer` | `Hash` | Echo of submitted customer info |
+| `response_code` | `String` | `"0000"` on success |
+| `response_message` | `String` | `responseDesc` |
+| `success_code` | `String` | `"0000"` — provider's success literal |
+| `raw` | `Hash` | Full provider response |
+
+Predicates: `success?`, `failed?`, `otc?`, `mobile_account?`.
+
+### `Contracts::InquiryResult` *(Easypaisa Inquire Transaction)*
+
+| Field | Type | Notes |
+|---|---|---|
+| `provider` | `Symbol` | `:easy_paisa` |
+| `basket_id` | `String` | Echoed `orderId` |
+| `account_num` | `String` |  |
+| `store_id` / `store_name` | `String?` |  |
+| `payment_token` | `String?` | OTC only |
+| `transaction_status` | `String` | `PAID`/`FAILED`/`PENDING`/`BLOCKED`/`EXPIRED`/`REVERSED` |
+| `transaction_amount` | `String` |  |
+| `transaction_date_time` | `String` | As Easypaisa sends, `dd/MM/yyyy hh:mm a` |
+| `payment_token_expiry` | `String?` | OTC only |
+| `msisdn` | `String?` |  |
+| `payment_mode` | `String` | `"MA"` / `"OTC"` / `"CC"` |
+| `response_code` / `response_message` | `String` |  |
+| `raw` | `Hash` | Full provider response |
+
+Predicates: `successful_lookup?`, `paid?`, `failed?`, `pending?`, `expired?`, `blocked?`, `reversed?`.
+
+## Errors
+
+All errors inherit from `PaygatePk::Error`:
+
+| Class | Raised when |
+|---|---|
+| `ConfigurationError` | Required config is missing (e.g. `merchant_id`) |
+| `ValidationError` | A required method argument is missing or blank (see `#details[:missing]`) |
+| `HTTPError` | Non-2xx response from the gateway (carries `#status`, `#body`) |
+| `TimeoutError` | Network timeout (subclass of `HTTPError`) |
+| `ConnectionError` | DNS / SSL / refused connection (subclass of `HTTPError`) |
+| `AuthError` | Token endpoint returned 2xx but the body had no `ACCESS_TOKEN` |
+| `SignatureError` | Callback `validation_hash` mismatch or required field missing |
+| `CapabilityNotSupported` | Provider asked for a flow it doesn't implement (1.1+) |
+| `ProviderError` | Provider business-rule failure (carries `#code`, `#response`) |
+
+## Non-Rails apps
+
+The view helper is the only Rails-specific piece — and it's autoloaded only if `Rails::Railtie` is present. Everything else works in plain Ruby / Sinatra / Hanami:
 
-- PaygatePk::ConfigurationError — missing/invalid configuration (e.g., merchant_id, secured_key, or base_url).
-- PaygatePk::ValidationError — missing required method arguments or required form fields.
-- PaygatePk::HTTPError — network/HTTP failure (wraps response status & body).
-- PaygatePk::AuthError — auth call succeeded at HTTP level but token missing/invalid in body.
-- PaygatePk::SignatureError — reserved for webhook/IPN verification (upcoming).
-- PaygatePk::ProviderError — reserved for provider business-rule failures.
+```ruby
+redirect = PaygatePk::PayFast::Redirect.build(...)
+# Render redirect.fields as <input type="hidden"> in your own template.
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+bin/setup
+bundle exec rake test            # 76 examples, 200 assertions, 0 failures
+bundle exec rubocop
+```
+
+## Roadmap
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- **1.0** ✅ — PayFast hosted-checkout + callback verification.
+- **1.1** ✅ — Easypaisa: Mobile Account, OTC voucher, Inquiry. `paygate_pk_otc_voucher` Rails helper. `c.easy_paisa.*` config block.
+- **1.2** — Easypaisa IPN (`EasyPaisa::Callback.verify!`). PayFast tokenization: bearer-token auth (`/api/token`), saved instruments (`/api/user/instruments`), charge-against-saved-instrument.
+- **1.x+** — Additional Pakistani gateways (JazzCash, HBL, SafePay) under the same `Contracts::RedirectRequest` / `ChargeResult` / `CallbackEvent` shapes so host code stays unchanged.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/paygate_pk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/paygate_pk/blob/master/CODE_OF_CONDUCT.md).
+Issues and PRs at <https://github.com/qbitechs/paygate_pk>.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the PaygatePk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/paygate_pk/blob/master/CODE_OF_CONDUCT.md).
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/paygate_pk/coercions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "date"
+
+module PaygatePk
+  # Small set of input normalisers shared across providers.
+  # All methods are pure and side-effect-free.
+  module Coercions
+    module_function
+
+    DATE_ISO            = "%Y-%m-%d"
+    EASYPAISA_TIMESTAMP = "%Y%m%d %H%M%S"
+
+    # Returns "YYYY-MM-DD" (PayFast's ORDER_DATE format) for Date/Time/DateTime
+    # or a String already in that shape. nil-tolerant.
+    def to_iso_date(value)
+      return nil if value.nil?
+      return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+      case value
+      when Date, Time, DateTime then value.strftime(DATE_ISO)
+      when String               then Date.parse(value).strftime(DATE_ISO)
+      else
+        raise ArgumentError, "cannot coerce #{value.inspect} to ISO date"
+      end
+    end
+
+    # Render a numeric amount as a non-scientific decimal String. PayFast
+    # accepts TXNAMT as a string; 1500 → "1500", 1500.5 → "1500.5".
+    def to_amount_string(value)
+      return nil if value.nil?
+
+      case value
+      when Float, Rational, BigDecimal then format("%g", value)
+      else value.to_s
+      end
+    end
+
+    # Returns "yyyymmdd HHmmss" -- Easypaisa's tokenExpiry format
+    # (per the REST without RSA Integration Guide, Initiate OTC
+    # Transaction request parameters). Accepts Date/Time/DateTime or a
+    # String already in the right shape. nil-tolerant.
+    def to_easypaisa_timestamp(value)
+      return nil if value.nil?
+      return value if value.is_a?(String) && value.match?(/\A\d{8} \d{6}\z/)
+
+      case value
+      when Time, DateTime then value.strftime(EASYPAISA_TIMESTAMP)
+      when Date           then value.to_time.strftime(EASYPAISA_TIMESTAMP)
+      when String         then DateTime.parse(value).strftime(EASYPAISA_TIMESTAMP)
+      else
+        raise ArgumentError, "cannot coerce #{value.inspect} to Easypaisa timestamp"
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+  end
+end

data/lib/paygate_pk/config.rb

@@ -1,45 +1,133 @@
 # 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.easy_paisa.environment = Rails.env.production? ? :production : :sandbox
+  #     c.easy_paisa.username    = ENV["EASYPAISA_USERNAME"]
+  #     c.easy_paisa.password    = ENV["EASYPAISA_PASSWORD"]
+  #     c.easy_paisa.store_id    = ENV["EASYPAISA_STORE_ID"]
+  #     c.easy_paisa.account_num = ENV["EASYPAISA_ACCOUNT"]
+  #   end
+  #
+  # After `configure`, the config object is frozen — mutating it raises.
   class Config
-    attr_accessor :logger, :default_currency, :timeouts, :retry, :user_agent
-    attr_reader   :pay_fast
+    attr_accessor :default_currency, :timeouts, :retry, :user_agent, :logger
+    attr_reader   :pay_fast, :easy_paisa
 
     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
+      @easy_paisa       = EasyPaisaConfig.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
+      @easy_paisa.freeze
+      freeze
       self
     end
 
-    def frozen?
-      @frozen
+    def configured?
+      @configured
+    end
+
+    # 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
+        @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
 
-    # 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 Easypaisa (REST without RSA).
+    #
+    # Required for any call: username + password + store_id. account_num
+    # is required for Inquiry only (it's the merchant's EWP Account #
+    # found on the Profile page of the Easypaisa Merchant Portal).
+    class EasyPaisaConfig
+      ENVIRONMENTS = %i[sandbox production].freeze
+
+      attr_accessor :username, :password, :store_id, :account_num, :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
+        @username    = nil
+        @password    = nil
+        @store_id    = nil
+        @account_num = nil
+        @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
+
+      def resolved_base_url
+        return base_url if base_url
+
+        PaygatePk::EasyPaisa::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