defra_ruby_govpay 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50914b4891648701b6e1d7e553820f3938c232af1e52666ddc99c60fc12e22e6
-  data.tar.gz: b893ef2af65fadf32e9dc5e437a4303f9f538e597751a976378046d87410ae38
+  metadata.gz: 0c82aff9dd09e95432ad62c5aedb6b4a2d8d4e9e42d9f17bac37ac7cbebbc90f
+  data.tar.gz: e859b6ca00740c0112aa80c117b3584dc2ae64f3be8aceb5fdc8cc055a2bdf59
 SHA512:
-  metadata.gz: 6518bb755f204d0e71c717b7c4e4ee1c1cc325596fb43dff3b8d034488d6489f4729d7e798e93ca3d2d186d57f19b02ab1159a38ba68a14a4090affc579cced3
-  data.tar.gz: 71e3faefb42675a382fe7eb872ab5f08e96843d1fe54a46770c2f75e986fa0950837d1d69e415670014bb0bd46e44245fbfcd27fa6a74d33843a29ea0ab3914b
+  metadata.gz: 62772d1e4dd940a2faa216a9c53d9e1c3fbbe1a36e04bfc7faa9af5969550c2a9ad1c5b3e8ca75d47052b3689a76618cd653d78d357f3d8c4c2409f17fbc3e3d
+  data.tar.gz: 1134a7ff08a8445cca67f50330f022a75e4e51fa08b13c0ef4e1c499659f9c88acf93397c1a1e5b963db4e953c8fd16f65456819a2c50257dc1ce260d5d30ad9

data/README.md

