przelewy24_payment 0.2.0 → 2.0.0

data/app/jobs/przelewy24_payment/charge_due_subscriptions_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # Schedule this job (cron, Solid Queue recurring tasks, GoodJob cron) e.g. hourly.
+  class ChargeDueSubscriptionsJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      Subscription.charge_due!
+      Payment.expire_stale!
+    end
+  end
+end

data/app/models/przelewy24_payment/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  class ApplicationRecord < ::ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/przelewy24_payment/payment.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  class Payment < ApplicationRecord
+    self.table_name = "przelewy24_payments"
+
+    # pending:  registered, waiting for the customer or for a notification
+    # verified: confirmed by Przelewy24, money received
+    # failed:   notification arrived but verification was rejected
+    # expired:  abandoned attempt closed by .expire_stale!; a late notification
+    #           can still settle it
+    STATUSES = %w[pending verified failed expired].freeze
+
+    belongs_to :payable, polymorphic: true
+    has_many :refunds, class_name: "Przelewy24Payment::Refund", dependent: :destroy
+
+    validates :session_id, presence: true, uniqueness: true
+    validates :amount, numericality: { only_integer: true, greater_than: 0 }
+    validates :currency, presence: true
+    validates :status, inclusion: { in: STATUSES }
+
+    scope :pending, -> { where(status: "pending") }
+    scope :verified, -> { where(status: "verified") }
+    scope :stale, ->(older_than: 1.day) { pending.where(created_at: ...older_than.ago) }
+
+    # Creates a payment with a fresh session id, registers it at Przelewy24
+    # and returns it with a token. Each payment attempt gets its own record.
+    # Closes abandoned attempts (customer left the gateway, no notification came).
+    # Safe to run from a recurring job; returns the number of closed payments.
+    def self.expire_stale!(older_than: 1.day)
+      stale(older_than: older_than).find_each.count(&:expire!)
+    end
+
+    # Builds the pending payment for the next period of a subscription.
+    def self.create_for!(subscription)
+      create!(payable: subscription, amount: subscription.amount, currency: subscription.currency,
+              session_id: SecureRandom.alphanumeric(16).upcase)
+    end
+
+    # Raises AlreadyPaidError when the payable already has a verified payment,
+    # so a retry can never charge the customer twice.
+    def self.start!(payable:, amount:, currency:, email:, description:, return_url:, status_url: nil,
+                    client: Przelewy24Payment.client, **extra)
+      raise AlreadyPaidError, "#{payable.class} ##{payable.id} already has a verified payment" if payable.przelewy24_paid?
+
+      payment = create!(payable: payable, amount: Money.to_minor(amount), currency: currency,
+                        session_id: SecureRandom.alphanumeric(16).upcase)
+      token = client.transactions.register(
+        session_id: payment.session_id, amount: payment.amount, currency: currency,
+        description: description, email: email, url_return: return_url,
+        url_status: status_url || payment.default_status_url, **extra
+      )
+      payment.update!(token: token)
+      payment
+    rescue StandardError
+      payment&.update_columns(status: "failed")
+      raise
+    end
+
+    def amount_decimal = Money.from_minor(amount)
+
+    def subscription
+      payable if payable.is_a?(Subscription)
+    end
+
+    # Closes an abandoned attempt. For a subscription this counts as a failed charge.
+    def expire!
+      with_lock do
+        next false unless status == "pending"
+
+        update!(status: "expired")
+        subscription&.record_failure!(reason: "payment_expired")
+        true
+      end
+    end
+
+    # BLIK level 0: charges the registered transaction with the customer's code.
+    # For a subscription payment the alias and recurring settings default to the
+    # ones stored on the subscription. The result arrives through the webhook.
+    def charge_blik_code!(blik_code:, alias_value: nil, alias_label: nil, recurring: nil,
+                          client: Przelewy24Payment.client)
+      sub = subscription
+      client.blik.charge_by_code(
+        token: token, blik_code: blik_code,
+        alias_value: alias_value || sub&.alias_value, alias_label: alias_label || sub&.alias_label,
+        recurring: recurring || sub&.recurring
+      )
+    end
+
+    # BLIK 1-click with a stored alias.
+    def charge_blik_alias!(alias_value:, client: Przelewy24Payment.client)
+      client.blik.charge_by_alias(token: token, alias_value: alias_value)
+    end
+
+    # Card charge by reference (registered with method_ref_id). Without 3-D Secure
+    # it is off-session; with `three_ds: true` it returns { order_id:, redirect_url: }.
+    def charge_card!(three_ds: false, client: Przelewy24Payment.client)
+      three_ds ? client.cards.charge_with_3ds(token: token) : client.cards.charge(token: token)
+    end
+
+    # Registers and charges a subscription renewal without the customer.
+    def register_and_charge!(client: Przelewy24Payment.client)
+      sub = subscription
+      options = { method_ref_id: sub.method_ref }
+      options[:additional] = { PSU: sub.psu } if sub.payment_method == "blik" && sub.psu
+      self.token = client.transactions.register(
+        session_id: session_id, amount: amount, currency: currency, description: sub.description,
+        email: sub.email, url_return: sub.return_url, url_status: default_status_url, **options
+      )
+      save!
+      if sub.payment_method == "blik"
+        charge_blik_alias!(alias_value: sub.method_ref, client: client)
+      else
+        charge_card!(client: client)
+      end
+    rescue StandardError
+      update_columns(status: "failed") if persisted?
+      raise
+    end
+
+    def redirect_url = token && Przelewy24Payment.configuration.gateway_url(token)
+    def pending? = status == "pending"
+    def expired? = status == "expired"
+    def verified? = status == "verified"
+    def failed? = status == "failed"
+
+    def default_status_url
+      Przelewy24Payment::Engine.routes.url_helpers.status_webhooks_url(
+        **Przelewy24Payment.configuration.url_options
+      )
+    end
+
+    # Verifies the notification with Przelewy24 exactly once: row lock + status
+    # guard make duplicate deliveries harmless. Does not run callbacks, see
+    # #deliver_callbacks!. Returns :verified, :failed or :duplicate.
+    def settle!(notification, client: Przelewy24Payment.client)
+      with_lock do
+        next :duplicate unless status.in?(%w[pending expired])
+
+        update!(p24_order_id: notification.order_id, method_id: notification.method_id,
+                payload: notification.attributes.except("sign"))
+        ok = client.transactions.verify(session_id: session_id, order_id: notification.order_id,
+                                        amount: amount, currency: currency)
+        update!(status: ok ? "verified" : "failed", verified_at: (Time.current if ok))
+        if ok
+          subscription&.payment_verified!(self, client: client)
+        else
+          subscription&.record_failure!(reason: "verification_failed")
+        end
+        ok ? :verified : :failed
+      end
+    end
+
+    def settled? = status.in?(%w[verified failed])
+
+    # Runs the configured callback for a settled payment until it succeeds once.
+    # The callback and the notified_at stamp share one transaction, so a raising
+    # callback leaves the payment un-notified and the next webhook delivery
+    # retries it. Callbacks therefore run at least once and must be idempotent
+    # for side effects outside the database (mails, jobs).
+    # Returns true when the callback ran, false when there was nothing to do.
+    def deliver_callbacks!
+      with_lock do
+        next false unless settled? && notified_at.nil?
+
+        config = Przelewy24Payment.configuration
+        callback = verified? ? config.on_payment_verified : config.on_payment_failed
+        callback&.call(self)
+        update!(notified_at: Time.current)
+        Instrumentation.instrument("payment_#{status}", payment: self)
+        true
+      end
+    end
+
+    ActiveSupport.run_load_hooks(:przelewy24_payment_payment, self)
+  end
+end

