przelewy24_payment 0.2.0 → 2.0.0

data/lib/przelewy24_payment/api/payment_methods.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    class PaymentMethods < Base
+      def list(lang: config.default_language)
+        client.get("payment/methods/#{lang}").fetch("data")
+      end
+    end
+  end
+end

data/lib/przelewy24_payment/api/refunds.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    class Refunds < Base
+      # Refunds part or all of a verified transaction. Amount is in minor units.
+      def create(request_id:, order_id:, session_id:, amount:, url_status:, description: nil)
+        refunds_uuid = SecureRandom.uuid
+        body = {
+          requestId: request_id,
+          refunds: [ { orderId: order_id, sessionId: session_id, amount: amount, description: description }.compact ],
+          refundsUuid: refunds_uuid,
+          urlStatus: url_status
+        }
+
+        data = client.post("transaction/refund", body).fetch("data")
+        { "refundsUuid" => refunds_uuid, "refunds" => data }
+      end
+
+      def find(order_id)
+        client.get("refund/by/orderId/#{Integer(order_id)}").fetch("data")
+      end
+    end
+  end
+end

data/lib/przelewy24_payment/api/transactions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    class Transactions < Base
+      # Registers a transaction and returns its token. Amount is in minor units.
+      # Extra keyword arguments are sent as-is in camelCase, e.g. method_ref_id:,
+      # method:, additional: { PSU: { IP:, userAgent: } }, transfer_label:,
+      # url_card_payment_notification:, time_limit:, wait_for_result:.
+      def register(session_id:, amount:, currency:, description:, email:, url_return:, url_status:, **extra)
+        body = {
+          merchantId: config.merchant_id,
+          posId: config.pos_id,
+          sessionId: session_id,
+          amount: amount,
+          currency: currency,
+          description: description,
+          email: email,
+          country: config.default_country,
+          language: config.default_language,
+          urlReturn: url_return,
+          urlStatus: url_status,
+          sign: Signature.register(session_id: session_id, merchant_id: config.merchant_id,
+                                   amount: amount, currency: currency, crc: config.crc_key)
+        }.merge(extra.transform_keys { |key| key.to_s.camelize(:lower).to_sym })
+
+        client.post("transaction/register", body).fetch("data").fetch("token")
+      end
+
+      # Confirms a transaction after a status notification. Required for settlement.
+      def verify(session_id:, order_id:, amount:, currency:)
+        body = {
+          merchantId: config.merchant_id,
+          posId: config.pos_id,
+          sessionId: session_id,
+          amount: amount,
+          currency: currency,
+          orderId: order_id,
+          sign: Signature.verify(session_id: session_id, order_id: order_id, amount: amount,
+                                 currency: currency, crc: config.crc_key)
+        }
+
+        client.put("transaction/verify", body).dig("data", "status") == "success"
+      end
+
+      def find_by_session_id(session_id)
+        client.get("transaction/by/sessionId/#{ERB::Util.url_encode(session_id)}").fetch("data")
+      end
+    end
+  end
+end

data/lib/przelewy24_payment/client.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Przelewy24Payment
+  class Client
+    attr_reader :configuration
+
+    def initialize(configuration = Przelewy24Payment.configuration)
+      @configuration = configuration
+    end
+
+    def test_access
+      get("testAccess").dig("data") == true
+    end
+
+    def transactions = @transactions ||= Api::Transactions.new(self)
+    def refunds = @refunds ||= Api::Refunds.new(self)
+    def payment_methods = @payment_methods ||= Api::PaymentMethods.new(self)
+    def blik = @blik ||= Api::Blik.new(self)
+    def cards = @cards ||= Api::Cards.new(self)
+
+    def get(path, params = nil) = request(:get, path, params)
+    def post(path, body) = request(:post, path, body)
+    def put(path, body) = request(:put, path, body)
+
+    private
+
+    def request(verb, path, payload)
+      configuration.validate!
+      response = Instrumentation.instrument("request", verb: verb, path: path) do
+        connection.public_send(verb, path, payload)
+      end
+      handle(response)
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise ConnectionError, "#{e.class}: #{e.message}"
+    end
+
+    def handle(response)
+      return response.body || {} if response.success?
+
+      body = response.body
+      message = body.is_a?(Hash) ? body["error"] : nil
+      message = message["message"] if message.is_a?(Hash)
+      error_class = case response.status
+      when 400, 422 then ValidationError
+      when 401, 403 then AuthenticationError
+      when 404 then NotFoundError
+      when 409 then ConflictError
+      when 500.. then ServerError
+      else ApiError
+      end
+      raise error_class.new(message ? "Przelewy24: #{message}" : nil, status: response.status, body: body)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: "#{configuration.api_url}/") do |conn|
+        conn.request :authorization, :basic, configuration.pos_id.to_s, configuration.api_key
+        conn.request :json
+        conn.response :json, content_type: /\bjson/
+        conn.options.open_timeout = configuration.open_timeout
+        conn.options.timeout = configuration.timeout
+      end
+    end
+  end
+end