@@ -7,8 +7,9 @@ The `defra-ruby-govpay` gem facilitates seamless integration with GovPay service
 1. [Installation](#installation)
 2. [Configuration](#configuration)
 3. [Usage](#usage)
-4. [Error Handling](#error-handling)
-5. [Testing](#testing)
+4. [Webhook Handling](#webhook-handling)
+5. [Error Handling](#error-handling)
+6. [Testing](#testing)
 
 ## Installation
 
@@ -77,6 +78,54 @@ rescue DefraRubyGovpay::GovpayApiError => e
 end
 ```
 
+## Webhook Handling
+
+The gem provides functionality for handling Govpay webhooks for both payments and refunds. The webhook services validate the webhook content, that the status transition is allowed, return structured information that your application can use to update its records.
+
+### Processing Webhooks
+
+The webhook services extract and return data from the webhook payload:
+
+```ruby
+# For payment webhooks
+result = DefraRubyGovpay::GovpayWebhookPaymentService.run(webhook_body)
+# => { id: "hu20sqlact5260q2nanm0q8u93", status: "success" }
+
+# For refund webhooks
+result = DefraRubyGovpay::GovpayWebhookRefundService.run(webhook_body)
+# => { id: "789", payment_id: "original-payment-123", status: "success" }
+```
+
+### Validating Webhook Signatures
+
+To validate the signature of a webhook, use the `CallbackValidator` class:
+
+```ruby
+valid = DefraRubyGovpay::CallbackValidator.call(
+  request_body,
+  ENV['GOVPAY_WEBHOOK_SIGNING_SECRET'],
+  request.headers['Pay-Signature']
+)
+
+if valid
+  # Process the webhook
+else
+  # Handle invalid signature
+end
+```
+
+### Payment vs Refund Webhooks
+
+The gem can handle both payment and refund webhooks:
+
+- **Payment Webhooks**: These have a `resource_type` of "payment" and contain payment status information in `resource.state.status`.
+- **Refund Webhooks**: These have a `refund_id` field and contain refund status information in the `status` field.
+
+The appropriate service class will be used based on the webhook type:
+
+- `GovpayWebhookPaymentService` for payment webhooks
+- `GovpayWebhookRefundService` for refund webhooks
+
 ## Testing
 
 ```

data/lib/defra_ruby_govpay/callback_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module DefraRubyGovpay
+  class CallbackValidator
+    def self.call(request_body, signing_secret, pay_signature_header)
+      new(request_body, signing_secret, pay_signature_header).call
+    end
+
+    attr_reader :request_body, :signing_secret, :pay_signature_header
+
+    def initialize(request_body, signing_secret, pay_signature_header)
+      @request_body = request_body
+      @signing_secret = signing_secret
+      @pay_signature_header = pay_signature_header
+    end
+
+    def call
+      hmac = OpenSSL::HMAC.hexdigest("sha256", signing_secret.encode("utf-8"), request_body.encode("utf-8"))
+
+      hmac == pay_signature_header
+    end
+  end
+end

data/lib/defra_ruby_govpay/configuration.rb

@@ -5,6 +5,6 @@ module DefraRubyGovpay
   # for the DefraRubyGovpay module. You can set different options like
   # API tokens, host preferences, and other necessary configurations here.
   class Configuration
-    attr_accessor :govpay_url, :govpay_front_office_api_token, :govpay_back_office_api_token
+    attr_accessor :govpay_url, :govpay_front_office_api_token, :govpay_back_office_api_token, :logger
   end
 end

data/lib/defra_ruby_govpay/services/govpay_webhook_base_service.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module DefraRubyGovpay
+  class GovpayWebhookBaseService
+    class InvalidGovpayStatusTransition < StandardError; end
+
+    attr_accessor :webhook_body, :previous_status
+
+    # override this in subclasses
+    VALID_STATUS_TRANSITIONS = {}.freeze
+
+    def self.run(webhook_body, previous_status: nil)
+      new.run(webhook_body, previous_status: previous_status)
+    end
+
+    def initialize
+      # No initialization needed
+    end
+
+    def run(webhook_body, previous_status: nil)
+      @webhook_body = webhook_body
+      @previous_status = previous_status
+
+      validate_webhook_body
+
+      # If we have a previous status and it's different from the current one, validate the transition
+      if previous_status && previous_status != webhook_payment_or_refund_status
+        validate_status_transition
+      else
+        DefraRubyGovpay.logger.warn(
+          "Status \"#{@previous_status}\" unchanged in #{payment_or_refund_str} webhook update " \
+          "#{log_webhook_context}"
+        )
+      end
+
+      # Extract and return data from webhook
+      extract_data_from_webhook
+    end
+
+    private
+
+    def validate_status_transition
+      return if self.class::VALID_STATUS_TRANSITIONS[previous_status]&.include?(webhook_payment_or_refund_status)
+
+      raise InvalidGovpayStatusTransition, "Invalid #{payment_or_refund_str} status transition " \
+                                           "from #{previous_status} to #{webhook_payment_or_refund_status}" \
+                                           "#{log_webhook_context}"
+    end
+
+    def extract_data_from_webhook
+      {
+        id: webhook_payment_or_refund_id,
+        status: webhook_payment_or_refund_status,
+        webhook_body: webhook_body
+      }
+    end
+
+    # The following methods must be implemented in subclasses
+    def payment_or_refund_str
+      raise NotImplementedError
+    end
+
+    def validate_webhook_body
+      raise NotImplementedError
+    end
+
+    def webhook_payment_or_refund_id
+      raise NotImplementedError
+    end
+
+    def webhook_payment_or_refund_status
+      raise NotImplementedError
+    end
+
+    def log_webhook_context
+      raise NotImplementedError
+    end
+  end
+end

data/lib/defra_ruby_govpay/services/govpay_webhook_payment_service.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DefraRubyGovpay
+  class GovpayWebhookPaymentService < GovpayWebhookBaseService
+
+    VALID_STATUS_TRANSITIONS = {
+      "created" => %w[started submitted success failed cancelled error],
+      "started" => %w[submitted success failed cancelled error],
+      "submitted" => %w[success failed cancelled error],
+      "success" => %w[],
+      "failed" => %w[],
+      "cancelled" => %w[],
+      "error" => %w[]
+    }.freeze
+
+    private
+
+    def payment_or_refund_str
+      "payment"
+    end
+
+    def validate_webhook_body
+      raise ArgumentError, "Invalid webhook type #{webhook_resource_type}" unless webhook_resource_type == "payment"
+
+      return unless webhook_payment_or_refund_status.blank?
+
+      raise ArgumentError, "Webhook body missing payment status: #{webhook_body}"
+    end
+
+    def webhook_resource_type
+      @webhook_resource_type ||= webhook_body["resource_type"]&.downcase
+    end
+
+    def webhook_payment_or_refund_id
+      @webhook_payment_or_refund_id ||= webhook_body.dig("resource", "payment_id")
+    end
+
+    def webhook_payment_or_refund_status
+      @webhook_payment_or_refund_status ||= webhook_body.dig("resource", "state", "status")
+    end
+
+    def log_webhook_context
+      "for payment #{webhook_payment_or_refund_id}"
+    end
+  end
+end

data/lib/defra_ruby_govpay/services/govpay_webhook_refund_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DefraRubyGovpay
+  class GovpayWebhookRefundService < GovpayWebhookBaseService
+
+    VALID_STATUS_TRANSITIONS = {
+      "submitted" => %w[success],
+      "success" => %w[],
+      "error" => %w[]
+    }.freeze
+
+    private
+
+    def payment_or_refund_str
+      "refund"
+    end
+
+    def validate_webhook_body
+      return if webhook_payment_or_refund_id.present? && webhook_payment_or_refund_status.present?
+
+      raise ArgumentError, "Invalid refund webhook: #{webhook_body}"
+    end
+
+    def webhook_payment_id
+      @webhook_payment_id ||= webhook_body["payment_id"]
+    end
+
+    def webhook_payment_or_refund_id
+      @webhook_payment_or_refund_id ||= webhook_body["refund_id"]
+    end
+
+    def webhook_payment_or_refund_status
+      @webhook_payment_or_refund_status ||= webhook_body["status"]
+    end
+
+    def extract_data_from_webhook
+      data = super
+
+      data.merge!(
+        payment_id: webhook_payment_id
+      )
+
+      data
+    end
+
+    def log_webhook_context
+      "for refund #{webhook_payment_or_refund_id}"
+    end
+  end
+end

data/lib/defra_ruby_govpay/services/govpay_webhook_sanitizer_service.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+
+module DefraRubyGovpay
+  class GovpayWebhookSanitizerService
+    def self.call(webhook_body)
+      new.call(webhook_body)
+    end
+
+    def call(webhook_body)
+      return webhook_body unless webhook_body.is_a?(Hash)
+
+      # Create a deep copy to avoid modifying the original hash
+      sanitized = webhook_body.deep_dup
+
+      if sanitized["resource"].is_a?(Hash)
+        sanitized["resource"].delete("email")
+        sanitized["resource"].delete("card_details")
+      end
+
+      sanitized
+    end
+  end
+end

data/lib/defra_ruby_govpay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DefraRubyGovpay
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

data/lib/defra_ruby_govpay.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "logger"
 require_relative "defra_ruby_govpay/version"
 require_relative "defra_ruby_govpay/configuration"
 require_relative "defra_ruby_govpay/object"
@@ -8,6 +9,11 @@ require_relative "defra_ruby_govpay/payment"
 require_relative "defra_ruby_govpay/refund"
 require_relative "defra_ruby_govpay/error"
 require_relative "defra_ruby_govpay/api"
+require_relative "defra_ruby_govpay/callback_validator"
+require_relative "defra_ruby_govpay/services/govpay_webhook_base_service"
+require_relative "defra_ruby_govpay/services/govpay_webhook_payment_service"
+require_relative "defra_ruby_govpay/services/govpay_webhook_refund_service"
+require_relative "defra_ruby_govpay/services/govpay_webhook_sanitizer_service"
 
 # The DefraRubyGovpay module facilitates integration with Govpay services.
 # It provides a convenient and configurable way to interact with Govpay APIs in Defra's ruby applications.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: defra_ruby_govpay
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Jerome Pratt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2025-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -48,11 +48,16 @@ files:
 - defra_ruby_govpay.gemspec
 - lib/defra_ruby_govpay.rb
 - lib/defra_ruby_govpay/api.rb
+- lib/defra_ruby_govpay/callback_validator.rb
 - lib/defra_ruby_govpay/configuration.rb
 - lib/defra_ruby_govpay/error.rb
 - lib/defra_ruby_govpay/object.rb
 - lib/defra_ruby_govpay/payment.rb
 - lib/defra_ruby_govpay/refund.rb
+- lib/defra_ruby_govpay/services/govpay_webhook_base_service.rb
+- lib/defra_ruby_govpay/services/govpay_webhook_payment_service.rb
+- lib/defra_ruby_govpay/services/govpay_webhook_refund_service.rb
+- lib/defra_ruby_govpay/services/govpay_webhook_sanitizer_service.rb
 - lib/defra_ruby_govpay/version.rb
 - sig/defra_ruby_govpay.rbs
 homepage: https://github.com/DEFRA/defra-ruby-govpay