swoosh 0.2.0

data/lib/swoosh/certificates.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Swoosh
+  # Resolves and loads the certificates for one environment.
+  #
+  # Drop your bank-issued bundle into the configured directory named after the
+  # environment it belongs to:
+  #
+  #   config/certs/swish_production.p12
+  #   config/certs/swish_test.p12
+  #
+  # In :test we fall back to the Swish test certificates bundled with the gem,
+  # so a fresh app can talk to the Swish staging playground with no setup at
+  # all. :production never falls back -- a missing bundle there is an error.
+  class Certificates
+    BUNDLED_DIR = File.expand_path("../../certs", __dir__)
+    BUNDLED_TEST_CERT = File.join(BUNDLED_DIR, "Swish_Merchant_TestCertificate_1234679304.p12")
+    BUNDLED_ROOT_CA = File.join(BUNDLED_DIR, "Swish_TLS_RootCA.pem")
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def cert
+      @cert ||= OpenSSL::PKCS12.new(File.read(cert_path), @configuration.cert_password)
+    rescue OpenSSL::PKCS12::PKCS12Error => e
+      raise CertificateError, "Could not open #{cert_path} (wrong cert_password?): #{e.message}"
+    end
+
+    def root_ca
+      @root_ca ||= OpenSSL::X509::Certificate.new(File.read(root_ca_path))
+    end
+
+    # Net::HTTP builds its own SSL context internally rather than accepting one,
+    # so the pieces go onto the connection:
+    #
+    #   cert / key       the merchant certificate Swish authenticates us by
+    #   extra_chain_cert the Nordea intermediates that vouch for it, which Swish
+    #                    needs because it does not hold them itself
+    #   ca_file          the root we verify *Swish* by -- the other direction
+    #
+    # Both directions matter. Sending the merchant credential to whatever
+    # answers on the far end, unverified, would be worse than not sending it.
+    def configure_ssl(http)
+      http.use_ssl = true
+      http.cert = cert.certificate
+      http.key = cert.key
+      http.extra_chain_cert = cert.ca_certs
+      http.ca_file = root_ca_path
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http
+    end
+
+    # <cert_dir>/swish_test.p12 or <cert_dir>/swish_production.p12
+    def filename
+      "swish_#{@configuration.environment}.p12"
+    end
+
+    def cert_path
+      @cert_path ||= resolve_cert_path
+    end
+
+    def root_ca_path
+      @configuration.root_ca_path&.to_s || BUNDLED_ROOT_CA
+    end
+
+    private
+
+    def resolve_cert_path
+      configured = configured_cert_path
+
+      return configured if configured && File.exist?(configured)
+      return BUNDLED_TEST_CERT unless @configuration.production?
+
+      raise CertificateError, missing_certificate_message(configured)
+    end
+
+    def configured_cert_path
+      dir = @configuration.cert_dir
+      File.join(dir.to_s, filename) if dir
+    end
+
+    def missing_certificate_message(configured)
+      return "No Swish production certificate found: set `cert_dir` and place #{filename} in it." unless configured
+
+      "No Swish production certificate at #{configured}. Place your bank-issued bundle there, " \
+        "or point `cert_dir` somewhere else."
+    end
+  end
+end

