paygate_pk 0.2.3 → 1.1.0

data/lib/paygate_pk/contracts/callback_event.rb

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

data/lib/paygate_pk/contracts/charge_result.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Returned by every "create a charge / take a payment" call against a
+    # REST-style provider (Easypaisa MA + OTC in 1.1; future providers
+    # to follow). Universal shape so host apps can branch on
+    # payment_mode rather than provider-specific response classes.
+    #
+    # OTC fills payment_token and expires_at (the customer takes that
+    # token to an Easypaisa shop). MA fills transaction_id (the
+    # gateway's Ericsson EWP id) and leaves payment_token nil.
+    #
+    # response_code/response_message are the upstream provider's raw
+    # status code and human-readable reason. Compare against
+    # success_code for the success predicate -- Easypaisa says "0000",
+    # but other providers may say "000" or "OK".
+    ChargeResult = Struct.new(
+      :provider,            # Symbol e.g. :easy_paisa
+      :basket_id,           # String -- the merchant's reference (Easypaisa orderId)
+      :transaction_id,      # String or nil (Easypaisa Ericsson EWP id for MA)
+      :payment_token,       # String or nil (OTC only)
+      :payment_mode,        # Symbol :mobile_account | :otc
+      :expires_at,          # Time or nil (OTC only)
+      :transacted_at,       # Time or nil
+      :amount,              # String -- echo of input amount
+      :currency,            # String
+      :customer,            # Hash echo of customer info actually sent
+      :response_code,       # String e.g. "0000"
+      :response_message,    # String e.g. "SUCCESS"
+      :success_code,        # String -- provider's success literal
+      :raw,                 # Hash -- full provider response
+      keyword_init: true
+    ) do
+      def success?
+        response_code == success_code
+      end
+
+      def failed?
+        !success?
+      end
+
+      def otc?
+        payment_mode == :otc
+      end
+
+      def mobile_account?
+        payment_mode == :mobile_account
+      end
+    end
+  end
+end

data/lib/paygate_pk/contracts/inquiry_result.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module Contracts
+    # Returned by status-inquiry calls (Easypaisa Inquire Transaction in
+    # 1.1; future providers to follow). Captures the canonical
+    # transaction status alongside everything the upstream API hands
+    # back so the host app can rebuild its mental model of the
+    # transaction without making additional calls.
+    InquiryResult = Struct.new(
+      :provider,                  # Symbol :easy_paisa
+      :basket_id,                 # String  Easypaisa orderId
+      :account_num,               # String  Merchant EWP account number
+      :store_id,                  # String
+      :store_name,                # String
+      :payment_token,             # String or nil  OTC only
+      :transaction_status,        # String  "PAID" | "FAILED" | "PENDING" | "BLOCKED" | "EXPIRED" | "REVERSED"
+      :transaction_amount,        # String
+      :transaction_date_time,     # String  "dd/MM/yyyy hh:mm a" as Easypaisa sends
+      :payment_token_expiry,      # String or nil  OTC only
+      :msisdn,                    # String
+      :payment_mode,              # String  "MA" | "OTC" | "CC"
+      :response_code,             # String  "0000" on a successful lookup
+      :response_message,          # String
+      :success_code,              # String  provider's success literal
+      :raw,                       # Hash    full provider response
+      keyword_init: true
+    ) do
+      def successful_lookup?
+        response_code == success_code
+      end
+
+      def paid?
+        transaction_status == "PAID"
+      end
+
+      def failed?
+        transaction_status == "FAILED"
+      end
+
+      def pending?
+        transaction_status == "PENDING"
+      end
+
+      def expired?
+        transaction_status == "EXPIRED"
+      end
+
+      def blocked?
+        transaction_status == "BLOCKED"
+      end
+
+      def reversed?
+        transaction_status == "REVERSED"
+      end
+    end
+  end
+end

data/lib/paygate_pk/contracts/redirect_request.rb

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