data/app/models/przelewy24_payment/refund.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  class Refund < ApplicationRecord
+    self.table_name = "przelewy24_refunds"
+
+    STATUSES = %w[pending completed failed].freeze
+
+    belongs_to :payment, class_name: "Przelewy24Payment::Payment"
+
+    validates :amount, numericality: { only_integer: true, greater_than: 0 }
+    validates :refunds_uuid, presence: true, uniqueness: true
+    validates :status, inclusion: { in: STATUSES }
+
+    # Requests a refund of a verified payment. Amount in decimal currency units.
+    def self.request!(payment:, amount:, description: nil, status_url: nil, client: Przelewy24Payment.client)
+      raise Error, "payment is not verified" unless payment.verified?
+
+      minor = Money.to_minor(amount)
+      request_id = SecureRandom.uuid
+      result = client.refunds.create(
+        request_id: request_id, order_id: payment.p24_order_id, session_id: payment.session_id,
+        amount: minor, description: description,
+        url_status: status_url || Przelewy24Payment::Engine.routes.url_helpers.refund_webhooks_url(
+          **Przelewy24Payment.configuration.url_options
+        )
+      )
+      create!(payment: payment, amount: minor, request_id: request_id, refunds_uuid: result.fetch("refundsUuid"))
+    end
+
+    ActiveSupport.run_load_hooks(:przelewy24_payment_refund, self)
+  end
+end