data/lib/swoosh/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Swoosh
+  # Framework-agnostic configuration. The Rails railtie maps `config.swoosh.*`
+  # onto this; Sinatra/Hanami/plain Ruby can use `Swoosh.configure` directly.
+  class Configuration
+    # Swish calls the staging environment "MSS". We accept :staging as an alias
+    # so `config.swoosh.environment = :staging` reads naturally in an app.
+    ENVIRONMENTS = { test: :test, staging: :test, production: :production }.freeze
+
+    DEFAULT_CERT_PASSWORD = "swish"
+    DEFAULT_CURRENCY = "SEK"
+
+    # A payment request has to be accepted within three minutes, after which the
+    # token is worthless, so there is no reason to keep one longer.
+    DEFAULT_TOKEN_TTL = 300
+
+    attr_reader :environment
+    attr_accessor :cert_dir, :cert_password, :root_ca_path,
+                  :payee_alias, :callback_url, :currency,
+                  :token_store, :token_ttl
+
+    def initialize
+      @environment = :test
+      @cert_dir = nil
+      @cert_password = DEFAULT_CERT_PASSWORD
+      @root_ca_path = nil
+
+      # The merchant number is the same for a whole codebase, so it belongs in
+      # configuration. callback_url has no default on purpose: leave it unset
+      # and every call must name one, which is usually what you want.
+      @payee_alias = nil
+      @callback_url = nil
+      @currency = DEFAULT_CURRENCY
+
+      # Opt-in. The railtie points this at Rails.cache; nil just disables the
+      # lookup, it never breaks a payment.
+      @token_store = nil
+      @token_ttl = DEFAULT_TOKEN_TTL
+    end
+
+    def environment=(value)
+      key = value.to_s.downcase.to_sym
+      @environment = ENVIRONMENTS.fetch(key) do
+        raise ConfigurationError,
+              "Unknown Swoosh environment #{value.inspect}. Valid values: #{ENVIRONMENTS.keys.join(", ")}."
+      end
+    end
+
+    def production?
+      environment == :production
+    end
+  end
+end

data/lib/swoosh/errors.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Swoosh
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class CertificateError < Error; end
+
+  # Swish answered, but not with success. A 422 carries a JSON array of
+  # {errorCode, errorMessage, additionalInformation}; other statuses may not.
+  class ResponseError < Error
+    attr_reader :status, :errors, :body
+
+    def initialize(status:, body:)
+      @status = status
+      @body = body
+      @errors = parse(body)
+      super(build_message)
+    end
+
+    def error_code = errors.first&.fetch("errorCode", nil)
+    def error_message = errors.first&.fetch("errorMessage", nil)
+
+    # Builds the most specific error the response justifies. Swish reports
+    # several quite different problems as the same 422, so status alone is not
+    # enough to pick a class -- the errorCode in the body decides.
+    def self.for(status:, body:)
+      subclass_for(status, body).new(status: status, body: body)
+    end
+
+    def self.subclass_for(status, body)
+      return ServerError if status >= 500
+      return PaymentNotFound if status == 404
+
+      ERROR_CLASSES_BY_CODE.fetch(error_code_in(body), RequestError)
+    end
+
+    def self.error_code_in(body)
+      parsed = JSON.parse(body.to_s)
+      parsed = parsed.first if parsed.is_a?(Array)
+      parsed["errorCode"] if parsed.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+
+    private
+
+    def parse(body)
+      parsed = JSON.parse(body.to_s)
+      parsed.is_a?(Array) ? parsed : [parsed]
+    rescue JSON::ParserError
+      []
+    end
+
+    def build_message
+      return "Swish responded #{status}: #{body.to_s[0, 200]}" if errors.empty?
+
+      described = errors.map { |e| "#{e["errorCode"]} #{e["errorMessage"]}".strip }.join(", ")
+      "Swish responded #{status}: #{described}"
+    end
+  end
+
+  # 4xx -- the request was wrong. A bug, or a payer number that can't be used.
+  class RequestError < ResponseError; end
+
+  # 404 -- Swish has no such payment *for this certificate*. Per the integration
+  # guide it means "not found, or it was not created by the merchant", so it is
+  # not proof the payment doesn't exist: the same 404 comes back for a real,
+  # possibly paid payment polled with the wrong merchant certificate.
+  #
+  # Retrying won't help, but treating one as "this payment never happened" is
+  # only safe once you know the certificate is right. In bulk, this almost
+  # always means a configuration mismatch rather than N missing payments.
+  class PaymentNotFound < RequestError; end
+
+  # 422 RP07 -- the payment is no longer CREATED, so there is nothing to
+  # withdraw. This is the race worth designing for rather than an edge case: the
+  # payer accepted somewhere between your decision to cancel and the PATCH
+  # landing, which on a checkout page people abandon by paying is common.
+  #
+  # The payment may well be PAID, so a failed cancel is never licence to treat
+  # the order as abandoned. Poll before you decide anything.
+  class PaymentNotCancellable < RequestError; end
+
+  # 422 RP08 -- already cancelled. The state you asked for already holds, so
+  # this is the one cancel failure that is usually safe to rescue and ignore.
+  class PaymentAlreadyCancelled < RequestError; end
+
+  # 5xx -- Swish had a problem. Worth retrying.
+  class ServerError < ResponseError; end
+
+  # Declared once the classes exist, so the mapping reads as a single table.
+  # An unrecognised code falls back to RequestError rather than raising, so a
+  # code Swish adds later degrades to something still rescuable.
+  ERROR_CLASSES_BY_CODE = {
+    "RP07" => PaymentNotCancellable,
+    "RP08" => PaymentAlreadyCancelled
+  }.freeze
+end