data/lib/paygate_pk/easy_paisa/client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module EasyPaisa
+    # Internal shared HTTP wrapper for the three Easypaisa REST endpoints.
+    # Not advertised on the public surface; MobileAccount / OTC /
+    # Inquiry instantiate it directly and consume the parsed response.
+    #
+    # Responsibilities:
+    # - Validate provider config (username + password + store_id) before
+    #   touching the network; raises ConfigurationError with a list of
+    #   missing keys.
+    # - Build the Credentials header (Base64Strict("user:pass")).
+    # - POST a JSON body, returning the decoded Hash.
+    # - Convert any non-Hash response (Easypaisa always returns JSON, so
+    #   this is defensive) into a ProviderError with the raw body
+    #   attached.
+    class Client
+      SUCCESS_CODE = "0000"
+
+      def initialize(config: PaygatePk::EasyPaisa.config, http: nil)
+        @config = config
+        @http   = http
+      end
+
+      # POSTs json to the given path. Returns the decoded Hash. Does NOT
+      # interpret responseCode -- the caller decides whether non-0000
+      # warrants raising vs. surfacing as a result with success? == false.
+      def post(path, json:)
+        ensure_config!
+        http.post(path, json: json, headers: auth_headers)
+      end
+
+      def success_code
+        SUCCESS_CODE
+      end
+
+      private
+
+      def http
+        @http ||= PaygatePk::HTTP::Client.new(
+          base_url: @config.resolved_base_url,
+          headers: { "Accept" => "application/json" }
+        )
+      end
+
+      def auth_headers
+        {
+          "Credentials" => PaygatePk::Util::Credentials.basic(@config.username, @config.password)
+        }
+      end
+
+      def ensure_config!
+        missing = []
+        missing << :username if Coercions.blank?(@config.username)
+        missing << :password if Coercions.blank?(@config.password)
+        missing << :store_id if Coercions.blank?(@config.store_id)
+        return if missing.empty?
+
+        raise PaygatePk::ConfigurationError, "Easypaisa config missing: #{missing.join(", ")}"
+      end
+    end
+  end
+end

data/lib/paygate_pk/easy_paisa/endpoints.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module EasyPaisa
+    # Centralised URL map for Easypaisa REST endpoints. Picks between
+    # sandbox and production based on EasyPaisaConfig#environment;
+    # callers never hand-type hostnames.
+    #
+    # The path constants encode the three documented endpoints from the
+    # vendor's "REST APIs without RSA Integration Guide".
+    module Endpoints
+      URLS = {
+        sandbox: "https://easypaystg.easypaisa.com.pk",
+        # Easypaisa has not published an official production base URL in
+        # the public REST guide; merchants typically receive it on
+        # go-live. Configure via `c.easy_paisa.base_url = "..."` until
+        # then.
+        production: "https://easypay.easypaisa.com.pk"
+      }.freeze
+
+      INITIATE_MA_PATH  = "/easypay-service/rest/v4/initiate-ma-transaction"
+      INITIATE_OTC_PATH = "/easypay-service/rest/v4/initiate-otc-transaction"
+      INQUIRE_PATH      = "/easypay-service/rest/v4/inquire-transaction"
+
+      module_function
+
+      def base_url(env)
+        URLS.fetch(env) do
+          raise PaygatePk::ConfigurationError, "unknown Easypaisa environment: #{env.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/paygate_pk/easy_paisa/inquiry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module EasyPaisa
+    # Inquire Transaction Status — given an orderId we previously
+    # submitted (and the merchant EWP account number), Easypaisa
+    # returns the current state. Use this to drive your own state
+    # machine for OTC payments (where success arrives asynchronously
+    # when the customer pays at a shop) or as a poor-man's IPN
+    # replacement until the IPN spec is wired.
+    #
+    # POST {base}/easypay-service/rest/v4/inquire-transaction
+    #
+    # Usage:
+    #
+    #   status = PaygatePk::EasyPaisa::Inquiry.fetch(
+    #     order_id:    "lawzo-#{payment.id}",
+    #     account_num: PaygatePk.config.easy_paisa.account_num
+    #   )
+    #   status.paid?     # transactionStatus == "PAID"
+    #   status.pending?  # transactionStatus == "PENDING"
+    class Inquiry
+      def self.fetch(**kwargs)
+        new.fetch(**kwargs)
+      end
+
+      def initialize(config: PaygatePk::EasyPaisa.config, client: nil)
+        @config = config
+        @client = client
+      end
+
+      def fetch(order_id:, account_num: nil)
+        account_num ||= @config.account_num
+        ensure_args!(order_id: order_id, account_num: account_num)
+
+        body = {
+          "orderId" => order_id.to_s,
+          "storeId" => @config.store_id.to_s,
+          "accountNum" => account_num.to_s
+        }
+
+        resp = client.post(Endpoints::INQUIRE_PATH, json: body)
+        build_result(order_id, account_num, resp)
+      end
+
+      private
+
+      def client
+        @client ||= Client.new(config: @config)
+      end
+
+      def ensure_args!(order_id:, account_num:)
+        missing = []
+        missing << :order_id    if Coercions.blank?(order_id)
+        missing << :account_num if Coercions.blank?(account_num)
+        return if missing.empty?
+
+        raise PaygatePk::ValidationError.new(
+          "missing required args: #{missing.join(", ")}",
+          details: { missing: missing }
+        )
+      end
+
+      def build_result(order_id, account_num, resp)
+        resp = {} unless resp.is_a?(Hash)
+        Contracts::InquiryResult.new(
+          provider: :easy_paisa,
+          basket_id: order_id.to_s,
+          account_num: account_num.to_s,
+          store_id: resp["storeId"]&.to_s,
+          store_name: resp["storeName"],
+          payment_token: resp["paymentToken"],
+          transaction_status: resp["transactionStatus"],
+          transaction_amount: resp["transactionAmount"]&.to_s,
+          transaction_date_time: resp["transactionDateTime"],
+          payment_token_expiry: resp["paymentTokenExpiryDateTime"],
+          msisdn: resp["msisdn"],
+          payment_mode: resp["paymentMode"],
+          response_code: resp["responseCode"],
+          response_message: resp["responseDesc"],
+          success_code: client.success_code,
+          raw: resp
+        )
+      end
+    end
+  end
+end