data/app/models/przelewy24_payment/subscription.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  # Przelewy24 has no subscription object: it only lets you charge a stored
+  # BLIK alias or card reference without the customer present. This model keeps
+  # the schedule on your side and drives those charges.
+  #
+  #   pending   -> first payment not confirmed yet
+  #   active    -> charged every `frequency` while payments succeed
+  #   past_due  -> last charge failed, retried every config.retry_interval
+  #   canceled  -> no more charges (by you, or after too many failures)
+  class Subscription < ApplicationRecord
+    self.table_name = "przelewy24_subscriptions"
+
+    STATUSES = %w[pending active past_due canceled].freeze
+    METHODS = %w[blik card].freeze
+    FREQUENCY = /\A([1-9]\d{0,2})([DWMY])\z/
+
+    include Payable
+
+    belongs_to :owner, polymorphic: true
+
+    validates :payment_method, inclusion: { in: METHODS }
+    validates :status, inclusion: { in: STATUSES }
+    validates :frequency, format: { with: FREQUENCY }
+    validates :amount, numericality: { only_integer: true, greater_than: 0 }
+    validates :currency, :email, :return_url, presence: true
+
+    scope :active, -> { where(status: "active") }
+    scope :due, ->(at = Time.current) { where(status: %w[active past_due]).where(next_charge_at: ..at) }
+
+    # Starts a subscription with its first payment, made with the customer
+    # present. Redirect to the returned payment's redirect_url (card, or BLIK
+    # through the gateway) or complete a BLIK code payment with
+    # payment.charge_blik_code!(...) passing the same alias and `recurring`.
+    #
+    # For BLIK pass `recurring:` exactly as described in the Przelewy24 docs
+    # (type O/M/A, frequency, limits). The feature must be enabled by Przelewy24.
+    #
+    # psu: { IP:, userAgent: } of the customer; Przelewy24 requires it for BLIK
+    # and it is reused for later off-session charges.
+    def self.start!(owner:, payment_method:, amount:, currency:, email:, description:, frequency:, return_url:,
+                    psu: nil, recurring: nil, alias_value: nil, alias_label: nil, client: Przelewy24Payment.client,
+                    **payment_options)
+      is_blik = payment_method.to_s == "blik"
+      subscription = create!(owner: owner, payment_method: payment_method.to_s, amount: Money.to_minor(amount),
+                             currency: currency, email: email, description: description, frequency: frequency,
+                             return_url: return_url, psu: psu, recurring: recurring,
+                             alias_value: alias_value || (SecureRandom.uuid if is_blik),
+                             alias_label: alias_label || description.to_s.ljust(5, ".").first(35))
+      payment_options[:additional] = { PSU: psu } if psu
+      subscription.first_payment = Payment.start!(
+        payable: subscription, amount: amount, currency: currency, email: email, description: description,
+        return_url: return_url, client: client, **payment_options
+      )
+      subscription
+    rescue StandardError
+      subscription&.update_columns(status: "canceled", cancel_reason: "start_failed")
+      raise
+    end
+
+    attr_accessor :first_payment
+
+    # Charges the stored method for the next period. The result arrives through
+    # the normal status webhook, which renews the subscription.
+    # Returns the pending Payment, or nil when a charge is already in flight.
+    def charge!(client: Przelewy24Payment.client)
+      payment = with_lock do
+        next if canceled? || method_ref.blank? || przelewy24_payments.pending.exists?
+
+        Payment.create_for!(self)
+      end
+      return unless payment
+
+      payment.register_and_charge!(client: client)
+      payment
+    rescue Error => e
+      record_failure!(reason: e.message)
+      nil
+    end
+
+    # Charges every due subscription. Run from a recurring job.
+    def self.charge_due!(client: Przelewy24Payment.client)
+      due.find_each.count { |subscription| subscription.charge!(client: client) }
+    end
+
+    def cancel!(reason: "canceled")
+      return false if canceled?
+
+      update!(status: "canceled", canceled_at: Time.current, cancel_reason: reason, next_charge_at: nil)
+      Instrumentation.instrument("subscription_canceled", subscription: self)
+      true
+    end
+
+    def canceled? = status == "canceled"
+    def active? = status == "active"
+    def amount_decimal = Money.from_minor(amount)
+
+    # Called from Payment#settle! when a payment of this subscription is verified.
+    def payment_verified!(payment, client: Przelewy24Payment.client)
+      return if canceled?
+
+      first = pending?
+      self.method_ref = fetch_card_reference(payment, client) if payment_method == "card" && method_ref.blank?
+      self.method_ref = alias_value if payment_method == "blik" && method_ref.blank?
+      update!(status: "active", failed_attempts: 0, last_charged_at: Time.current,
+              next_charge_at: advance(Time.current))
+      Instrumentation.instrument(first ? "subscription_activated" : "subscription_renewed",
+                                 subscription: self, payment: payment)
+    end
+
+    # Called when a payment of this subscription failed or expired.
+    def record_failure!(reason: nil)
+      return if canceled?
+
+      attempts = failed_attempts + 1
+      if pending? || attempts >= Przelewy24Payment.configuration.max_failed_attempts
+        return cancel!(reason: reason.presence || "payment_failed")
+      end
+
+      update!(status: "past_due", failed_attempts: attempts,
+              next_charge_at: Przelewy24Payment.configuration.retry_interval.from_now)
+      Instrumentation.instrument("subscription_past_due", subscription: self, reason: reason)
+    end
+
+    def pending? = status == "pending"
+
+    private
+
+    def advance(from)
+      count, unit = FREQUENCY.match(frequency).captures
+      count = count.to_i
+      case unit
+      when "D" then from + count.days
+      when "W" then from + count.weeks
+      when "M" then from + count.months
+      when "Y" then from + count.years
+      end
+    end
+
+    def fetch_card_reference(payment, client)
+      client.cards.reference_for(payment.p24_order_id)
+    end
+
+    ActiveSupport.run_load_hooks(:przelewy24_payment_subscription, self)
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Przelewy24Payment::Engine.routes.draw do
+  post "webhooks/status", to: "webhooks#status", as: :status_webhooks
+  post "webhooks/refund", to: "webhooks#refund", as: :refund_webhooks
+end