data/lib/swoosh/payment.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+
+module Swoosh
+  # A Swish payment request, however you came by it: the response to creating
+  # one, a poll, or a callback body.
+  #
+  # Only #id and #token can't be re-derived -- everything else comes back from
+  # Swoosh.find_payment.
+  class Payment
+    # Swish stops changing a payment once it reaches one of these.
+    TERMINAL_STATUSES = %w[PAID DECLINED ERROR CANCELLED].freeze
+    CREATED = "CREATED"
+
+    ATTRIBUTES = {
+      id: "id",
+      status: "status",
+      amount: "amount",
+      currency: "currency",
+      message: "message",
+      callback_url: "callbackUrl",
+      payee_alias: "payeeAlias",
+      payer_alias: "payerAlias",
+      payee_payment_reference: "payeePaymentReference",
+      payment_reference: "paymentReference",
+      date_created: "dateCreated",
+      date_paid: "datePaid",
+      error_code: "errorCode",
+      error_message: "errorMessage"
+    }.freeze
+
+    attr_reader :token, :attributes
+
+    # Swish only ever hands the m-commerce token back in the 201 response
+    # header, so it has to be carried alongside rather than read from the body.
+    def initialize(attributes = {}, token: nil)
+      @attributes = attributes.transform_keys(&:to_s)
+      @token = token
+    end
+
+    def self.from_json(json, token: nil)
+      new(json.nil? || json.empty? ? {} : JSON.parse(json), token: token)
+    end
+
+    # The body Swish POSTs to your callback URL is a Payment Request object.
+    def self.from_callback(json)
+      from_json(json)
+    end
+
+    ATTRIBUTES.each do |name, key|
+      define_method(name) { @attributes[key] }
+    end
+
+    def paid? = status == "PAID"
+    def declined? = status == "DECLINED"
+    def cancelled? = status == "CANCELLED"
+    def error? = status == "ERROR"
+
+    def terminal? = TERMINAL_STATUSES.include?(status)
+    def pending? = !terminal?
+
+    # Present for m-commerce (no payer_alias), absent for e-commerce.
+    def token? = !token.nil?
+
+    # Opens the Swish app with this payment preloaded. Same-device flow.
+    # return_url is where Swish (or BankID) sends the payer afterwards; it is a
+    # UX return only, and never evidence that the payment succeeded.
+    def app_switch_url(return_url:)
+      require_token!(:app_switch_url)
+
+      "swish://paymentrequest?token=#{token}&callbackurl=#{CGI.escape(return_url.to_s)}"
+    end
+
+    # Image bytes for the other-device flow. Served from Swish's public QR host.
+    def qr_code(**options)
+      require_token!(:qr_code)
+
+      QrCode.generate(token, **options)
+    end
+
+    def to_h = @attributes.dup
+
+    def ==(other)
+      other.is_a?(Payment) && other.attributes == attributes && other.token == token
+    end
+    alias eql? ==
+
+    def hash = [attributes, token].hash
+
+    private
+
+    def require_token!(method)
+      return if token?
+
+      raise Error, "##{method} needs an m-commerce token. Omit payer_alias when creating the " \
+                   "payment so Swish issues one, or use Swoosh.token_for(id) to recover it."
+    end
+  end
+end

