payu_pl 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3153797e232dc9495c8f175f37558a8f360688b9f53e311cf925652a55db620
-  data.tar.gz: ca4dcc6531dec57bbc908c39cd5dd801d8fb9e5e33de22eca1df876e40abdd8e
+  metadata.gz: 0e5d4017013c53056c374299d981c16553d6de4372f9446bd6dbb2aebbc05929
+  data.tar.gz: 22ecc4cfcf8b66c153b21956b5fa4754b70ec51589e51e8bc6703d33e2789216
 SHA512:
-  metadata.gz: 144220b42c84c7745c1f41755afe6c118bf9b0d2b06567abdea30ab21403341c7991525f914e70da3f971781ae4944d66b22cb6826603c4fcf96f18a2c88f1c8
-  data.tar.gz: c7a8325b86ca1102977cbfbe776b6013c31c4a78ddf7f16d7401933aeebf881d8aa47ac427a47a3f9ab28ed7ff539e5f5f4cc56c0dce074a7a3af2cdbc712d64
+  metadata.gz: 321e0e7efebc1c9dfabf68f8a41428634f342e42e089da13198c604753d75fe45c6284bf816e648dc7ca2031a09889e7ec838ffda67bb7838c690bea1d07c49c
+  data.tar.gz: 60e13ebceb420e9a8759b741391744163e28efa1ed30211914c73509f0501d835ab2a150027496af9624fa2559037ff0ff60d9026e1d33eb938bbabd2c926a1f

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-01-09
+
+### Added
+
+- **Webhook Validation**: Complete webhook signature verification and payload parsing
+  - `PayuPl::Webhooks::Validator` - Validates PayU webhook signatures and parses JSON payloads
+  - `PayuPl::Webhooks::Result` - Success/failure result object for webhook validation
+  - Support for all PayU signature algorithms: MD5, SHA1, SHA256, SHA384, SHA512
+  - Automatic detection and verification of both MD5 concatenation variants (body+key and key+body)
+  - Framework-agnostic design (works with Rails, Sinatra, Hanami, plain Rack)
+  - Optional logging for debugging webhook processing
+  - Constant-time signature comparison for security
+
+- **Configuration**: `PayuPl::Configuration#second_key` for webhook signature verification
+  - Three configuration methods: initializer, ENV variable, or direct parameter
+  - Automatic fallback from config → ENV → direct parameter
+
+- **Documentation**:
+  - Comprehensive webhook integration guide (`examples/WEBHOOK_GUIDE.md`)
+  - Rails controller example (`examples/webhooks_controller.rb`)
+  - Sinatra example (`examples/sinatra_webhook_example.rb`)
+  - Rack example (`examples/rack_webhook_example.ru`)
+  - Updated README with webhook section and best practices
+  - PayU IP addresses for webhook whitelisting (production + sandbox)
+  - PayU notification retry mechanism details (20 attempts over 72 hours)
+  - Official webhook header documentation
+  - Payment status lifecycle documentation
+
+- **Testing**: 25 comprehensive webhook tests
+  - Signature verification tests for all algorithms
+  - MD5 variant testing (both concatenation orders)
+  - Configuration priority testing
+  - Error handling and edge cases
+  - Logging behavior tests
+
+### Fixed
+
+- Amount display in logs now correctly converts from minor units to major currency units
+  - Example: `2900` (minor units) now displays as `29.00 PLN` (major units)
+  - Updated validator logs and example controllers
+
+### Dependencies
+
+- Added `rack ~> 3.0` to development dependencies for webhook testing
+
 ## [0.2.0] - 2025-12-31
 
 - Add Shop Data endpoint: `GET /api/v2_1/shops/{shopId}` (`Client#retrieve_shop_data`)

data/DOCUMENTATION_UPDATES.md