data/lib/generators/przelewy24_payment/install/install_generator.rb

@@ -1,8 +1,63 @@
-class Przelewy24Payment::InstallGenerator < Rails::Generators::Base
-  source_root File.expand_path('../templates', __FILE__)
+# frozen_string_literal: true
 
-  def add_config
-    template "przelewy24_payment.rb", "config/initializers/przelewy24_payment.rb"
-  end
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Przelewy24Payment
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs Przelewy24Payment: initializer, migrations and webhook routes."
+
+      class_option :mount_path, type: :string, default: "/przelewy24",
+                                desc: "Path where the webhook engine is mounted"
+      class_option :skip_subscriptions, type: :boolean, default: false,
+                                        desc: "Do not generate the subscriptions migration"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/przelewy24_payment.rb"
+      end
+
+      def copy_migrations
+        migration_template "create_przelewy24_payments.rb.tt", "db/migrate/create_przelewy24_payments.rb",
+                           migration_version: migration_version
+        tables = options[:skip_subscriptions] ? %w[refunds] : %w[refunds subscriptions]
+        tables.each do |name|
+          sleep 1 # keep migration timestamps unique
+          migration_template "create_przelewy24_#{name}.rb.tt", "db/migrate/create_przelewy24_#{name}.rb",
+                             migration_version: migration_version
+        end
+      end
 
+      def mount_engine
+        return if File.read(File.join(destination_root, "config/routes.rb")).include?("Przelewy24Payment::Engine")
+
+        route "mount Przelewy24Payment::Engine => #{mount_path.inspect}"
+      end
+
+      def show_readme
+        return unless behavior == :invoke
+
+        say File.read(File.join(self.class.source_root, "README")).gsub("{{mount_path}}", mount_path)
+      end
+
+      private
+
+      def mount_path
+        path = options[:mount_path].to_s
+        path = "/#{path}" unless path.start_with?("/")
+        path.chomp("/").presence || "/"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
 end

data/lib/generators/przelewy24_payment/install/templates/README