data/lib/swoosh/payment_request.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Swoosh
+  # Builds the body of a Swish payment request.
+  #
+  # payee_alias (your merchant number) and callback_url fall back to the
+  # configuration when a call doesn't name them; everything else is per-call,
+  # because it describes this payment rather than this application.
+  class PaymentRequest
+    # Swish rejects a payload carrying keys it doesn't expect, so anything left
+    # nil is dropped rather than sent as null.
+    def initialize(configuration:, amount:, **options)
+      @configuration = configuration
+      @amount = amount
+      @options = options
+    end
+
+    def to_h
+      {
+        payeeAlias: payee_alias,
+        callbackUrl: callback_url,
+        amount: @amount,
+        currency: currency,
+        message: @options[:message],
+        payerAlias: @options[:payer_alias],
+        payeePaymentReference: @options[:payee_payment_reference],
+        payerSSN: @options[:payer_ssn],
+        ageLimit: @options[:age_limit]
+      }.compact
+    end
+
+    def payee_alias
+      @options[:payee_alias] || @configuration.payee_alias ||
+        raise(ConfigurationError, missing_message("payee_alias", "your Swish merchant number"))
+    end
+
+    def callback_url
+      @options[:callback_url] || @configuration.callback_url ||
+        raise(ConfigurationError, missing_message("callback_url", "the HTTPS URL Swish posts the result to"))
+    end
+
+    def currency
+      @options[:currency] || @configuration.currency
+    end
+
+    private
+
+    def missing_message(name, description)
+      "Swoosh needs a #{name} (#{description}). Pass #{name}: to the call, " \
+        "or set config.swoosh.#{name} once for the whole application."
+    end
+  end
+end

data/lib/swoosh/qr_code.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Swoosh
+  # Swish generates payment QR codes from a separate, public host -- no client
+  # certificate involved, which is why this doesn't go through the mTLS client.
+  module QrCode
+    ENDPOINT = "https://mpc.getswish.net/qrg-swish/api/v1/commerce"
+    FORMATS = %w[png jpg svg].freeze
+    # Swish rejects anything smaller with a 400, for every format.
+    MIN_SIZE = 300
+    DEFAULT_SIZE = 300
+
+    module_function
+
+    # Returns the image bytes. Render with `send_data qr, type: "image/png"`.
+    def generate(token, size: DEFAULT_SIZE, format: "png", border: 0, transparent: false)
+      raise ArgumentError, "Unknown QR format #{format.inspect}. Use #{FORMATS.join(", ")}." unless
+        FORMATS.include?(format.to_s)
+      raise ArgumentError, "Swish requires a QR size of at least #{MIN_SIZE} (got #{size})." if size < MIN_SIZE
+
+      response = Net::HTTP.post(
+        URI.parse(ENDPOINT),
+        JSON.generate({ token: token, size: size, format: format.to_s, border: border, transparent: transparent }),
+        "Content-Type" => "application/json"
+      )
+      raise ResponseError.new(status: response.code.to_i, body: response.body.to_s) unless
+        response.is_a?(Net::HTTPSuccess)
+
+      response.body
+    end
+  end
+end