data/lib/paygate_pk/easy_paisa/mobile_account.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module EasyPaisa
+    # Initiate MA Transaction — pushes an OTP confirmation to the
+    # customer's Easypaisa wallet so they can authorise payment without
+    # leaving the merchant site.
+    #
+    # POST {base}/easypay-service/rest/v4/initiate-ma-transaction
+    #
+    # Usage:
+    #
+    #   result = PaygatePk::EasyPaisa::MobileAccount.charge(
+    #     order_id:          "lawzo-#{payment.id}",
+    #     amount:            1500,
+    #     mobile_account_no: "03001234567",
+    #     email:             "client@example.com"
+    #   )
+    #   result.success?       # => true if responseCode == "0000"
+    #   result.transaction_id # => Ericsson EWP ID (string)
+    class MobileAccount
+      TRANSACTION_TYPE = "MA"
+
+      def self.charge(**kwargs)
+        new.charge(**kwargs)
+      end
+
+      def initialize(config: PaygatePk::EasyPaisa.config, client: nil)
+        @config = config
+        @client = client
+      end
+
+      def charge(order_id:, amount:, mobile_account_no:, email:, optional: {})
+        ensure_args!(order_id: order_id, amount: amount,
+                     mobile_account_no: mobile_account_no, email: email)
+
+        body = build_body(order_id: order_id, amount: amount,
+                          mobile_account_no: mobile_account_no, email: email,
+                          optional: optional)
+
+        resp = client.post(Endpoints::INITIATE_MA_PATH, json: body)
+        build_result(order_id: order_id, amount: amount,
+                     mobile_account_no: mobile_account_no, email: email,
+                     resp: resp)
+      end
+
+      private
+
+      def client
+        @client ||= Client.new(config: @config)
+      end
+
+      def ensure_args!(order_id:, amount:, mobile_account_no:, email:)
+        missing = []
+        missing << :order_id          if Coercions.blank?(order_id)
+        missing << :amount            if amount.nil?
+        missing << :mobile_account_no if Coercions.blank?(mobile_account_no)
+        missing << :email             if Coercions.blank?(email)
+        return if missing.empty?
+
+        raise PaygatePk::ValidationError.new(
+          "missing required args: #{missing.join(", ")}",
+          details: { missing: missing }
+        )
+      end
+
+      def build_body(order_id:, amount:, mobile_account_no:, email:, optional:)
+        body = {
+          "orderId" => order_id.to_s,
+          "storeId" => @config.store_id.to_s,
+          "transactionAmount" => Coercions.to_amount_string(amount),
+          "transactionType" => TRANSACTION_TYPE,
+          "mobileAccountNo" => mobile_account_no.to_s,
+          "emailAddress" => email.to_s
+        }
+        add_optionals!(body, optional)
+        body
+      end
+
+      def add_optionals!(body, optional)
+        return unless optional.is_a?(Hash)
+
+        optional.each do |key, value|
+          next if Coercions.blank?(value)
+          next unless ("1".."5").cover?(key.to_s)
+
+          body["optional#{key}"] = value.to_s
+        end
+      end
+
+      def build_result(order_id:, amount:, mobile_account_no:, email:, resp:)
+        resp = {} unless resp.is_a?(Hash)
+        Contracts::ChargeResult.new(
+          provider: :easy_paisa,
+          basket_id: order_id.to_s,
+          transaction_id: resp["transactionId"],
+          payment_token: nil,
+          payment_mode: :mobile_account,
+          expires_at: nil,
+          transacted_at: parse_easypaisa_time(resp["transactionDateTime"]),
+          amount: Coercions.to_amount_string(amount),
+          currency: PaygatePk.config.default_currency,
+          customer: { mobile_account_no: mobile_account_no.to_s, email: email.to_s },
+          response_code: resp["responseCode"],
+          response_message: resp["responseDesc"],
+          success_code: client.success_code,
+          raw: resp
+        )
+      end
+
+      # Easypaisa hands back "dd/MM/yyyy hh:mm a" (e.g. "11/08/2018 11:30 PM").
+      # Best-effort parse -- returns the raw string if it's in some
+      # unexpected shape rather than blowing up the call site.
+      def parse_easypaisa_time(value)
+        return nil if Coercions.blank?(value)
+
+        DateTime.strptime(value, "%d/%m/%Y %I:%M %p").to_time
+      rescue ArgumentError, TypeError
+        value
+      end
+    end
+  end
+end