@@ -0,0 +1,144 @@
+# Documentation Updates Based on PayU Official Documentation
+
+## Changes Made
+
+Based on the official PayU webhook documentation, the following enhancements have been made to ensure complete alignment with PayU's specifications.
+
+### 1. Payment Status Clarifications
+
+Updated status descriptions to match official definitions:
+
+- **PENDING** - Payment is currently being processed
+- **WAITING_FOR_CONFIRMATION** - PayU is waiting for merchant to capture payment (when auto-receive is disabled) 
+- **COMPLETED** - Payment accepted, funds will be paid out shortly
+- **CANCELED** - Payment cancelled, buyer was not charged
+
+### 2. Retry Mechanism Documentation
+
+Added complete details about PayU's notification retry mechanism:
+- PayU expects **200 HTTP status code**
+- Up to **20 retry attempts** over 72 hours
+- Specific retry intervals documented (1min, 2min, 5min, 10min, 30min, 1hr, etc.)
+- Emphasis on returning 200 even if business logic fails
+
+### 3. IP Address Whitelisting
+
+Added official PayU IP addresses for webhook filtering:
+
+**Production:**
+- 185.68.12.10, 185.68.12.11, 185.68.12.12
+- 185.68.12.26, 185.68.12.27, 185.68.12.28
+
+**Sandbox:**
+- 185.68.14.10, 185.68.14.11, 185.68.14.12
+- 185.68.14.26, 185.68.14.27, 185.68.14.28
+
+### 4. Webhook Headers Documentation
+
+Documented all official PayU webhook headers:
+- `OpenPayu-Signature` (also sent as `X-OpenPayU-Signature`)
+- `Content-Type: application/json;charset=UTF-8`
+- `Authorization` - Basic auth credentials
+- `PayU-Processing-Time` - Processing duration in milliseconds
+
+Added example of signature header format:
+```
+OpenPayu-Signature: sender=checkout;signature=...;algorithm=MD5;content=DOCUMENT
+```
+
+### 5. Payload Structure Details
+
+Enhanced payload documentation with official field descriptions:
+
+- **localReceiptDateTime** - Only present for COMPLETED status
+- **properties[PAYMENT_ID]** - Transaction identifier (Trans ID in management panel)
+- **payMethod.type** - Payment method indicators:
+  - `PBL` - Online/standard transfer
+  - `CARD_TOKEN` - Card payment
+  - `INSTALLMENTS` - PayU Installments
+
+### 6. Best Practices Updates
+
+Enhanced best practices section:
+
+- **Duplicate Handling** - Added context about retry mechanism causing duplicates
+- **Status Codes** - Clarified critical importance of returning 200 OK
+- **Async Processing** - Emphasized responding quickly to avoid retries
+- Added code examples showing correct vs incorrect patterns
+
+### 7. Controller Example Enhancements
+
+Updated example controller with:
+- PayU-Processing-Time header logging for monitoring
+- Clarified WAITING_FOR_CONFIRMATION status handling
+- Better error handling examples
+- More detailed status case handling
+
+## Implementation Notes
+
+### What Works Perfectly
+
+✅ **Signature Verification** - Handles all PayU algorithms (MD5, SHA1, SHA256, SHA384, SHA512)
+✅ **MD5 Variants** - Automatically checks both `MD5(body+key)` and `MD5(key+body)` 
+✅ **Header Detection** - Works with both `OpenPayu-Signature` and `X-OpenPayU-Signature`
+✅ **Framework Agnostic** - Compatible with Rails, Sinatra, Hanami, plain Rack
+✅ **Logging Support** - Optional detailed logging for debugging
+✅ **Error Handling** - Clear error messages for all failure scenarios
+
+### Developer Experience Improvements
+
+1. **Flexible Configuration** - Three ways to set second_key (config, ENV, direct)
+2. **Simple API** - Clean success/failure result pattern
+3. **Comprehensive Examples** - Rails, Sinatra, Rack examples provided
+4. **Detailed Guide** - Step-by-step integration guide with troubleshooting
+5. **Full Test Coverage** - 25 webhook-specific tests, all passing
+
+## Files Updated
+
+### Documentation
+- `examples/WEBHOOK_GUIDE.md` - Added IP addresses, retry mechanism, headers info
+- `README.md` - Added best practices summary and IP addresses
+- `examples/webhooks_controller.rb` - Enhanced with monitoring and better comments
+
+### No Code Changes Required
+
+The webhook validator implementation already correctly handles:
+- All PayU signature algorithms
+- Both MD5 concatenation variants
+- Proper header parsing (signature format with semicolons)
+- Request body preservation for multiple reads
+- Constant-time signature comparison for security
+
+## Verification
+
+All tests pass (70 total, 25 webhook-specific):
+```
+PayuPl::Webhooks::Validator
+  ✓ #initialize (4 examples)
+  ✓ #verify_signature! (7 examples)
+  ✓ #parse_payload (2 examples)
+  ✓ #validate_and_parse (4 examples)
+  ✓ logging (2 examples)
+
+PayuPl::Webhooks::Result
+  ✓ All result object behaviors (6 examples)
+```
+
+## Next Steps for Users
+
+When integrating webhooks, users should:
+
+1. Get second_key from PayU merchant panel (Settings → POS Configuration)
+2. Configure second_key in their application
+3. Set up webhook endpoint (see examples)
+4. Configure notifyUrl in PayU to point to their endpoint
+5. Optional: Whitelist PayU IPs if using IP filtering
+6. Test with PayU sandbox before production
+7. Monitor PayU-Processing-Time header for performance insights
+
+## References
+
+All documentation updates are based on official PayU documentation:
+- PayU API Reference: https://developers.payu.com/europe/api/
+- Webhook Documentation: https://developers.payu.com/europe/docs/webhooks/
+- Payment Lifecycle: https://developers.payu.com/europe/docs/payment-lifecycle/