data/lib/przelewy24_payment/configuration.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  class Configuration
+    HOSTS = {
+      sandbox: "https://sandbox.przelewy24.pl",
+      production: "https://secure.przelewy24.pl"
+    }.freeze
+
+    ENV_KEYS = {
+      merchant_id: "PRZELEWY24_MERCHANT_ID",
+      pos_id: "PRZELEWY24_POS_ID",
+      api_key: "PRZELEWY24_API_KEY",
+      crc_key: "PRZELEWY24_CRC_KEY"
+    }.freeze
+
+    attr_writer :merchant_id, :pos_id, :api_key, :crc_key
+    attr_accessor :default_country, :default_language, :url_options,
+                  :open_timeout, :timeout, :logger, :allowed_ips,
+                  :on_payment_verified, :on_payment_failed, :on_refund,
+                  :max_failed_attempts, :retry_interval, :parent_controller
+    attr_reader :environment
+
+    def initialize
+      self.environment = ENV.fetch("PRZELEWY24_ENVIRONMENT", "sandbox")
+      @default_country = "PL"
+      @default_language = "pl"
+      @url_options = {}
+      @open_timeout = 5
+      @timeout = 15
+      @allowed_ips = nil
+      @parent_controller = "ActionController::API"
+      @max_failed_attempts = 3
+      @retry_interval = 1.day
+    end
+
+    def environment=(value)
+      value = value.to_s.to_sym
+      unless HOSTS.key?(value)
+        raise ConfigurationError, "environment must be one of #{HOSTS.keys.inspect}, got #{value.inspect}"
+      end
+
+      @environment = value
+    end
+
+    def sandbox? = environment == :sandbox
+    def production? = environment == :production
+
+    def merchant_id = Integer(fetch!(:merchant_id))
+    def pos_id = Integer(value_for(:pos_id).presence || fetch!(:merchant_id))
+    def api_key = fetch!(:api_key).to_s
+    def crc_key = fetch!(:crc_key).to_s
+
+    def host = HOSTS.fetch(environment)
+    def api_url = "#{host}/api/v1"
+    def gateway_url(token) = "#{host}/trnRequest/#{token}"
+
+    def logger = @logger || (defined?(::Rails) ? ::Rails.logger : nil)
+
+    # Raises ConfigurationError naming every missing credential at once.
+    # Called lazily on first use, so asset precompilation and generators
+    # work without credentials.
+    def validate!
+      missing = ENV_KEYS.keys.reject { |key| key == :pos_id || value_for(key).present? }
+      return self if missing.empty?
+
+      names = missing.map { |key| "#{key} (#{ENV_KEYS.fetch(key)})" }
+      raise ConfigurationError, "Przelewy24Payment is missing: #{names.join(', ')}"
+    end
+
+    private
+
+    def fetch!(key)
+      value_for(key).presence || validate!.then { value_for(key) }
+    end
+
+    def value_for(key)
+      instance_variable_get("@#{key}").presence || ENV[ENV_KEYS.fetch(key)].presence
+    end
+  end
+end

data/lib/przelewy24_payment/engine.rb

@@ -1,4 +1,15 @@
+# frozen_string_literal: true
+
 module Przelewy24Payment
-  class Engine < Rails::Engine
+  class Engine < ::Rails::Engine
+    isolate_namespace Przelewy24Payment
+
+    initializer "przelewy24_payment.filter_parameters" do |app|
+      app.config.filter_parameters += %i[sign crc crc_key api_key]
+    end
+
+    generators do
+      require "generators/przelewy24_payment/install/install_generator"
+    end
   end
 end