data/lib/paygate_pk/easy_paisa/otc.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  module EasyPaisa
+    # Initiate OTC Transaction — issues a paymentToken the customer
+    # takes to any Easypaisa shop and pays with cash. The merchant gets
+    # paid when Easypaisa reconciles the shop deposit (status moves to
+    # PAID; poll via Inquiry.fetch or rely on IPN once configured in
+    # the merchant portal).
+    #
+    # POST {base}/easypay-service/rest/v4/initiate-otc-transaction
+    #
+    # Usage:
+    #
+    #   voucher = PaygatePk::EasyPaisa::OTC.create(
+    #     order_id:     "lawzo-#{payment.id}",
+    #     amount:       1500,
+    #     msisdn:       "03001234567",
+    #     email:        "client@example.com",
+    #     token_expiry: 7.days.from_now
+    #   )
+    #   voucher.payment_token  # => "40933012" (show this to the customer)
+    #   voucher.expires_at     # => Time
+    class OTC
+      TRANSACTION_TYPE = "OTC"
+
+      def self.create(**kwargs)
+        new.create(**kwargs)
+      end
+
+      def initialize(config: PaygatePk::EasyPaisa.config, client: nil)
+        @config = config
+        @client = client
+      end
+
+      def create(order_id:, amount:, msisdn:, email:, token_expiry:, optional: {})
+        ensure_args!(order_id: order_id, amount: amount,
+                     msisdn: msisdn, email: email, token_expiry: token_expiry)
+
+        formatted_expiry = format_expiry(token_expiry)
+
+        body = build_body(order_id: order_id, amount: amount, msisdn: msisdn,
+                          email: email, token_expiry: formatted_expiry, optional: optional)
+
+        resp = client.post(Endpoints::INITIATE_OTC_PATH, json: body)
+        build_result(order_id: order_id, amount: amount, msisdn: msisdn,
+                     email: email, formatted_expiry: formatted_expiry, resp: resp)
+      end
+
+      private
+
+      def client
+        @client ||= Client.new(config: @config)
+      end
+
+      def ensure_args!(order_id:, amount:, msisdn:, email:, token_expiry:)
+        missing = []
+        missing << :order_id     if Coercions.blank?(order_id)
+        missing << :amount       if amount.nil?
+        missing << :msisdn       if Coercions.blank?(msisdn)
+        missing << :email        if Coercions.blank?(email)
+        missing << :token_expiry if Coercions.blank?(token_expiry)
+        return if missing.empty?
+
+        raise PaygatePk::ValidationError.new(
+          "missing required args: #{missing.join(", ")}",
+          details: { missing: missing }
+        )
+      end
+
+      def format_expiry(value)
+        formatted = Coercions.to_easypaisa_timestamp(value)
+        validate_future!(formatted)
+        formatted
+      end
+
+      # Easypaisa returns code "0016" when tokenExpiry is in the past.
+      # Surface that as a ValidationError up-front so the caller doesn't
+      # waste a round-trip.
+      def validate_future!(formatted)
+        # Parse back to compare; we trust to_easypaisa_timestamp's shape.
+        parsed = DateTime.strptime(formatted, Coercions::EASYPAISA_TIMESTAMP).to_time
+        return if parsed > Time.now
+
+        raise PaygatePk::ValidationError.new(
+          "token_expiry must be in the future (got #{formatted})",
+          details: { token_expiry: formatted }
+        )
+      end
+
+      def build_body(order_id:, amount:, msisdn:, email:, token_expiry:, optional:)
+        body = {
+          "orderId" => order_id.to_s,
+          "storeId" => @config.store_id.to_s,
+          "transactionAmount" => Coercions.to_amount_string(amount),
+          "transactionType" => TRANSACTION_TYPE,
+          "msisdn" => msisdn.to_s,
+          "emailAddress" => email.to_s,
+          "tokenExpiry" => token_expiry
+        }
+        add_optionals!(body, optional)
+        body
+      end
+
+      def add_optionals!(body, optional)
+        return unless optional.is_a?(Hash)
+
+        optional.each do |key, value|
+          next if Coercions.blank?(value)
+          next unless ("1".."5").cover?(key.to_s)
+
+          body["optional#{key}"] = value.to_s
+        end
+      end
+
+      def build_result(order_id:, amount:, msisdn:, email:, formatted_expiry:, resp:)
+        resp = {} unless resp.is_a?(Hash)
+        Contracts::ChargeResult.new(
+          provider: :easy_paisa,
+          basket_id: order_id.to_s,
+          transaction_id: nil,
+          payment_token: resp["paymentToken"],
+          payment_mode: :otc,
+          expires_at: parse_easypaisa_time(resp["paymentTokenExpiryDateTime"]) ||
+                             DateTime.strptime(formatted_expiry, Coercions::EASYPAISA_TIMESTAMP).to_time,
+          transacted_at: parse_easypaisa_time(resp["transactionDateTime"]),
+          amount: Coercions.to_amount_string(amount),
+          currency: PaygatePk.config.default_currency,
+          customer: { msisdn: msisdn.to_s, email: email.to_s },
+          response_code: resp["responseCode"],
+          response_message: resp["responseDesc"],
+          success_code: client.success_code,
+          raw: resp
+        )
+      end
+
+      def parse_easypaisa_time(value)
+        return nil if Coercions.blank?(value)
+
+        DateTime.strptime(value, "%d/%m/%Y %I:%M %p").to_time
+      rescue ArgumentError, TypeError
+        value
+      end
+    end
+  end
+end

data/lib/paygate_pk/easy_paisa.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PaygatePk
+  # Easypaisa integration (REST APIs without RSA encryption, per the
+  # vendor's "REST APIs without RSA Integration Guide").
+  #
+  # Public API (1.1):
+  #
+  #   PaygatePk::EasyPaisa::MobileAccount.charge(...)  # => Contracts::ChargeResult
+  #   PaygatePk::EasyPaisa::OTC.create(...)            # => Contracts::ChargeResult
+  #   PaygatePk::EasyPaisa::Inquiry.fetch(...)         # => Contracts::InquiryResult
+  #
+  # Callback (IPN) verification is deferred to 1.2 until Easypaisa
+  # publishes the full IPN wire spec; for now configure the IPN URL in
+  # the Easypaisa Merchant Portal and use Inquiry.fetch to poll status.
+  module EasyPaisa
+    def self.config
+      PaygatePk.config.easy_paisa
+    end
+  end
+end