data/README.md

@@ -112,6 +112,155 @@ client.retrieve_refund(order_id, "5000000142")
 client.retrieve_transactions(order_id)
 ```
 
+### Webhook validation
+
+PayU sends webhook notifications when order status changes. This gem provides a validator to verify webhook signatures and parse payloads.
+
+#### Basic usage in Rails
+
+```ruby
+# config/routes.rb
+post '/webhooks/payu', to: 'webhooks/payu#create'
+
+# app/controllers/webhooks/payu_controller.rb
+class Webhooks::PayuController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    result = PayuPl::Webhooks::Validator.new(request).validate_and_parse
+    
+    if result.failure?
+      Rails.logger.error("PayU webhook validation failed: #{result.error}")
+      return head :bad_request
+    end
+
+    payload = result.data
+    order_id = payload.dig('order', 'orderId')
+    status = payload.dig('order', 'status')
+    
+    # Process the webhook...
+    # (check for duplicates, enqueue background job, etc.)
+    
+    head :ok
+  end
+end
+```
+
+#### Configuration
+
+Set your PayU second key (MD5 key) in one of three ways:
+
+```ruby
+# 1. Via initializer (recommended)
+# config/initializers/payu.rb
+PayuPl.configure do |config|
+  config.second_key = ENV.fetch('PAYU_SECOND_KEY')
+end
+
+# 2. Via ENV variable (automatic fallback)
+ENV['PAYU_SECOND_KEY'] = 'your_second_key'
+
+# 3. Pass directly to validator
+validator = PayuPl::Webhooks::Validator.new(request, second_key: 'custom_key')
+```
+
+#### With custom logger
+
+```ruby
+logger = Logger.new(STDOUT)
+validator = PayuPl::Webhooks::Validator.new(request, logger: logger)
+result = validator.validate_and_parse
+```
+
+#### Validation only (without parsing)
+
+```ruby
+validator = PayuPl::Webhooks::Validator.new(request)
+
+begin
+  validator.verify_signature!
+  # Signature is valid
+rescue => e
+  # Signature validation failed
+  Rails.logger.error("Invalid signature: #{e.message}")
+end
+```
+
+#### Result object
+
+The validator returns a `PayuPl::Webhooks::Result` object:
+
+```ruby
+result = validator.validate_and_parse
+
+if result.success?
+  payload = result.data
+  # Access webhook data
+  order_id = payload.dig('order', 'orderId')
+  status = payload.dig('order', 'status')
+  
+  # Convert amount from minor units (2900 = 29.00 PLN)
+  total_amount = payload.dig('order', 'totalAmount').to_i / 100.0
+  currency = payload.dig('order', 'currencyCode')
+else
+  error_message = result.error
+  # Handle validation error
+end
+```
+
+#### Signature algorithms
+
+PayU supports multiple signature algorithms (MD5, SHA1, SHA256, SHA384, SHA512). The validator automatically detects the algorithm from the webhook header and verifies accordingly.
+
+For MD5, PayU may use either `MD5(body + key)` or `MD5(key + body)`. The validator checks both variants automatically.
+
+#### Important: Webhook Best Practices
+
+1. **Always return 200 OK** - After signature validation, return 200 even if processing fails
+2. **Handle duplicates** - PayU retries up to 20 times if you don't return 200
+3. **Process asynchronously** - Store webhook and process in background job
+4. **IP Whitelisting** (optional) - Allow PayU IPs:
+   - Production: `185.68.12.10-12`, `185.68.12.26-28`
+   - Sandbox: `185.68.14.10-12`, `185.68.14.26-28`
+
+See `examples/WEBHOOK_GUIDE.md` for comprehensive integration guide.
+
+#### Non-Rails frameworks
+
+The validator works with any Rack-compatible request object:
+
+```ruby
+# Sinatra
+post '/webhooks/payu' do
+  result = PayuPl::Webhooks::Validator.new(request).validate_and_parse
+  
+  if result.success?
+    # Process webhook
+    status 200
+  else
+    status 400
+  end
+end
+
+# Hanami
+module Web::Controllers::Webhooks
+  class Payu
+    include Web::Action
+
+    def call(params)
+      result = PayuPl::Webhooks::Validator.new(request).validate_and_parse
+      
+      if result.success?
+        # Process webhook
+        self.status = 200
+      else
+        self.status = 400
+      end
+    end
+  end
+end
+```
+
 ### Retrieve shop data
 
 ```ruby

