dpay 0.1.0 → 0.2.0

data/lib/dpay/payment/registered_payment.rb

@@ -38,5 +38,24 @@ module DPay
 
       additional["card_recurring_alias"]
     end
+
+    # Alias of the recurring payment registered with this payment (with_recurring_registration).
+    def recurring_alias
+      value = recurring_registration["alias"]
+      value.is_a?(String) ? value : nil
+    end
+
+    def recurring_methods
+      names = recurring_registration["methods"]
+      names.is_a?(Array) ? names.grep(String) : []
+    end
+
+    private
+
+    def recurring_registration
+      additional = @raw["additionalInfo"]
+      registration = additional.is_a?(Hash) ? additional["recurring_registration"] : nil
+      registration.is_a?(Hash) ? registration : {}
+    end
   end
 end

data/lib/dpay/payment/return_urls.rb

@@ -6,8 +6,10 @@ module DPay
 
     attr_reader :success, :fail, :ipn
 
-    def initialize(success, fail, ipn)
+    # ipn is optional: without it no IPN is sent and "url_ipn" is left out (the outcome comes as a webhook).
+    def initialize(success, fail, ipn = nil)
       { "success" => success, "fail" => fail, "ipn" => ipn }.each do |name, url|
+        next if name == "ipn" && url.nil?
         raise InvalidArgumentError, %(Invalid #{name} URL "#{url}") unless url.is_a?(String) && HTTP_URL.match?(url)
       end
 

data/lib/dpay/payment/transaction_type.rb

@@ -6,11 +6,9 @@ module DPay
     DCB_GATEWAY = "dcb_gateway"
     CARD_AUTH = "card_auth"
     MB_WAY_DIRECT = "mb_way_direct"
-    BIZUM_DIRECT = "bizum_direct"
-    BLIK_RECURRING = "blik_recurring"
     CARD_RECURRING = "card_recurring"
 
-    ALL = [TRANSFERS, DCB_GATEWAY, CARD_AUTH, MB_WAY_DIRECT, BIZUM_DIRECT, BLIK_RECURRING, CARD_RECURRING].freeze
+    ALL = [TRANSFERS, DCB_GATEWAY, CARD_AUTH, MB_WAY_DIRECT, CARD_RECURRING].freeze
 
     def self.valid?(value)
       ALL.include?(value)

data/lib/dpay/recurring/recurring_registration.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module DPay
+  # The "recurring_registration" object: registers a recurring payment (today BLIK, alias PAYID) together with a
+  # payment that carries the customer's BLIK code. Models:
+  #  - O (open): no frequency or limits, the merchant charges any amount within its active ranges (max 2000 PLN);
+  #  - A (automatic): fixed amount, frequency, total limit, start and expiry date - all required;
+  #  - M (manual): every charge is confirmed by the customer in the banking app; frequency and limits optional.
+  class RecurringRegistration
+    MODEL_A = "A"
+    MODEL_M = "M"
+    MODEL_O = "O"
+    MODELS = [MODEL_A, MODEL_M, MODEL_O].freeze
+
+    METHOD_BLIK = "blik"
+    METHODS = [METHOD_BLIK].freeze
+
+    FREQUENCY = /\A[1-9][0-9]{0,2}[DWMY]\z/
+    DATE = /\A\d{4}-\d{2}-\d{2}\z/
+    HTTP_URL = %r{\Ahttps?://[^\s]+\z}
+    TERMS_URL_MAX = 2048
+    ALIAS_MAX = 128
+    MODEL_O_FORBIDDEN = %w[frequency limit_amt tot_limit_amt is_limit_amt_fixed].freeze
+    MODEL_A_REQUIRED = %w[frequency limit_amt tot_limit_amt expiration_date init_date].freeze
+    OPTIONAL_ORDER = %w[frequency limit_amt tot_limit_amt is_limit_amt_fixed expiration_date init_date methods].freeze
+
+    attr_reader :model
+
+    # terms_url: the merchant's terms the customer accepted (consent evidence).
+    def self.create(label, model, terms_url)
+      new(label, model, terms_url)
+    end
+
+    def initialize(label, model, terms_url)
+      unless label.is_a?(String) && !label.empty? && label.length <= 50
+        raise InvalidArgumentError, "Recurring payment label must be 1-50 characters"
+      end
+      raise InvalidArgumentError, %(Invalid recurring model "#{model}") unless MODELS.include?(model)
+      unless terms_url.is_a?(String) && terms_url.bytesize <= TERMS_URL_MAX && HTTP_URL.match?(terms_url)
+        raise InvalidArgumentError, %(Invalid terms URL "#{terms_url}")
+      end
+
+      @label = label
+      @model = model
+      @terms_url = terms_url
+      @optional = {}
+    end
+
+    # Your own alias of the recurring payment (max 128 characters); without it dpay assigns one.
+    def with_alias(alias_value)
+      unless alias_value.is_a?(String) && !alias_value.empty? && alias_value.bytesize <= ALIAS_MAX
+        raise InvalidArgumentError, "Recurring alias must be 1-128 characters"
+      end
+
+      set("alias", alias_value)
+    end
+
+    def with_terms_version(terms_version)
+      unless terms_version.is_a?(String) && !terms_version.empty? && terms_version.length <= 64
+        raise InvalidArgumentError, "Terms version must be 1-64 characters"
+      end
+
+      set("terms_version", terms_version)
+    end
+
+    # Payment methods of the recurring payment, today only "blik".
+    def with_methods(names)
+      unless names.is_a?(Array) && !names.empty? && names.uniq.size == names.size
+        raise InvalidArgumentError, "Methods must be a non-empty list of distinct methods"
+      end
+
+      unsupported = names.reject { |name| METHODS.include?(name) }
+      raise InvalidArgumentError, %(Unsupported recurring method "#{unsupported.first}") unless unsupported.empty?
+
+      set("methods", names.dup)
+    end
+
+    # Frequency like "1M", "2W", "14D", "1Y" (1-999 days, weeks, months or years).
+    def with_frequency(frequency)
+      unless frequency.is_a?(String) && FREQUENCY.match?(frequency)
+        raise InvalidArgumentError, %(Invalid recurring frequency "#{frequency}")
+      end
+
+      set("frequency", frequency)
+    end
+
+    # Single payment limit in minor units (grosz).
+    def with_limit_amt(limit_amt)
+      set("limit_amt", assert_positive(limit_amt, "limit_amt"))
+    end
+
+    # Total limit of all payments in minor units (grosz).
+    def with_tot_limit_amt(tot_limit_amt)
+      set("tot_limit_amt", assert_positive(tot_limit_amt, "tot_limit_amt"))
+    end
+
+    def with_limit_amt_fixed(fixed)
+      raise InvalidArgumentError, "is_limit_amt_fixed must be true or false" unless [true, false].include?(fixed)
+
+      set("is_limit_amt_fixed", fixed)
+    end
+
+    # YYYY-MM-DD, after today and at most 10 years ahead.
+    def with_expiration_date(expiration_date)
+      set("expiration_date", assert_date(expiration_date))
+    end
+
+    # YYYY-MM-DD, the first charge date (today or later).
+    def with_init_date(init_date)
+      set("init_date", assert_date(init_date))
+    end
+
+    # Key order: label, alias, model, frequency, limit_amt, tot_limit_amt, is_limit_amt_fixed, expiration_date,
+    # init_date, methods, terms_url, terms_version. Raises InvalidArgumentError when the terms break the model rules.
+    def to_h
+      assert_model_rules
+
+      data = { "label" => @label }
+      data["alias"] = @optional["alias"] if @optional.key?("alias")
+      data["model"] = @model
+      OPTIONAL_ORDER.each { |key| data[key] = @optional[key] if @optional.key?(key) }
+      data["terms_url"] = @terms_url
+      data["terms_version"] = @optional["terms_version"] if @optional.key?("terms_version")
+      data
+    end
+
+    private
+
+    def set(key, value)
+      @optional[key] = value
+      self
+    end
+
+    def assert_model_rules
+      if @model == MODEL_O
+        forbidden = MODEL_O_FORBIDDEN.find { |key| @optional.key?(key) }
+        raise InvalidArgumentError, "#{forbidden} is not allowed in recurring model O" unless forbidden.nil?
+      end
+      return unless @model == MODEL_A
+
+      missing = MODEL_A_REQUIRED.find { |key| !@optional.key?(key) }
+      raise InvalidArgumentError, "#{missing} is required in recurring model A" unless missing.nil?
+      return unless @optional["is_limit_amt_fixed"] == false
+
+      raise InvalidArgumentError, "Recurring model A requires a fixed amount (is_limit_amt_fixed = true)"
+    end
+
+    def assert_positive(value, field)
+      raise InvalidArgumentError, "#{field} must be at least 1 (minor units)" unless value.is_a?(Integer) && value >= 1
+
+      value
+    end
+
+    def assert_date(date)
+      unless date.is_a?(String) && DATE.match?(date)
+        raise InvalidArgumentError, %(Date "#{date}" must be in YYYY-MM-DD format)
+      end
+
+      date
+    end
+  end
+end

data/lib/dpay/recurring/recurring_registration_info.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DPay
+  # Terms of a registered recurring payment, as returned by the status endpoint. Amounts in minor units (grosz).
+  class RecurringRegistrationInfo
+    DIGITS = /\A\d+\z/
+
+    # transaction_id: transactionId of the registering payment. registered_at: ISO 8601 with offset.
+    attr_reader :transaction_id, :label, :model, :frequency, :limit_amt, :tot_limit_amt, :limit_amt_fixed,
+                :init_date, :terms_url, :terms_version, :registered_at, :raw
+
+    def self.from_api(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @raw = data
+      @transaction_id = string(data["transaction_id"])
+      @label = string(data["label"])
+      @model = string(data["model"])
+      @frequency = string(data["frequency"])
+      @limit_amt = integer(data["limit_amt"])
+      @tot_limit_amt = integer(data["tot_limit_amt"])
+      fixed = data["is_limit_amt_fixed"]
+      @limit_amt_fixed = [true, false].include?(fixed) ? fixed : nil
+      @init_date = string(data["init_date"])
+      @terms_url = string(data["terms_url"])
+      @terms_version = string(data["terms_version"])
+      @registered_at = string(data["registered_at"])
+      freeze
+    end
+
+    private
+
+    def string(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def integer(value)
+      return value if value.is_a?(Integer)
+
+      value.is_a?(String) && DIGITS.match?(value) ? value.to_i : nil
+    end
+  end
+end

data/lib/dpay/recurring/recurring_retry_result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DPay
+  # Result of retrying a declined recurring charge. "pending" - the retry went to the bank, the outcome comes like for
+  # a charge (webhook, IPN, status); "failed" - the bank declined it at once (error code in #error_code).
+  class RecurringRetryResult
+    STATUS_PENDING = "pending"
+    STATUS_FAILED = "failed"
+    STATUS_SUCCESS = "success"
+
+    # count: which retry this was (1-3).
+    attr_reader :transaction_id, :status, :count, :error_code, :error_description, :raw
+
+    def self.from_api(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @raw = data
+      details = data["retry"].is_a?(Hash) ? data["retry"] : {}
+      @transaction_id = Internal::Coerce.string(data["transactionId"]) || ""
+      @status = string(details["status"])
+      @count = details["count"].is_a?(Integer) ? details["count"] : nil
+      @error_code = string(details["error"])
+      @error_description = string(details["error_description"])
+      freeze
+    end
+
+    def pending?
+      @status == STATUS_PENDING
+    end
+
+    def failed?
+      @status == STATUS_FAILED
+    end
+
+    private
+
+    def string(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/dpay/recurring/recurring_service.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module DPay
+  # Recurring payments shared by payment methods (today BLIK). Registration and charges go through
+  # payments.register with RegisterPaymentRequest#with_recurring_registration and #with_recurring_alias.
+  class RecurringService
+    CANCEL = "cancel"
+
+    def initialize(api)
+      @api = api
+    end
+
+    # Current status and terms of the recurring payment registered for this service.
+    def status(alias_value)
+      body = {
+        "service" => @api.service,
+        "alias" => alias_value,
+        "checksum" => @api.checksum.secret_second(@api.service, [alias_value])
+      }
+
+      RecurringStatus.from_api(payload(post("/api/v1_0/payments/recurring/status", body)))
+    end
+
+    # Retries a declined recurring charge (transaction_id of the charge) with the same BLIK transaction - up to
+    # 3 times within 5 minutes, only after declines the customer can fix, e.g. INSUFFICIENT_FUNDS. Not retryable:
+    # InvalidRequestError with the reason in field_errors["retry"] (e.g. DECLINE_NOT_RETRYABLE, RETRY_LIMIT_REACHED).
+    def retry(transaction_id)
+      body = {
+        "service" => @api.service,
+        "transaction_id" => transaction_id,
+        "checksum" => @api.checksum.secret_second(@api.service, [transaction_id])
+      }
+
+      RecurringRetryResult.from_api(payload(post("/api/v1_0/payments/recurring/retry", body)))
+    end
+
+    # Cancels the recurring payment (for BLIK: unregisters the alias at BLIK); later charges with the alias are
+    # rejected. The checksum ends with the operation name, so a status checksum cannot cancel. Returns the new
+    # status (UNREGISTERED).
+    def cancel(alias_value, reason = nil)
+      body = { "service" => @api.service, "alias" => alias_value }
+      body["reason"] = reason unless reason.nil?
+      body["checksum"] = @api.checksum.secret_second(@api.service, [alias_value, CANCEL])
+
+      status = payload(post("/api/v1_0/payments/recurring/cancel", body))["status"]
+      status.is_a?(String) ? status : RecurringStatus::UNREGISTERED
+    end
+
+    private
+
+    def post(path, body)
+      @api.post_json(Internal::BaseUrls::API_PAYMENTS, path, body)
+    end
+
+    def payload(data)
+      data["data"].is_a?(Hash) ? data["data"] : {}
+    end
+  end
+end

data/lib/dpay/recurring/recurring_status.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DPay
+  class RecurringStatus
+    ACTIVE = "ACTIVE"
+    INACTIVE = "INACTIVE"
+    UNREGISTERED = "UNREGISTERED"
+    EXPIRED = "EXPIRED"
+    DECLINED = "DECLINED"
+
+    ALL = [ACTIVE, INACTIVE, UNREGISTERED, EXPIRED, DECLINED].freeze
+
+    # payment_method: the "method" field, e.g. "blik" (renamed so it does not shadow Object#method).
+    # status: ACTIVE, INACTIVE (waiting for the customer), UNREGISTERED, EXPIRED, DECLINED or nil.
+    attr_reader :alias, :payment_method, :status, :expiration_date, :registration, :raw
+
+    def self.from_api(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @raw = data
+      @alias = string(data["alias"]) || ""
+      @payment_method = string(data["method"])
+      @status = string(data["status"])
+      @expiration_date = string(data["expiration_date"])
+      registration = data["registration"]
+      @registration = registration.is_a?(Hash) ? RecurringRegistrationInfo.from_api(registration) : nil
+      freeze
+    end
+
+    def active?
+      @status == ACTIVE
+    end
+
+    private
+
+    def string(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/dpay/refund/refund_service.rb

@@ -8,8 +8,12 @@ module DPay
       @api = api
     end
 
-    def create(transaction_id, amount = nil, reason = nil)
-      body = signed_body(transaction_id, amount, reason)
+    # Orders a refund (partial with an amount, the rest of the payment without). A successful response means the
+    # refund was accepted - its outcome comes as a "refund.succeeded" / "refund.failed" event. The optional webhook
+    # target receives the events of this refund and is part of the checksum.
+    def create(transaction_id, amount = nil, reason = nil, webhook = nil)
+      webhook&.assert_events_allowed(WebhookEventType::REFUND, "a refund")
+      body = signed_body(transaction_id, amount, reason, webhook)
 
       Refund.from_api(@api.post_json(Internal::BaseUrls::PANEL, "/api/v1/pbl/refund", body))
     end
@@ -34,11 +38,13 @@ module DPay
       status == 401 && data["message"] != "Unauthorized request"
     end
 
-    def signed_body(transaction_id, amount, reason)
+    def signed_body(transaction_id, amount, reason, webhook = nil)
+      # @type var body: Hash[String, untyped]
       body = { "service" => @api.service, "transaction_id" => transaction_id }
       body["value"] = amount.to_decimal unless amount.nil?
       body["reason"] = reason unless reason.nil?
-      body["checksum"] = @api.checksum.ordered_body(body.values)
+      body["webhook"] = webhook.to_h unless webhook.nil?
+      body["checksum"] = @api.checksum.ordered_body(body)
 
       body
     end

data/lib/dpay/version.rb

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

data/lib/dpay/webhook/event_page.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DPay
+  class EventPage
+    # data: events, newest first. Re-encoded by the API - do not verify webhook signatures on them.
+    attr_reader :data, :next_starting_after, :raw
+
+    def self.from_api(response)
+      new(response)
+    end
+
+    def initialize(response)
+      @raw = response
+      @data = Internal::Coerce.list(response["data"]).map { |event| WebhookEvent.from_api(event) }.freeze
+      @has_more = response["has_more"] == true
+      next_starting_after = response["next_starting_after"]
+      @next_starting_after = next_starting_after.is_a?(String) ? next_starting_after : nil
+      freeze
+    end
+
+    def has_more? # rubocop:disable Naming/PredicatePrefix
+      @has_more
+    end
+  end
+end

data/lib/dpay/webhook/event_service.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module DPay
+  # Events API: the event history of the service (the same envelopes as webhooks), newest first. Use it to catch up
+  # after an outage of your webhook endpoint.
+  class EventService
+    PATH = "/api/v1_0/events"
+    STARTING_AFTER = /\Aevt_[0-9a-z]{26}\z/
+    DATE_FIELDS = %w[created_from created_to].freeze
+    LIMIT = (1..100)
+
+    def initialize(api)
+      @api = api
+    end
+
+    # params (String or Symbol keys): types, created_from, created_to, starting_after, limit. timestamp: Unix time
+    # for the checksum (defaults to now; the API accepts +/- 300 s).
+    def list(params = {}, timestamp = nil)
+      options = params.transform_keys(&:to_s)
+      timestamp = Time.now.to_i if timestamp.nil?
+      raise InvalidArgumentError, "timestamp must be an Integer (Unix time)" unless timestamp.is_a?(Integer)
+
+      body = { "service" => @api.service, "timestamp" => timestamp }
+      append_types(body, options["types"])
+      DATE_FIELDS.each { |field| body[field] = options[field] unless options[field].nil? }
+      append_starting_after(body, options["starting_after"])
+      append_limit(body, options["limit"])
+      body["checksum"] = @api.checksum.secret_second(@api.service, [timestamp.to_s])
+
+      EventPage.from_api(@api.post_json(Internal::BaseUrls::API_PAYMENTS, PATH, body))
+    end
+
+    # Iterates over all matching events page by page (newest first). Without a block returns an Enumerator.
+    def iterate(params = {}, &block)
+      return enum_for(:iterate, params) if block.nil?
+
+      options = params.transform_keys(&:to_s)
+      loop do
+        page = list(options)
+        page.data.each(&block)
+        options["starting_after"] = page.next_starting_after
+        break unless page.has_more? && !options["starting_after"].nil?
+      end
+
+      nil
+    end
+
+    private
+
+    def append_types(body, types)
+      return if types.nil?
+      unless types.is_a?(Array) && !types.empty? && types.uniq.size == types.size
+        raise InvalidArgumentError, "Event types must be a non-empty list of distinct types"
+      end
+
+      WebhookEventType.assert_allowed(types, WebhookEventType::MERCHANT, "the Events API")
+      body["types"] = types.dup
+    end
+
+    def append_starting_after(body, starting_after)
+      return if starting_after.nil?
+      unless starting_after.is_a?(String) && STARTING_AFTER.match?(starting_after)
+        raise InvalidArgumentError, "starting_after must be an event id (evt_...)"
+      end
+
+      body["starting_after"] = starting_after
+    end
+
+    def append_limit(body, limit)
+      return if limit.nil?
+      raise InvalidArgumentError, "limit must be between 1 and 100" unless limit.is_a?(Integer) && LIMIT.cover?(limit)
+
+      body["limit"] = limit
+    end
+  end
+end

data/lib/dpay/webhook/webhook_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DPay
+  # Webhook event envelope: {id, type, api_version, created, livemode, service, [merchant_ref], data: {object}}.
+  # data.object stays a Hash - payment, refund, recurring_payment or payout, amounts in minor units.
+  class WebhookEvent
+    # created: event time in UTC ("YYYY-MM-DDTHH:MM:SSZ") - not the delivery time, do not use it against replays.
+    # service: nil for account events (payouts) and test events. merchant_ref: only in events sent to a dpay Connect
+    # partner. object_type: "payment", "refund", "recurring_payment", "payout" or "webhook_endpoint".
+    attr_reader :id, :type, :api_version, :created, :service, :merchant_ref, :object, :object_type, :raw
+
+    def self.from_api(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @raw = data
+      @id = string(data["id"]) || ""
+      @type = string(data["type"]) || ""
+      @api_version = string(data["api_version"])
+      @created = string(data["created"])
+      @livemode = data["livemode"] != false
+      @service = string(data["service"])
+      @merchant_ref = string(data["merchant_ref"])
+      envelope = data["data"]
+      object = envelope.is_a?(Hash) ? envelope["object"] : nil
+      @object = object.is_a?(Hash) ? object : {}
+      @object_type = string(@object["object"])
+      freeze
+    end
+
+    def livemode?
+      @livemode
+    end
+
+    private
+
+    def string(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/dpay/webhook/webhook_event_type.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DPay
+  module WebhookEventType
+    PAYMENT_SUCCEEDED = "payment.succeeded"
+    PAYMENT_FAILED = "payment.failed"
+    PAYMENT_CAPTURED = "payment.captured"
+    REFUND_SUCCEEDED = "refund.succeeded"
+    REFUND_FAILED = "refund.failed"
+    RECURRING_PAYMENT_ACTIVATED = "recurring_payment.activated"
+    RECURRING_PAYMENT_CANCELED = "recurring_payment.canceled"
+    RECURRING_PAYMENT_EXPIRED = "recurring_payment.expired"
+    RECURRING_PAYMENT_DECLINED = "recurring_payment.declined"
+    PAYOUT_PAID = "payout.paid"
+    PAYOUT_FAILED = "payout.failed"
+    WEBHOOK_TEST = "webhook.test"
+
+    # Events allowed in the "webhook" object of a payment registration.
+    PAYMENT_REGISTRATION = [
+      PAYMENT_SUCCEEDED, PAYMENT_FAILED, PAYMENT_CAPTURED, REFUND_SUCCEEDED, REFUND_FAILED,
+      RECURRING_PAYMENT_ACTIVATED, RECURRING_PAYMENT_CANCELED, RECURRING_PAYMENT_EXPIRED, RECURRING_PAYMENT_DECLINED
+    ].freeze
+
+    # Events a merchant endpoint can subscribe to and the Events API can filter on.
+    MERCHANT = (PAYMENT_REGISTRATION + [PAYOUT_PAID, PAYOUT_FAILED]).freeze
+
+    # Events allowed in the "webhook" object of a refund.
+    REFUND = [REFUND_SUCCEEDED, REFUND_FAILED].freeze
+
+    # Events allowed in the "webhook" object of a card capture.
+    CAPTURE = [PAYMENT_CAPTURED].freeze
+
+    def self.assert_allowed(events, allowed, context)
+      events.each do |event|
+        next if allowed.include?(event)
+
+        raise InvalidArgumentError, %(Event "#{event}" is not allowed in the webhook object of #{context})
+      end
+
+      nil
+    end
+  end
+end

data/lib/dpay/webhook/webhook_target.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DPay
+  # Per-request webhook address (the "webhook" object of a payment registration, refund or card capture). Events of
+  # this payment go to this URL, signed with the service's webhook secret, on top of the endpoints set in the panel.
+  class WebhookTarget
+    HTTPS_URL = %r{\Ahttps://[^\s]+\z}i
+    URL_MAX = 500
+
+    attr_reader :url, :events
+
+    # events: empty = every event the request allows.
+    def self.create(url, events = [])
+      new(url, events)
+    end
+
+    def initialize(url, events = [])
+      raise InvalidArgumentError, "Webhook URL must be at most 500 characters" if url.to_s.bytesize > URL_MAX
+      unless url.is_a?(String) && HTTPS_URL.match?(url)
+        raise InvalidArgumentError, %(Webhook URL "#{url}" must be a valid https:// URL)
+      end
+      unless events.is_a?(Array) && events.uniq.size == events.size
+        raise InvalidArgumentError, "Webhook events must be distinct"
+      end
+
+      WebhookEventType.assert_allowed(events, WebhookEventType::MERCHANT, "a request")
+
+      @url = url
+      @events = events.dup.freeze
+      freeze
+    end
+
+    def assert_events_allowed(allowed, context)
+      WebhookEventType.assert_allowed(@events, allowed, context)
+    end
+
+    # "url" first, then "events" - the refund checksum hashes the values in this order.
+    def to_h
+      # @type var data: Hash[String, untyped]
+      data = { "url" => @url }
+      data["events"] = @events.dup unless @events.empty?
+      data
+    end
+  end
+end