data/lib/przelewy24_payment/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  class Error < StandardError; end
+
+  # Raised when a required setting is missing or invalid.
+  class ConfigurationError < Error; end
+
+  # Raised for transport-level failures (timeouts, DNS, TLS).
+  class ConnectionError < Error; end
+
+  # Raised when starting a payment for something that is already paid.
+  class AlreadyPaidError < Error; end
+
+  # Raised when a webhook signature does not match.
+  class SignatureError < Error; end
+
+  # Raised when a webhook payload lacks required fields.
+  class InvalidNotificationError < Error; end
+
+  # Raised when Przelewy24 answers with an error status.
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "Przelewy24 API error (HTTP #{status})")
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class ValidationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ServerError < ApiError; end
+
+  class ConflictError < ApiError; end
+
+  # BLIK chargeByAlias answered 409: the alias is linked to several bank apps.
+  class AmbiguousAliasError < ConflictError
+    def alternative_keys
+      Array(body.is_a?(Hash) ? body.dig("error", "alternativeKeys") : nil)
+    end
+  end
+end

data/lib/przelewy24_payment/instrumentation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module Przelewy24Payment
+  # Events are published as "<name>.przelewy24", e.g. "request.przelewy24".
+  module Instrumentation
+    NAMESPACE = "przelewy24"
+
+    module_function
+
+    def instrument(name, payload = {}, &block)
+      ActiveSupport::Notifications.instrument("#{name}.#{NAMESPACE}", payload, &block)
+    end
+  end
+end

data/lib/przelewy24_payment/money.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Przelewy24Payment
+  # Converts between decimal amounts and the integer minor units
+  # (grosze, cents) that Przelewy24 expects.
+  module Money
+    module_function
+
+    def to_minor(amount)
+      case amount
+      when Integer then amount * 100
+      when BigDecimal then (amount * 100).round(0, :half_up).to_i
+      when String, Rational then (BigDecimal(amount.to_s) * 100).round(0, :half_up).to_i
+      when Float then (BigDecimal(amount.to_s) * 100).round(0, :half_up).to_i
+      else
+        raise ArgumentError, "unsupported amount: #{amount.inspect}"
+      end
+    end
+
+    def from_minor(minor)
+      BigDecimal(Integer(minor)) / 100
+    end
+  end
+end

data/lib/przelewy24_payment/notification.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # A signed transaction status notification sent by Przelewy24 to urlStatus.
+  class Notification
+    REQUIRED = %w[merchantId posId sessionId amount currency orderId sign].freeze
+
+    attr_reader :attributes
+
+    def initialize(attributes, configuration: Przelewy24Payment.configuration)
+      @attributes = attributes.to_h.transform_keys(&:to_s)
+      @configuration = configuration
+    end
+
+    def self.from_json(raw, **options)
+      new(JSON.parse(raw), **options)
+    rescue JSON::ParserError => e
+      raise InvalidNotificationError, "malformed JSON: #{e.message}"
+    end
+
+    def session_id = attributes["sessionId"].to_s
+    def order_id = Integer(attributes["orderId"])
+    def amount = Integer(attributes["amount"])
+    def currency = attributes["currency"].to_s
+    def method_id = attributes["methodId"]&.then { |value| Integer(value) }
+    def statement = attributes["statement"]
+
+    def complete?
+      REQUIRED.all? { |key| attributes[key].to_s != "" }
+    end
+
+    def valid?
+      complete? &&
+        Integer(attributes["merchantId"]) == configuration.merchant_id &&
+        Signature.secure_compare?(expected_sign, attributes["sign"])
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def verify!
+      raise InvalidNotificationError, "missing required fields" unless complete?
+      raise SignatureError, "invalid notification signature" unless valid?
+
+      self
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def expected_sign
+      Signature.notification(attributes, crc: configuration.crc_key)
+    end
+  end
+end

data/lib/przelewy24_payment/payable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # Include in any model that can be paid for (Order, Invoice, ...).
+  module Payable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :przelewy24_payments, as: :payable, class_name: "Przelewy24Payment::Payment", dependent: :restrict_with_exception
+    end
+
+    def przelewy24_paid?
+      przelewy24_payments.verified.exists?
+    end
+
+    def latest_przelewy24_payment
+      przelewy24_payments.order(:id).last
+    end
+  end
+end