data/lib/swoosh/railtie.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "callback/controller"
+
+module Swoosh
+  # Maps `config.swoosh.*` from the host app onto Swoosh::Configuration.
+  #
+  #   # config/environments/development.rb
+  #   config.swoosh.environment = :staging               # default outside production
+  #   config.swoosh.cert_dir    = Rails.root.join("config/certs")
+  #   config.swoosh.cert_password = ENV["SWISH_CERT_PASSWORD"]
+  #   config.swoosh.payee_alias = "1231181189"           # your merchant number
+  class Railtie < Rails::Railtie
+    # Passed through only when the app actually set them, so Configuration keeps
+    # owning the defaults.
+    OPTIONAL_SETTINGS = %i[cert_password root_ca_path payee_alias callback_url currency
+                           token_store token_ttl].freeze
+
+    config.swoosh = ActiveSupport::OrderedOptions.new
+
+    initializer "swoosh.configure" do |app|
+      options = app.config.swoosh
+
+      Swoosh.configure do |swoosh|
+        swoosh.environment = options[:environment] || default_environment
+        swoosh.cert_dir = options[:cert_dir] || app.root.join("config/certs")
+        swoosh.token_store = options.key?(:token_store) ? options[:token_store] : ::Rails.cache
+        OPTIONAL_SETTINGS.each do |setting|
+          swoosh.public_send(:"#{setting}=", options[setting]) if options.key?(setting)
+        end
+      end
+    end
+
+    # Development and test talk to the Swish staging playground unless the app
+    # says otherwise, so only a real production boot reaches for real money.
+    def default_environment
+      Rails.env.production? ? :production : :test
+    end
+  end
+end

