dpay 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f660bb376f9c3a692b0fcd3b243384fb4265a826afb4bce089928687c2ac7e
-  data.tar.gz: ac17460ac4601eb85224609d373a45870eed71a38f129fdf94098fc1d31361d7
+  metadata.gz: 96829708b670a52f5790c2e96db83946582206a72dd1c81cbd3a1744306b7fe9
+  data.tar.gz: 9928ed9b7eb9c6b6da934ad204e6c7afb1aff3d44b12088b33382c74144cb39c
 SHA512:
-  metadata.gz: 3ac8bf1585647900f6723835332ededbaa0b3b6e2901ffe9c23e55fa6688cc448d7c3d4eb7bcc62bcaf4a08f9b4728ddf103a20094801cbd06ce4a3f69e28a1c
-  data.tar.gz: 493b7bf534857df4fc6dcbebbba508ad58b1ea91770bfaf424b67bd02728229f79ab9354532ccca9be078c49d3ad0edfd62c71a08680ace6672e199080038abd
+  metadata.gz: fc7432ce768eeaf7c9795af7177bbdc4b4036bbbcb0c14c390c58c6ad078f40c9889eb8997580f1d44b26ae26df35d28380dba208a81172c3471f094c29977d3
+  data.tar.gz: 04d7f864c82d9f4a29600a61edebc77673c7b2429900018d514d23683f7e9e326b990950298ac17dc76e71f176d2a90e6fbb1d3d6f24a4d4dcdeeaa2455c288a

data/CHANGELOG.md