data/lib/przelewy24_payment/refund_notification.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # A signed refund status notification. Status 0 means the refund was
+  # completed, 1 means it was rejected.
+  class RefundNotification
+    REQUIRED = %w[orderId sessionId refundsUuid merchantId amount currency status sign].freeze
+
+    attr_reader :attributes
+
+    def initialize(attributes, configuration: Przelewy24Payment.configuration)
+      @attributes = attributes.to_h.transform_keys(&:to_s)
+      @configuration = configuration
+    end
+
+    def refunds_uuid = attributes["refundsUuid"].to_s
+    def session_id = attributes["sessionId"].to_s
+    def order_id = Integer(attributes["orderId"])
+    def amount = Integer(attributes["amount"])
+    def success? = Integer(attributes["status"]).zero?
+
+    def complete?
+      REQUIRED.all? { |key| attributes[key].to_s != "" }
+    end
+
+    def valid?
+      complete? &&
+        Signature.secure_compare?(Signature.refund_notification(attributes, crc: configuration.crc_key), attributes["sign"])
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def verify!
+      raise InvalidNotificationError, "missing required fields" unless complete?
+      raise SignatureError, "invalid refund notification signature" unless valid?
+
+      self
+    end
+
+    private
+
+    attr_reader :configuration
+  end
+end

data/lib/przelewy24_payment/signature.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Przelewy24Payment
+  # Przelewy24 signs the compact JSON of an ordered hash with SHA-384.
+  # Key order is part of the contract, so every endpoint has its own builder.
+  module Signature
+    module_function
+
+    def register(session_id:, merchant_id:, amount:, currency:, crc:)
+      sign("sessionId" => session_id.to_s, "merchantId" => Integer(merchant_id),
+           "amount" => Integer(amount), "currency" => currency.to_s, "crc" => crc.to_s)
+    end
+
+    def verify(session_id:, order_id:, amount:, currency:, crc:)
+      sign("sessionId" => session_id.to_s, "orderId" => Integer(order_id),
+           "amount" => Integer(amount), "currency" => currency.to_s, "crc" => crc.to_s)
+    end
+
+    # Optional fields are signed only when Przelewy24 sends them, in the
+    # order below.
+    def notification(attrs, crc:)
+      fields = {}
+      fields["merchantId"] = Integer(attrs.fetch("merchantId"))
+      fields["posId"] = Integer(attrs.fetch("posId"))
+      fields["sessionId"] = attrs.fetch("sessionId").to_s
+      fields["amount"] = Integer(attrs.fetch("amount"))
+      fields["originAmount"] = Integer(attrs["originAmount"]) if present?(attrs["originAmount"])
+      fields["currency"] = attrs.fetch("currency").to_s
+      fields["orderId"] = Integer(attrs.fetch("orderId"))
+      fields["methodId"] = Integer(attrs["methodId"]) if present?(attrs["methodId"])
+      fields["statement"] = attrs["statement"].to_s if present?(attrs["statement"])
+      fields["crc"] = crc.to_s
+      sign(fields)
+    end
+
+    def refund_notification(attrs, crc:)
+      sign("orderId" => Integer(attrs.fetch("orderId")),
+           "sessionId" => attrs.fetch("sessionId").to_s,
+           "refundsUuid" => attrs.fetch("refundsUuid").to_s,
+           "merchantId" => Integer(attrs.fetch("merchantId")),
+           "amount" => Integer(attrs.fetch("amount")),
+           "currency" => attrs.fetch("currency").to_s,
+           "status" => Integer(attrs.fetch("status")),
+           "crc" => crc.to_s)
+    end
+
+    def sign(fields)
+      Digest::SHA384.hexdigest(JSON.generate(fields))
+    end
+
+    def present?(value)
+      !value.nil? && value.to_s != ""
+    end
+
+    def secure_compare?(expected, actual)
+      return false unless actual.is_a?(String) && actual.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, actual)
+    end
+  end
+end

data/lib/przelewy24_payment/test_helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # Builds signed webhook payloads for host-app specs.
+  #   post przelewy24_payment.status_webhooks_path,
+  #        params: Przelewy24Payment::TestHelpers.status_payload(payment), as: :json
+  module TestHelpers
+    module_function
+
+    def status_payload(payment, order_id: 123_456, method_id: 25, configuration: Przelewy24Payment.configuration)
+      attrs = {
+        "merchantId" => configuration.merchant_id, "posId" => configuration.pos_id,
+        "sessionId" => payment.session_id, "amount" => payment.amount,
+        "originAmount" => payment.amount, "currency" => payment.currency,
+        "orderId" => order_id, "methodId" => method_id, "statement" => "p24-#{order_id}"
+      }
+      attrs.merge("sign" => Signature.notification(attrs, crc: configuration.crc_key))
+    end
+  end
+end

data/lib/przelewy24_payment/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Przelewy24Payment
-  VERSION = "0.2.0"
+  VERSION = "2.0.0"
 end