paygate_pk 0.2.3 → 1.1.0

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

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