data/lib/swoosh/test.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Not loaded with the gem -- require "swoosh/test" from your test helper.
+require "json"
+require_relative "../swoosh"
+
+module Swoosh
+  # Builders and stubs for exercising Swish flows without touching the network.
+  module Test
+    CALLBACK_DEFAULTS = {
+      "payeePaymentReference" => "ABC123",
+      "paymentReference" => "A58D39A2632D488EA8F00AA88251336B",
+      "callbackUrl" => "https://example.com/swish/callbacks",
+      "payerAlias" => "4671234768",
+      "payeeAlias" => "1231181189",
+      "amount" => 100.0,
+      "currency" => "SEK",
+      "message" => "",
+      "status" => "PAID",
+      "dateCreated" => "2026-09-21T08:26:45.746Z",
+      "datePaid" => "2026-09-21T08:27:01.000Z",
+      "errorCode" => nil,
+      "errorMessage" => nil
+    }.freeze
+
+    # Swish's refusals, verbatim from the staging playground. RP07 is the payer
+    # winning the race (the payment is PAID); RP08 is a second cancel.
+    CANCEL_REFUSALS = {
+      "RP07" => "The payment request can not be cancelled.",
+      "RP08" => "The payment request has been cancelled."
+    }.freeze
+
+    module_function
+
+    # The body Swish POSTs to your callback URL, shaped like the real thing.
+    def callback_payload(id:, status: "PAID", **overrides)
+      CALLBACK_DEFAULTS
+        .merge("id" => id, "status" => status)
+        .merge(error_defaults(status))
+        .merge(overrides.transform_keys(&:to_s))
+    end
+
+    def callback_json(...) = JSON.generate(callback_payload(...))
+
+    def payment(id: SecureRandom.uuid.delete("-").upcase, status: "CREATED", token: nil, **overrides)
+      Payment.new(callback_payload(id: id, status: status, **overrides), token: token)
+    end
+
+    # Requires webmock. Stubs the mTLS GET that find_payment and
+    # swoosh_verified_payment make.
+    def stub_find_payment(id, status: "PAID", **overrides)
+      require "webmock"
+      WebMock::API.stub_request(:get, %r{/api/v1/paymentrequests/#{id}\z})
+                  .to_return(
+                    status: 200,
+                    body: callback_json(id: id, status: status, **overrides),
+                    headers: { "Content-Type" => "application/json" }
+                  )
+    end
+
+    # Stubs creating a payment, including the token header when one is wanted.
+    def stub_generate_payment(token: "37ca502428ff40c1b17310787165236f")
+      require "webmock"
+      headers = { "Content-Length" => "0" }
+      headers["PaymentRequestToken"] = token if token
+      WebMock::API.stub_request(:put, %r{/api/v2/paymentrequests/})
+                  .to_return(status: 201, body: "", headers: headers)
+    end
+
+    # Stubs the PATCH that cancel_payment makes. Swish answers with the payment
+    # in its new state, so this returns a CANCELLED one by default.
+    def stub_cancel_payment(id, status: "CANCELLED", **overrides)
+      require "webmock"
+      WebMock::API.stub_request(:patch, %r{/api/v1/paymentrequests/#{id}\z})
+                  .to_return(
+                    status: 200,
+                    body: callback_json(id: id, status: status, **overrides),
+                    headers: { "Content-Type" => "application/json" }
+                  )
+    end
+
+    # Stubs a cancel Swish refuses. Defaults to RP07, the race worth testing:
+    # the payer accepted before your PATCH landed.
+    def stub_cancel_payment_refused(id, code: "RP07")
+      require "webmock"
+      WebMock::API.stub_request(:patch, %r{/api/v1/paymentrequests/#{id}\z})
+                  .to_return(
+                    status: 422,
+                    body: JSON.generate(
+                      [{ "errorCode" => code, "errorMessage" => CANCEL_REFUSALS.fetch(code),
+                         "additionalInformation" => nil }]
+                    ),
+                    headers: { "Content-Type" => "application/json" }
+                  )
+    end
+
+    def stub_qr_code(body: "\x89PNG\r\n\x1a\n")
+      require "webmock"
+      WebMock::API.stub_request(:post, Swoosh::QrCode::ENDPOINT)
+                  .to_return(status: 200, body: body, headers: { "Content-Type" => "image/png" })
+    end
+
+    # Swish fills errorCode on more than just ERROR: a successfully cancelled
+    # payment carries RP08 while its status is CANCELLED, not ERROR.
+    def error_defaults(status)
+      case status
+      when "ERROR"
+        { "errorCode" => "TM01", "errorMessage" => "Swish timed out before the payment was started" }
+      when "CANCELLED"
+        { "errorCode" => "RP08", "errorMessage" => CANCEL_REFUSALS.fetch("RP08") }
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/swoosh/token_store.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Swoosh
+  # Optional, best-effort storage for the m-commerce token, which Swish hands
+  # back exactly once and never again.
+  #
+  # Backed by anything with ActiveSupport::Cache's read/write signature, so
+  # `Rails.cache` drops straight in; `delete` is used when present and skipped
+  # when not. A miss is normal and must never raise: the caller creates a fresh
+  # payment request instead. Losing a token costs the payer one extra tap, and
+  # it expires with the payment window anyway.
+  class TokenStore
+    PREFIX = "swoosh:token:"
+
+    # A cache that blips must not take a payment down with it. A cache that was
+    # wired up wrong should be loud, though, so these come straight back out
+    # rather than looking like a miss.
+    PROGRAMMING_ERRORS = [NameError, NoMethodError, TypeError, ArgumentError].freeze
+
+    def initialize(backend, ttl:)
+      @backend = backend
+      @ttl = ttl
+    end
+
+    def write(payment_id, token)
+      return if @backend.nil? || token.nil?
+
+      @backend.write(key(payment_id), token, expires_in: @ttl)
+      token
+    rescue *PROGRAMMING_ERRORS
+      raise
+    rescue StandardError
+      token
+    end
+
+    # Called when a payment can no longer be paid. Best-effort like the rest:
+    # the TTL would clear it anyway, so a backend that refuses is not a failure.
+    #
+    # `delete` is the one method a store may leave out. It arrived after read
+    # and write, so a hand-rolled store written against the older contract
+    # doesn't have it, and a missing one must not turn a completed cancel into
+    # an exception -- unlike read and write, whose absence is a real miswiring.
+    def delete(payment_id)
+      return if @backend.nil? || !@backend.respond_to?(:delete)
+
+      @backend.delete(key(payment_id))
+      nil
+    rescue *PROGRAMMING_ERRORS
+      raise
+    rescue StandardError
+      nil
+    end
+
+    def read(payment_id)
+      return nil if @backend.nil?
+
+      @backend.read(key(payment_id))
+    rescue *PROGRAMMING_ERRORS
+      raise
+    rescue StandardError
+      nil
+    end
+
+    def key(payment_id) = "#{PREFIX}#{payment_id}"
+  end
+end

data/lib/swoosh/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Swoosh
+  VERSION = "0.2.0"
+end