data/WEBHOOK_INTEGRATION_SUMMARY.md

@@ -0,0 +1,153 @@
+# PayU Webhook Integration - Summary
+
+## What Was Added
+
+This integration adds webhook validation capabilities to the `payu_pl` gem, allowing you to securely process PayU webhook notifications in any Ruby application.
+
+## Files Created
+
+### Core Library
+- `lib/payu_pl/webhooks/result.rb` - Result object for success/failure responses
+- `lib/payu_pl/webhooks/validator.rb` - Main webhook validator class
+- `lib/payu_pl/configuration.rb` - Updated to support `second_key` configuration
+
+### Tests
+- `spec/webhooks/result_spec.rb` - Tests for Result class (6 examples)
+- `spec/webhooks/validator_spec.rb` - Tests for Validator class (19 examples)
+- All tests passing (70 total examples)
+
+### Examples & Documentation
+- `examples/WEBHOOK_GUIDE.md` - Comprehensive integration guide
+- `examples/webhooks_controller.rb` - Rails controller example
+- `examples/sinatra_webhook_example.rb` - Sinatra example
+- `examples/rack_webhook_example.ru` - Plain Rack example
+- `README.md` - Updated with webhook section
+
+## Key Features
+
+### 1. Flexible Configuration
+```ruby
+# Option 1: Via configuration
+PayuPl.configure do |config|
+  config.second_key = ENV.fetch('PAYU_SECOND_KEY')
+end
+
+# Option 2: Via ENV (automatic)
+ENV['PAYU_SECOND_KEY'] = 'your_key'
+
+# Option 3: Pass directly
+validator = PayuPl::Webhooks::Validator.new(request, second_key: 'key')
+```
+
+### 2. Framework Agnostic
+Works with any Rack-compatible framework:
+- Rails
+- Sinatra
+- Hanami
+- Roda
+- Plain Rack
+
+### 3. Comprehensive Signature Validation
+Supports all PayU signature algorithms:
+- MD5 (with both key+body and body+key variants)
+- SHA1, SHA256, SHA384, SHA512
+
+### 4. Optional Logging
+```ruby
+validator = PayuPl::Webhooks::Validator.new(request, logger: Rails.logger)
+```
+
+Logs:
+- Signature verification steps
+- Algorithm details
+- Payload parsing
+- Errors and backtraces
+
+### 5. Simple API
+```ruby
+result = validator.validate_and_parse
+
+if result.success?
+  payload = result.data
+  # Process webhook...
+else
+  error = result.error
+  # Handle error...
+end
+```
+
+## Usage in Your Controller
+
+```ruby
+class Webhooks::PayuController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    result = PayuPl::Webhooks::Validator.new(request).validate_and_parse
+    
+    if result.failure?
+      return head :bad_request
+    end
+
+    payload = result.data
+    order_id = payload.dig('order', 'orderId')
+    status = payload.dig('order', 'status')
+    
+    # Process webhook...
+    
+    head :ok
+  end
+end
+```
+
+## Security Features
+
+1. **Constant-time signature comparison** - Prevents timing attacks
+2. **Multi-algorithm support** - Automatic algorithm detection
+3. **Configurable secret key** - Flexible configuration options
+4. **Request body preservation** - Can read body multiple times
+5. **Comprehensive error handling** - Clear error messages
+
+## Testing
+
+All webhook functionality is fully tested:
+- ✅ Configuration options (ENV, config, direct)
+- ✅ Signature verification (all algorithms)
+- ✅ MD5 variants (body+key and key+body)
+- ✅ Payload parsing
+- ✅ Error handling
+- ✅ Logging behavior
+- ✅ Result object behavior
+
+## Dependencies
+
+Added to Gemfile for testing:
+- `rack ~> 3.0` - For Rack::Request in tests
+
+No additional runtime dependencies required.
+
+## Next Steps
+
+1. ✅ Webhook validation implemented
+2. ✅ Comprehensive tests written
+3. ✅ Documentation created
+4. ✅ Examples provided
+5. 🔄 Ready for use!
+
+## Integration Checklist
+
+For users wanting to integrate webhooks:
+
+- [ ] Get PayU second_key from merchant panel
+- [ ] Configure second_key (ENV or initializer)
+- [ ] Create webhook controller/endpoint
+- [ ] Add route for webhook
+- [ ] Test with PayU sandbox
+- [ ] Deploy and configure notifyUrl in PayU
+- [ ] Monitor webhook logs
+
+## Links
+
+- See `examples/WEBHOOK_GUIDE.md` for detailed integration guide
+- See `examples/webhooks_controller.rb` for Rails example
+- See `README.md` for API documentation