@@ -0,0 +1,14 @@
+
+Przelewy24Payment installed. Next steps:
+
+  1. Run `bin/rails db:migrate`.
+  2. Add credentials (`bin/rails credentials:edit`) or set the ENV variables:
+     PRZELEWY24_MERCHANT_ID, PRZELEWY24_POS_ID (optional), PRZELEWY24_API_KEY, PRZELEWY24_CRC_KEY.
+  3. Include Przelewy24Payment::Payable in your payable model (e.g. Order).
+  4. Start a payment:
+       payment = Przelewy24Payment::Payment.start!(payable: order, amount: order.price,
+         currency: "PLN", email: user.email, description: "Order #1", return_url: order_url(order))
+       redirect_to payment.redirect_url, allow_other_host: true
+  5. Status webhook URL (public, HTTPS in production):
+       POST {{mount_path}}/webhooks/status
+

data/lib/generators/przelewy24_payment/install/templates/create_przelewy24_payments.rb.tt

@@ -0,0 +1,21 @@
+class CreatePrzelewy24Payments < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :przelewy24_payments do |t|
+      t.references :payable, polymorphic: true, null: false, index: true
+      t.string :session_id, null: false
+      t.string :token
+      t.integer :amount, null: false
+      t.string :currency, null: false
+      t.string :status, null: false, default: "pending"
+      t.bigint :p24_order_id
+      t.integer :method_id
+      t.json :payload
+      t.datetime :verified_at
+      t.datetime :notified_at
+      t.timestamps
+    end
+
+    add_index :przelewy24_payments, :session_id, unique: true
+    add_index :przelewy24_payments, :p24_order_id
+  end
+end

data/lib/generators/przelewy24_payment/install/templates/create_przelewy24_refunds.rb.tt

@@ -0,0 +1,14 @@
+class CreatePrzelewy24Refunds < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :przelewy24_refunds do |t|
+      t.references :payment, null: false, foreign_key: { to_table: :przelewy24_payments }
+      t.integer :amount, null: false
+      t.string :request_id, null: false
+      t.string :refunds_uuid, null: false
+      t.string :status, null: false, default: "pending"
+      t.timestamps
+    end
+
+    add_index :przelewy24_refunds, :refunds_uuid, unique: true
+  end
+end

data/lib/generators/przelewy24_payment/install/templates/create_przelewy24_subscriptions.rb.tt

@@ -0,0 +1,28 @@
+class CreatePrzelewy24Subscriptions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :przelewy24_subscriptions do |t|
+      t.references :owner, polymorphic: true, null: false, index: true
+      t.string :payment_method, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :frequency, null: false
+      t.integer :amount, null: false
+      t.string :currency, null: false
+      t.string :email, null: false
+      t.string :description
+      t.string :return_url, null: false
+      t.string :alias_value
+      t.string :alias_label
+      t.string :method_ref
+      t.json :recurring
+      t.json :psu
+      t.integer :failed_attempts, null: false, default: 0
+      t.datetime :next_charge_at
+      t.datetime :last_charged_at
+      t.datetime :canceled_at
+      t.string :cancel_reason
+      t.timestamps
+    end
+
+    add_index :przelewy24_subscriptions, %i[status next_charge_at]
+  end
+end