@@ -7,6 +7,54 @@ projekt stosuje [Semantic Versioning](https://semver.org/lang/pl/).
 
 ## [Unreleased]
 
+## [0.2.0] - wydanie razem z wdrożeniem API dpay
+
+Wersja wymaga API dpay z tym samym wydaniem (wspólne API płatności cyklicznych, suma kontrolna capture
+i anulowania kart). Zmiany łamiące zgodność są oznaczone jako **BREAKING**.
+
+### Added
+
+- `client.recurring` (`DPay::RecurringService`): `status`, `retry` i `cancel` płatności cyklicznej
+  (`/api/v1_0/payments/recurring/*`), modele `DPay::RecurringStatus`, `DPay::RecurringRegistrationInfo`,
+  `DPay::RecurringRetryResult`.
+- `RegisterPaymentRequest#with_recurring_registration(DPay::RecurringRegistration)` - rejestracja płatności
+  cyklicznej (modele O, A i M, `terms_url` wymagany) z kodem BLIK klienta.
+- `RegisterPaymentRequest#with_recurring_alias` - obciążenie zapisanej płatności cyklicznej bez kodu BLIK;
+  alias wchodzi do sumy kontrolnej. `#with_client_context` - opcjonalne IP i przeglądarka klienta przy obciążeniu.
+- Webhooki: `DPay::WebhookVerifier.construct_event` i `.verify` (Standard Webhooks, podpis `v1`, tolerancja czasu,
+  kilka podpisów i sekretów w czasie rotacji; nagłówki z `Hash` z kluczami `String` lub `Symbol` w dowolnej
+  wielkości liter albo w formacie Rack `HTTP_WEBHOOK_ID`), `DPay::WebhookEvent`, `DPay::WebhookEventType`.
+- `client.events` (`DPay::EventService`): historia zdarzeń z filtrami, `list` i `iterate` po stronach
+  (`DPay::EventPage`).
+- `DPay::WebhookTarget` - własny adres zdarzeń w rejestracji płatności (`#with_webhook`), zwrocie
+  (`refunds.create`) i capture karty (`cards.capture`); `RegisterPaymentRequest#with_reference`.
+- `DPay::ApiError#reason`, `DPay::PaymentRejectedError#error_description` (kod błędu także
+  z `additionalInfo.error`), `DPay::RegisteredPayment#recurring_alias` i `#recurring_methods`.
+- `spec/fixtures/api_vectors.json` - wspólne wektory sum kontrolnych i podpisów webhooków wszystkich SDK dpay.
+
+### Changed
+
+- **BREAKING** `cards.capture` i `cards.cancel` wysyłają `service` i sumę
+  `sha256(operacja|service|transaction_id|amount|hash)` - API odrzuca je bez sumy (401).
+- **BREAKING** `DPay::ReturnUrls`: adres IPN jest opcjonalny (`ipn` może być `nil`); bez niego `url_ipn`
+  nie jest wysyłany, a IPN nie przychodzi (wynik przychodzi webhookiem).
+- Kod błędu API (`DPay::ApiError#error_code`) pochodzi z pola `code` (np. `CHECKSUM_REQUIRED`,
+  `WEBHOOK_URL_INVALID`), potem z `errorcode`.
+- `ChecksumCalculator#ordered_body` przyjmuje całe body i spłaszcza obiekty zagnieżdżone (np. `webhook`).
+
+### Removed
+
+- **BREAKING** `BlikService#recurring_status`, `DPay::BlikRecurringRegistration`, `DPay::BlikRecurringStatus`,
+  `DPay::BlikRecurringRegistrationInfo` i `RegisterPaymentRequest#with_register_blik_recurring_alias` - API
+  usunęło te endpointy i pole; użyj `client.recurring` i `#with_recurring_registration`.
+- **BREAKING** `BlikAliasType::PAYID` (aliasy OneClick są tylko `UID`), `TransactionType::BLIK_RECURRING`
+  i `TransactionType::BIZUM_DIRECT` (API odrzuca je kodem 422).
+
+### Deprecated
+
+- `IpnType::CAPTURE`, `IpnEvent#capture?` i `#capture_payment_id` - dpay nie wysyła już IPN typu `capture`;
+  użyj zdarzenia `payment.captured`.
+
 ## [0.1.0] - 2026-07-23
 
 ### Added

data/README.md

@@ -46,9 +46,84 @@ redirect_to payment.redirect_url if payment.redirect_url
 
 `DPay::Money.pln(1050)` przyjmuje kwotę w groszach (najmniejszej jednostce), czyli 10,50 PLN.
 `RegisterPaymentRequest` to budowniczy: każda metoda `with_*` zwraca `self`, więc wywołania można łączyć w łańcuch.
+Adres IPN w `ReturnUrls` jest opcjonalny - bez niego IPN nie przychodzi, a wynik płatności dostaniesz webhookiem.
+
+## Płatności cykliczne
+
+Rejestracja idzie razem z płatnością kodem BLIK klienta (kwota `0` - sama zgoda, więcej - opłata inicjalna).
+Kolejne obciążenia wysyła Twój serwer, bez kodu.
+
+```ruby
+urls = DPay::ReturnUrls.new("https://twojsklep.pl/sukces", "https://twojsklep.pl/blad")
+
+registration = dpay.payments.register(
+  DPay::RegisterPaymentRequest
+    .create(DPay::Money.pln(0), DPay::TransactionType::TRANSFERS, urls)
+    .with_blik_code(kod_blik, request.user_agent, request.remote_ip)
+    .with_recurring_registration(
+      DPay::RecurringRegistration
+        .create("Abonament Premium", DPay::RecurringRegistration::MODEL_O, "https://twojsklep.pl/regulamin")
+        .with_alias("SUB-1234")
+    )
+)
+registration.recurring_alias # => "SUB-1234"
+
+charge = dpay.payments.register(
+  DPay::RegisterPaymentRequest
+    .create(DPay::Money.pln(4999), DPay::TransactionType::TRANSFERS, urls)
+    .with_recurring_alias("SUB-1234")
+    .with_description("Abonament Premium 10/2026")
+)
+
+status = dpay.recurring.status("SUB-1234")  # status.status: ACTIVE, INACTIVE, UNREGISTERED, EXPIRED, DECLINED
+dpay.recurring.retry(charge.transaction_id) # po odmowie, np. INSUFFICIENT_FUNDS
+dpay.recurring.cancel("SUB-1234", "Rezygnacja klienta")
+```
+
+Model `A` (stała kwota) wymaga `with_frequency`, `with_limit_amt`, `with_tot_limit_amt` (kwoty w groszach),
+`with_expiration_date` i `with_init_date`, model `M` przyjmuje je opcjonalnie, a model `O` ich nie dopuszcza.
+Obciążenie wiąże alias z sumą kontrolną, a anulowanie ma własną sumę - SDK liczy obie.
+Limity API: `status` do 60, `retry` i `cancel` do 30 zapytań na minutę (licznik wspólny z resztą API
+płatności z tego adresu IP) - nie odpytuj statusu w pętli, wynik przychodzi webhookiem.
+
+## Webhooki
+
+Zdarzenia (`payment.succeeded`, `refund.failed`, `recurring_payment.canceled` i inne) są podpisane
+(Standard Webhooks). Weryfikuj je na surowym body, przed parsowaniem JSON:
+
+```ruby
+begin
+  event = DPay::WebhookVerifier.construct_event(
+    request.raw_post,
+    request.headers,
+    ENV.fetch("DPAY_WEBHOOK_SECRET") # sekret endpointu z panelu (whsec_...); w czasie rotacji tablica sekretów
+  )
+rescue DPay::SignatureVerificationError
+  return head :bad_request
+end
+
+payment = event.object if event.type == DPay::WebhookEventType::PAYMENT_SUCCEEDED # Hash, kwoty w groszach
+
+head :ok
+```
+
+Nagłówki podajesz jako `Hash` (albo obiekt z `#each` zwracającym nazwę i wartość) z kluczami `String` lub `Symbol`
+w dowolnej wielkości liter (`"webhook-id"`, `"Webhook-Id"`, `:webhook_id`) albo w formacie Rack (`"HTTP_WEBHOOK_ID"`),
+więc zadziała zarówno `request.headers` w Rails, jak i `request.env` w Rack i Sinatrze. Wartość nagłówka może być
+tablicą - liczy się pierwszy element. Znacznik czasu może odbiegać od zegara serwera najwyżej o 300 sekund
+(`DPay::WebhookVerifier::DEFAULT_TOLERANCE`, inną wartość podasz czwartym argumentem). Sama weryfikacja bez
+parsowania: `DPay::WebhookVerifier.verify` z tymi samymi argumentami.
+
+Deduplikuj zdarzenia po `event.id`. Historię zdarzeń (np. po awarii endpointu) pobierzesz przez
+`dpay.events.iterate(types: ["payment.succeeded"]) { |event| ... }` albo stronami przez `dpay.events.list`.
+
+Własny adres zdarzeń jednej płatności: `.with_webhook(DPay::WebhookTarget.create("https://twojsklep.pl/webhooks"))`
+(podpisywany sekretem webhooków serwisu), a Twój identyfikator zamówienia w zdarzeniach: `.with_reference("order-1234")`.
 
 ## Obsługa IPN
 
+IPN przychodzi tylko wtedy, gdy podasz adres IPN w `ReturnUrls`.
+
 Brama traktuje jako potwierdzenie dokładnie treść odpowiedzi, nie kod HTTP. Musi to być dokładnie napis
 `"OK"` (dostępny jako stała `DPay::IpnEvent::ACK`) - jakikolwiek inna treść w body oznacza dla dpay.pl,
 że powiadomienie nie zostało obsłużone i zostanie wysłane ponownie.
@@ -60,7 +135,7 @@ rescue DPay::SignatureVerificationError
   return render plain: "Invalid signature", status: :bad_request
 end
 
-mark_order_as_paid(event.id, event.amount) if event.transfer? || event.capture?
+mark_order_as_paid(event.id, event.amount) if event.transfer?
 
 render plain: DPay::IpnEvent::ACK
 ```
@@ -75,6 +150,14 @@ zamiast ufać wyłącznie faktowi otrzymania powiadomienia.
 dpay.refunds.create("identyfikator-transakcji")
 dpay.refunds.create("identyfikator-transakcji", DPay::Money.pln(500), "reklamacja")
 
+# Odpowiedź oznacza przyjęcie zwrotu - wynik przychodzi zdarzeniem refund.succeeded / refund.failed
+dpay.refunds.create(
+  "identyfikator-transakcji",
+  DPay::Money.pln(500),
+  nil,
+  DPay::WebhookTarget.create("https://twojsklep.pl/webhooks/zwroty", %w[refund.succeeded refund.failed])
+)
+
 availability = dpay.refunds.check_availability("identyfikator-transakcji")
 availability.available?
 ```
@@ -119,6 +202,18 @@ offer = result.dcc_offer if result.dcc_offer?
 
 Klucz publiczny jest rotowany - pobieraj go przed każdą próbą płatności, nie przechowuj go u siebie.
 
+Po preautoryzacji (`pre_auth`) pobierasz środki przez `capture` albo zwalniasz je przez `cancel`. Oba wywołania
+SDK podpisuje sumą kontrolną operacji; `capture` przyjmuje też własny adres zdarzenia `payment.captured`:
+
+```ruby
+dpay.cards.capture(
+  "identyfikator-transakcji",
+  DPay::Money.pln(2999),
+  DPay::WebhookTarget.create("https://twojsklep.pl/webhooks", ["payment.captured"])
+)
+dpay.cards.cancel("identyfikator-transakcji") # bez kwoty: cała nieprzechwycona reszta
+```
+
 ## Obsługa błędów
 
 Wszystkie wyjątki SDK dołączają moduł `DPay::Error`, więc `rescue DPay::Error` łapie każdy z nich.
@@ -130,7 +225,8 @@ rescue DPay::InvalidRequestError => e
   e.field_errors
 rescue DPay::ApiError => e
   e.http_status
-  e.error_code
+  e.error_code # np. CHECKSUM_REQUIRED, WEBHOOK_URL_INVALID
+  e.reason     # szczegół kodu, np. "https_required" przy WEBHOOK_URL_INVALID
 rescue DPay::TransportError
   # błąd sieci - status płatności jest nieznany, sprawdź go przez payments.details()
 rescue DPay::Error => e
@@ -146,9 +242,9 @@ end
 | `DPay::NotFoundError` | HTTP 404 |
 | `DPay::RateLimitError` | HTTP 429, dodatkowo `retry_after`, `limit`, `remaining` |
 | `DPay::ApiServerError` | HTTP 5xx |
-| `DPay::PaymentRejectedError` | rejestracja płatności odrzucona mimo HTTP 200 |
+| `DPay::PaymentRejectedError` | rejestracja płatności odrzucona mimo HTTP 200, dodatkowo `transaction_id`, `error_description` |
 | `DPay::CardPaymentError` | płatność kartą odrzucona mimo HTTP 200 |
-| `DPay::SignatureVerificationError` | niepoprawny lub brakujący podpis IPN |
+| `DPay::SignatureVerificationError` | niepoprawny lub brakujący podpis IPN albo webhooka |
 | `DPay::TransportError` | błąd sieci lub transportu HTTP |
 | `DPay::InvalidArgumentError` | niepoprawny argument przekazany do SDK |
 

data/lib/dpay/blik/blik_alias_type.rb

@@ -2,10 +2,10 @@
 
 module DPay
   module BlikAliasType
+    # BLIK OneClick alias. Recurring payments (PAYID) are handled by Client#recurring.
     UID = "UID"
-    PAYID = "PAYID"
 
-    ALL = [UID, PAYID].freeze
+    ALL = [UID].freeze
 
     def self.valid?(value)
       ALL.include?(value)

data/lib/dpay/blik/blik_service.rb

@@ -23,15 +23,6 @@ module DPay
       nil
     end
 
-    def recurring_status(alias_value)
-      body = { "service" => @api.service, "alias_value" => alias_value }
-      body["checksum"] = @api.checksum.secret_second(@api.service, [alias_value])
-
-      data = @api.post_json(Internal::BaseUrls::API_PAYMENTS, "/api/v1_0/payments/blik/recurring/status", body)
-
-      BlikRecurringStatus.from_api(payload(data))
-    end
-
     private
 
     def alias_body(alias_value, alias_type, reason = nil)

data/lib/dpay/card/card_service.rb

@@ -18,12 +18,28 @@ module DPay
       post(transaction_id, "/pay/card-pre-auth", request.to_body)
     end
 
-    def capture(transaction_id, amount)
-      post(transaction_id, "/capture", { "amount" => amount.to_decimal.to_f })
-    end
-
+    # Captures a pre-authorised amount (partial captures allowed up to the authorisation). Signed with
+    # sha256(capture|service|transaction_id|amount|hash). Optional webhook target for "payment.captured".
+    def capture(transaction_id, amount, webhook = nil)
+      # @type var body: Hash[String, untyped]
+      body = { "service" => @api.service, "amount" => amount.to_decimal.to_f }
+      unless webhook.nil?
+        webhook.assert_events_allowed(WebhookEventType::CAPTURE, "a card capture")
+        body["webhook"] = webhook.to_h
+      end
+      body["checksum"] = @api.checksum.operation("capture", @api.service, transaction_id, amount.to_decimal)
+
+      post(transaction_id, "/capture", body)
+    end
+
+    # Cancels the pre-authorisation, the whole uncaptured remainder without an amount. Signed with
+    # sha256(cancellation|service|transaction_id|amount|hash) - empty amount segment without an amount.
     def cancel(transaction_id, amount = nil)
-      post(transaction_id, "/cancellation", amount.nil? ? {} : { "amount" => amount.to_decimal.to_f })
+      body = { "service" => @api.service }
+      body["amount"] = amount.to_decimal.to_f unless amount.nil?
+      body["checksum"] = @api.checksum.operation("cancellation", @api.service, transaction_id, amount&.to_decimal)
+
+      post(transaction_id, "/cancellation", body)
     end
 
     def google_pay(transaction_id, request)

data/lib/dpay/client.rb

@@ -4,7 +4,7 @@ module DPay
   class Client
     VERSION = DPay::VERSION
 
-    attr_reader :config, :payments, :refunds, :banks, :blik, :cards, :payouts
+    attr_reader :config, :payments, :refunds, :banks, :blik, :cards, :payouts, :recurring, :events
 
     def initialize(service:, secret_hash:, timeout: Config::DEFAULT_TIMEOUT, http_client: nil, base_urls: nil)
       @config = Config.new(
@@ -20,6 +20,8 @@ module DPay
       @blik = BlikService.new(api)
       @cards = CardService.new(api)
       @payouts = PayoutService.new(api)
+      @recurring = RecurringService.new(api)
+      @events = EventService.new(api)
       freeze
     end
   end

data/lib/dpay/errors.rb

@@ -22,14 +22,16 @@ module DPay
   class ApiError < StandardError
     include Error
 
-    attr_reader :http_status, :error_code, :field_errors, :raw_body
+    # reason: detail next to the error code, e.g. "https_required" for WEBHOOK_URL_INVALID.
+    attr_reader :http_status, :error_code, :field_errors, :raw_body, :reason
 
-    def initialize(message, http_status, error_code = nil, field_errors = {}, raw_body = "")
+    def initialize(message, http_status, error_code = nil, field_errors = {}, raw_body = "", reason = nil)
       super(message)
       @http_status = http_status
       @error_code = error_code
       @field_errors = field_errors
       @raw_body = raw_body
+      @reason = reason
     end
   end
 
@@ -51,19 +53,24 @@ module DPay
   end
 
   class PaymentRejectedError < ApiError
-    attr_reader :transaction_id
+    # error_description: the provider's description of the decline, when it sent one.
+    attr_reader :transaction_id, :error_description
 
     def self.from_api(data)
       message = %w[message msg].filter_map { |key| data[key] if data[key].is_a?(String) }.first || "Payment rejected"
-      error_code = data["errorcode"].is_a?(String) ? data["errorcode"] : nil
+      additional = data["additionalInfo"].is_a?(Hash) ? data["additionalInfo"] : {}
+      error_code = [data["errorcode"], additional["error"]].find { |code| code.is_a?(String) }
       transaction_id = data["transactionId"].nil? ? nil : Internal::PHP.strval(data["transactionId"])
+      description = additional["error_description"].is_a?(String) ? additional["error_description"] : nil
 
-      new(message, 200, error_code, {}, Internal::PHP.json_encode(data), transaction_id)
+      new(message, 200, error_code, {}, Internal::PHP.json_encode(data), transaction_id, description)
     end
 
-    def initialize(message, http_status, error_code = nil, field_errors = {}, raw_body = "", transaction_id = nil)
+    def initialize(message, http_status, error_code = nil, field_errors = {}, raw_body = "", transaction_id = nil,
+                   error_description = nil)
       super(message, http_status, error_code, field_errors, raw_body)
       @transaction_id = transaction_id
+      @error_description = error_description
     end
   end
 

data/lib/dpay/internal/checksum_calculator.rb

@@ -5,22 +5,47 @@ require "digest"
 module DPay
   module Internal
     class ChecksumCalculator
+      CHECKSUM_KEY = "checksum"
+
       def initialize(secret_hash)
         @secret_hash = secret_hash
         freeze
       end
 
+      # sha256(service|secret_hash|field1|field2|...) - payment registration, BLIK aliases, recurring payments, events.
       def secret_second(service, fields)
         parts = [service, @secret_hash] + fields.map { |field| PHP.strval(field) }
 
         Digest::SHA256.hexdigest(parts.join("|"))
       end
 
-      def ordered_body(values)
-        joined = values.map { |value| PHP.strval(value) }.join("|")
+      # sha256(value1|value2|...|secret_hash) over the request body in the order it is sent (PBL API: refunds,
+      # transaction details, banks, payouts). Takes the whole body (Hash) or its values (Array). The "checksum" key
+      # is skipped, nested objects (e.g. "webhook") contribute their leaf values in order, nil and false give an empty
+      # segment and true gives "1" - the way the API casts JSON values to strings.
+      def ordered_body(body)
+        values = body.is_a?(Hash) ? body.reject { |key, _| key.to_s == CHECKSUM_KEY }.values : body
+        joined = values.flat_map { |value| leaves(value) }.map { |leaf| PHP.strval(leaf) }.join("|")
 
         Digest::SHA256.hexdigest("#{joined}|#{@secret_hash}")
       end
+
+      # sha256(operation|service|transaction_id|amount|secret_hash) - Cards API capture and cancellation. The
+      # operation name keeps a capture checksum from authorising a cancellation; without an amount the segment
+      # stays empty.
+      def operation(operation, service, transaction_id, amount)
+        Digest::SHA256.hexdigest([operation, service, transaction_id, amount || "", @secret_hash].join("|"))
+      end
+
+      private
+
+      def leaves(value)
+        case value
+        when Hash then value.values.flat_map { |item| leaves(item) }
+        when Array then value.flat_map { |item| leaves(item) }
+        else [value]
+        end
+      end
     end
   end
 end

data/lib/dpay/internal/error_mapper.rb

@@ -17,12 +17,21 @@ module DPay
         error_class(response.status).new(
           message,
           response.status,
-          data["errorcode"].is_a?(String) ? data["errorcode"] : nil,
+          extract_code(data),
           normalize_field_errors(data["errors"]),
-          response.body
+          response.body,
+          data["reason"].is_a?(String) ? data["reason"] : nil
         )
       end
 
+      # "code" (Cards API, webhooks, Connect: CHECKSUM_REQUIRED, WEBHOOK_URL_INVALID, ...), then legacy "errorcode".
+      def extract_code(data)
+        return data["code"] if data["code"].is_a?(String)
+        return data["errorcode"] if data["errorcode"].is_a?(String)
+
+        nil
+      end
+
       def error_class(status)
         case status
         when 401 then AuthenticationError

data/lib/dpay/internal/php.rb

@@ -7,9 +7,15 @@ module DPay
     module PHP
       SAFE_INTEGRAL_FLOAT = 2**53
       NON_UNRESERVED = /[^A-Za-z0-9\-_.~]/n
+      TRIM_EDGES = /\A[ \t\n\r\x00\x0B]+|[ \t\n\r\x00\x0B]+\z/
 
       module_function
 
+      # PHP trim(): strips " \t\n\r\0\x0B" from both ends (String#strip also strips "\f").
+      def trim(value)
+        value.gsub(TRIM_EDGES, "")
+      end
+
       def strval(value)
         case value
         when nil, false then ""

data/lib/dpay/ipn/ipn_event.rb

@@ -39,6 +39,7 @@ module DPay
       scalar("custom")
     end
 
+    # @deprecated dpay no longer sends capture IPNs - use the "payment.captured" webhook event.
     def capture_payment_id
       scalar("capture_payment_id")
     end
@@ -55,6 +56,7 @@ module DPay
       type == IpnType::TRANSFER
     end
 
+    # @deprecated dpay no longer sends capture IPNs - use the "payment.captured" webhook event.
     def capture?
       type == IpnType::CAPTURE
     end

data/lib/dpay/ipn/ipn_type.rb

@@ -3,6 +3,7 @@
 module DPay
   module IpnType
     TRANSFER = "transfer"
+    # @deprecated dpay no longer sends capture IPNs - use the "payment.captured" webhook event.
     CAPTURE = "capture"
     DCB = "dcb"
 

data/lib/dpay/payment/payment_service.rb

@@ -8,10 +8,10 @@ module DPay
 
     def register(request)
       body = request.to_body(@api.service)
-      body["checksum"] = @api.checksum.secret_second(
-        @api.service,
-        [body["value"], body["url_success"], body["url_fail"], body["url_ipn"]]
-      )
+      fields = [body["value"], body["url_success"], body["url_fail"], body["url_ipn"]]
+      # A recurring charge binds the checksum to the customer's alias
+      fields << body["recurring_alias"] unless body["recurring_alias"].nil?
+      body["checksum"] = @api.checksum.secret_second(@api.service, fields)
 
       data = @api.post_json(Internal::BaseUrls::API_PAYMENTS, "/api/v1_0/payments/register", body)
       raise PaymentRejectedError.from_api(data) if rejected?(data)

data/lib/dpay/payment/register_payment_request.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
+require "resolv"
+
 module DPay
   class RegisterPaymentRequest
     BLIK_CODE = /\A\d{6}\z/
     PARTNER_PLATFORM = /\A[A-Z0-9]{1,64}\z/
     HTTP_URL = %r{\Ahttps?://[^\s]+\z}
+    CONTROL_CHARACTERS = /[\x00-\x1F\x7F]/
+    RECURRING_ALIAS_MAX = 128
+    REFERENCE_MAX = 64
     TOGGLES = { "creditcard" => :@credit_card, "paysafecard" => :@paysafecard, "blik" => :@blik,
                 "installment" => :@installment, "paypal" => :@paypal, "nobanks" => :@no_banks }.freeze
+    RECURRING_CONFLICTS = %w[blik_alias register_blik_alias register_card_recurring card_recurring_alias].freeze
 
     attr_reader :amount
 
@@ -21,6 +27,7 @@ module DPay
       @transaction_type = transaction_type
       @urls = urls
       @optional = {}
+      @recurring_registration = nil
     end
 
     def with_description(description)
@@ -103,9 +110,10 @@ module DPay
     end
 
     def with_blik_alias(alias_value, user_agent, user_ip)
-      if @optional.key?("blik_code") || @optional.key?("register_blik_alias") ||
-         @optional.key?("register_blik_recurring_alias")
-        raise InvalidArgumentError, "blik_alias cannot be combined with blik_code or alias registration"
+      if %w[blik_code register_blik_alias recurring_alias].any? { |key| @optional.key?(key) } ||
+         !@recurring_registration.nil?
+        raise InvalidArgumentError,
+              "blik_alias cannot be combined with blik_code, alias registration or recurring payments"
       end
 
       set("blik_alias", alias_value)
@@ -121,12 +129,47 @@ module DPay
       set("register_blik_alias", registration.to_h)
     end
 
-    def with_register_blik_recurring_alias(registration)
-      if @optional.key?("blik_alias")
-        raise InvalidArgumentError, "register_blik_recurring_alias cannot be combined with blik_alias"
+    # Registers a recurring payment together with this payment. Requires the customer's BLIK code (with_blik_code)
+    # and transactionType "transfers"; the amount may be 0 (consent only) or an initial fee.
+    def with_recurring_registration(registration)
+      @recurring_registration = registration
+      self
+    end
+
+    # Charges a registered recurring payment server-to-server (no BLIK code): transactionType "transfers", amount
+    # above 0. The alias is appended to the checksum, binding the charge to that customer.
+    def with_recurring_alias(alias_value)
+      unless alias_value.is_a?(String) && !alias_value.empty? && alias_value.bytesize <= RECURRING_ALIAS_MAX
+        raise InvalidArgumentError, "Recurring alias must be 1-128 characters"
       end
 
-      set("register_blik_recurring_alias", registration.to_h)
+      set("recurring_alias", alias_value)
+    end
+
+    # Payer's user agent and IP for a recurring charge (optional there; BLIK code and alias payments set them in
+    # with_blik_code / with_blik_alias).
+    def with_client_context(user_agent, user_ip)
+      raise InvalidArgumentError, %(Invalid user IP "#{user_ip}") unless ip_address?(user_ip)
+
+      set("user_agent", user_agent)
+      set("user_ip", user_ip)
+    end
+
+    # Sends this payment's events (and later events of its refunds and recurring payment) also to this URL, signed
+    # with the service's webhook secret. Not part of the checksum.
+    def with_webhook(webhook)
+      webhook.assert_events_allowed(WebhookEventType::PAYMENT_REGISTRATION, "a payment registration")
+      set("webhook", webhook.to_h)
+    end
+
+    # Your reference of the payment (max 64 characters), returned as references.merchant in webhooks.
+    def with_reference(reference)
+      trimmed = reference.is_a?(String) ? Internal::PHP.trim(reference) : ""
+      if trimmed.empty? || trimmed.length > REFERENCE_MAX || CONTROL_CHARACTERS.match?(trimmed)
+        raise InvalidArgumentError, "Reference must be 1-64 characters without control characters"
+      end
+
+      set("reference", trimmed)
     end
 
     def with_alias_ipn_url(url)
@@ -194,14 +237,17 @@ module DPay
     end
 
     def to_body(service)
+      assert_recurring_combination
+
+      # @type var body: Hash[String, untyped]
       body = {
         "service" => service,
         "value" => @amount.to_decimal,
         "transactionType" => @transaction_type,
         "url_success" => @urls.success,
-        "url_fail" => @urls.fail,
-        "url_ipn" => @urls.ipn
+        "url_fail" => @urls.fail
       }
+      body["url_ipn"] = @urls.ipn unless @urls.ipn.nil?
 
       append(body, "description")
       append(body, "custom")
@@ -209,10 +255,12 @@ module DPay
       append(body, "accept_tos")
       append(body, "channel")
       append_toggles(body)
-      %w[phone_number currency_code partner_platform user_agent user_ip blik_code blik_alias register_blik_alias
-         register_blik_recurring_alias alias_ipn_url no_delay register_card_recurring card_recurring_alias
-         authorize_only card_recurring_operation payout billing_address shipping_address device_info products
-         efaktura invoice].each { |key| append(body, key) }
+      %w[phone_number currency_code partner_platform user_agent user_ip blik_code blik_alias
+         register_blik_alias].each { |key| append(body, key) }
+      body["recurring_registration"] = @recurring_registration.to_h unless @recurring_registration.nil?
+      %w[recurring_alias alias_ipn_url no_delay register_card_recurring card_recurring_alias authorize_only
+         card_recurring_operation payout billing_address shipping_address device_info products efaktura invoice
+         webhook reference].each { |key| append(body, key) }
 
       body
     end
@@ -242,5 +290,36 @@ module DPay
         body[key] = flag ? 1 : 0 unless flag.nil?
       end
     end
+
+    def ip_address?(value)
+      value.is_a?(String) && !value.include?("%") &&
+        (Resolv::IPv4::Regex.match?(value) || Resolv::IPv6::Regex.match?(value))
+    end
+
+    # Checked when the body is built, like the API: a registration needs the BLIK code and excludes "channel",
+    # a charge needs an amount above 0 and excludes "blik_code"; both exclude the other alias kinds.
+    def assert_recurring_combination
+      charge = !@optional["recurring_alias"].nil?
+      return if @recurring_registration.nil? && !charge
+
+      if !@recurring_registration.nil? && charge
+        raise InvalidArgumentError, "recurring_registration cannot be combined with recurring_alias"
+      end
+      unless @transaction_type == TransactionType::TRANSFERS
+        raise InvalidArgumentError, %(Recurring payments require transactionType "transfers")
+      end
+
+      assert_recurring_requirements(charge)
+      conflict = (RECURRING_CONFLICTS + [charge ? "blik_code" : "channel"]).find { |key| !@optional[key].nil? }
+      raise InvalidArgumentError, "#{conflict} cannot be combined with a recurring payment" unless conflict.nil?
+    end
+
+    def assert_recurring_requirements(charge)
+      if charge
+        raise InvalidArgumentError, "A recurring charge requires an amount above 0" unless @amount.minor.positive?
+      elsif @optional["blik_code"].nil?
+        raise InvalidArgumentError, "recurring_registration requires the customer's BLIK code (with_blik_code)"
+      end
+    end
   end
 end