data/lib/generators/przelewy24_payment/install/templates/initializer.rb.tt

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+Przelewy24Payment.configure do |config|
+  # :sandbox or :production
+  config.environment = Rails.env.production? ? :production : :sandbox
+
+  # Credentials: Rails credentials first, ENV as a fallback.
+  #   bin/rails credentials:edit
+  #   przelewy24:
+  #     merchant_id: 12345
+  #     pos_id: 12345        # optional, defaults to merchant_id
+  #     api_key: "..."       # REST API key from the Przelewy24 panel
+  #     crc_key: "..."       # CRC key of the shop
+  credentials = Rails.application.credentials.przelewy24 || {}
+  config.merchant_id = credentials[:merchant_id] || ENV["PRZELEWY24_MERCHANT_ID"]
+  config.pos_id      = credentials[:pos_id]      || ENV["PRZELEWY24_POS_ID"]
+  config.api_key     = credentials[:api_key]     || ENV["PRZELEWY24_API_KEY"]
+  config.crc_key     = credentials[:crc_key]     || ENV["PRZELEWY24_CRC_KEY"]
+
+  config.default_country  = "PL"
+  config.default_language = "pl"
+
+  # Public host used to build the status webhook URL sent to Przelewy24.
+  # In development point it at a tunnel (ngrok, cloudflared).
+  config.url_options = {
+    host: ENV.fetch("APP_HOST", "localhost:3000"),
+    protocol: ENV.fetch("APP_PROTOCOL", Rails.env.production? ? "https" : "http")
+  }
+
+  # Optional: only accept webhooks from Przelewy24 servers (IPs and CIDR ranges
+  # published in the Przelewy24 REST docs, section "Adresy IP serwerów").
+  # config.allowed_ips = %w[5.252.202.254 5.252.202.255 20.215.81.124 20.215.183.48/28
+  #                         193.178.213.0/24 91.220.177.0/24 134.112.88.8/29]
+
+  # Controller the webhook endpoints inherit from. Keep it free of
+  # authentication filters; Przelewy24 calls it without a session.
+  # config.parent_controller = "ApplicationController"
+
+  # Subscriptions: failed charges before cancel, and the wait between retries.
+  # config.max_failed_attempts = 3
+  # config.retry_interval = 1.day
+
+  # Called once per payment, after Przelewy24 confirmed the transaction.
+  config.on_payment_verified = ->(payment) { payment.payable.try(:payment_verified!) }
+  config.on_payment_failed   = ->(payment) { payment.payable.try(:payment_failed!) }
+  config.on_refund           = ->(refund) { }
+end

data/lib/przelewy24_payment/api/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      def config = client.configuration
+    end
+  end
+end

data/lib/przelewy24_payment/api/blik.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    # BLIK on the merchant's own page. The transaction must be registered first
+    # (with additional.PSU) and its token passed here.
+    class Blik < Base
+      # BLIK level 0: the customer types the 6-digit code. Pass alias_value,
+      # alias_label (5..35 chars) and recurring to register an alias for later charges.
+      def charge_by_code(token:, blik_code:, alias_value: nil, alias_label: nil, recurring: nil)
+        body = { token: token, blikCode: blik_code, aliasValue: alias_value,
+                 aliasLabel: alias_label, recurring: recurring }.compact
+        client.post("paymentMethod/blik/chargeByCode", body).fetch("data").fetch("orderId")
+      end
+
+      # BLIK 1-click / recurring charge with a stored alias. Raises
+      # AmbiguousAliasError (HTTP 409) when the alias maps to several bank apps;
+      # retry with charge_by_alternative_key using one of error.alternative_keys.
+      def charge_by_alias(token:, alias_value:)
+        charge(type: "alias", token: token, aliasValue: alias_value)
+      end
+
+      def charge_by_alternative_key(token:, alternative_key:)
+        charge(type: "alternativeKey", token: token, alternativeKey: alternative_key)
+      end
+
+      def aliases(email, custom: false)
+        path = "paymentMethod/blik/getAliasesByEmail/#{ERB::Util.url_encode(email)}"
+        client.get(custom ? "#{path}/custom" : path).fetch("data")
+      end
+
+      private
+
+      def charge(body)
+        client.post("paymentMethod/blik/chargeByAlias", body).fetch("data").fetch("orderId")
+      rescue ConflictError => e
+        raise AmbiguousAliasError.new(e.message, status: e.status, body: e.body)
+      end
+    end
+  end
+end

data/lib/przelewy24_payment/api/cards.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Przelewy24Payment
+  module Api
+    # Card one-click and recurring charges by card reference (refId). The
+    # reference must be passed as methodRefId when registering the transaction.
+    class Cards < Base
+      # Reference of the card used in a paid transaction (nil when unavailable).
+      def reference_for(order_id)
+        client.get("card/info/#{Integer(order_id)}").dig("data", "refId")
+      end
+
+      # Charge without the customer present (recurring). Returns the order id.
+      def charge(token:)
+        client.post("card/charge", { token: token }).fetch("data").fetch("orderId")
+      end
+
+      # One-click charge that may need 3-D Secure. Returns { order_id:, redirect_url: }
+      # where redirect_url is nil when no customer action is needed.
+      def charge_with_3ds(token:)
+        data = client.post("card/chargeWith3ds", { token: token }).fetch("data")
+        { order_id: data["orderId"], redirect_url: data["redirectUrl"] }
+      end
+    end
+  end
+end