payu_pl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b782044448418c46fdc1576fc1e2a8b1c3855930e4758dfb692ca5707accc4e2
+  data.tar.gz: 18f16cc358d142bd54bd2ed9c696e4ee4300686e47cee7502bf104ca4f0558d5
+SHA512:
+  metadata.gz: 93a1fc0a92eb1031ad67cb93aef28f2997a48f500fb4d8d3353bbcb55c2b389b01c67e88cd0612c227ce337e421984921469149f212d1e3b03ea8a2b123750b9
+  data.tar.gz: 3e40a0fe16dbbf8e83e5ce7bde53697f1273f34f3c5b1705174d40d9232a365f4466b2feb4667545d4a89ae6e11e37ee417fcdf3f22518d357f5fd1704137d24

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-30
+
+- Add i18n-backed validation messages (English + Polish) and `PayuPl.configure` locale support
+- DRY up ID validation in operations (`validate_id!` / `validate_ids!` in base)
+- Split specs into multiple focused files and expand coverage
+- Add PayU documentation links to README
+- Consolidate CI workflows (single `ci.yml`)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dmytro Koval
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# PayuPl
+
+A small Ruby client for the PayU GPO Europe REST API (commonly used for PayU Poland integrations), with:
+
+- `Net::HTTP` transport
+- consistent error mapping
+- basic request validation via `dry-validation`
+
+This gem focuses on the standard payment flow endpoints:
+
+- OAuth token
+- Create / retrieve order
+- Capture / cancel
+- Refunds
+- Transaction retrieve
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "payu_pl"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Create a client
+
+```ruby
+client = PayuPl::Client.new(
+  client_id: ENV.fetch("PAYU_CLIENT_ID"),
+  client_secret: ENV.fetch("PAYU_CLIENT_SECRET"),
+  environment: :sandbox # or :production
+)
+```
+
+### Authenticate (OAuth)
+
+```ruby
+client.oauth_token
+# => {"access_token"=>"...", "token_type"=>"bearer", "expires_in"=>43199, ...}
+```
+
+The token is stored on the client as `client.access_token` and used automatically for subsequent calls.
+
+### Create an order
+
+```ruby
+payload = {
+  notifyUrl: "https://example.com/payu/notify",
+  customerIp: "127.0.0.1",
+  merchantPosId: ENV.fetch("PAYU_POS_ID"),
+  description: "RTV market",
+  currencyCode: "PLN",
+  totalAmount: "21000",
+  products: [
+    { name: "Wireless Mouse", unitPrice: "21000", quantity: "1" }
+  ]
+}
+
+response = client.create_order(payload)
+redirect_uri = response["redirectUri"]
+order_id = response["orderId"]
+```
+
+Notes:
+
+- `totalAmount` / `unitPrice` are strings in minor units.
+- PayU often responds with HTTP `302` and JSON body; this client does not auto-follow redirects.
+
+### Retrieve an order
+
+```ruby
+client.retrieve_order(order_id)
+```
+
+### Capture / cancel
+
+```ruby
+client.capture_order(order_id) # full capture (empty JSON body)
+
+client.capture_order(order_id, amount: "1000", currency_code: "PLN") # partial capture
+
+client.cancel_order(order_id)
+```
+
+### Refunds
+
+```ruby
+client.create_refund(order_id, description: "Refund")
+client.create_refund(order_id, description: "Partial refund", amount: "1000")
+
+client.list_refunds(order_id)
+client.retrieve_refund(order_id, "5000000142")
+```
+
+### Retrieve transactions
+
+```ruby
+client.retrieve_transactions(order_id)
+```
+
+## Errors and validation
+
+HTTP errors are mapped to Ruby exceptions:
+
+- `PayuPl::UnauthorizedError` (401)
+- `PayuPl::ForbiddenError` (403)
+- `PayuPl::NotFoundError` (404)
+- `PayuPl::RateLimitedError` (429)
+- `PayuPl::ClientError` (other 4xx)
+- `PayuPl::ServerError` (5xx)
+
+They carry useful fields like `http_status`, `correlation_id`, `raw_body`, and `parsed_body`.
+
+Request validation errors raise `PayuPl::ValidationError` and include an `errors` hash.
+
+## PayU documentation
+
+Useful official resources:
+
+- PayU GPO Europe docs: https://developers.payu.com/europe/docs/
+- REST API reference (OpenAPI): https://developers.payu.com/europe/api/
+- OpenAPI YAML download: https://developers.payu.com/europe/resources/payu-gpo-europe-api-ref.yaml
+- Sandbox testing guide: https://developers.payu.com/europe/docs/testing/sandbox/
+- Sandbox registration: https://registration-merch-prod.snd.payu.com/boarding/#/registerSandbox/
+- Sandbox status page: https://status.snd.payu.com/
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rspec
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  payu_pl:
+    validation:
+      max_length: "must be at most %{max} characters"
+      ip_address: "must be a valid IPv4 or IPv6 address"
+      iso_4217: "must be a 3-letter ISO 4217 code"
+      numeric_string: "must be a numeric string"
+      min_items: "must include at least %{min} item(s)"
+      required_with_currency_code: "is required when providing currency_code"
+      required_with_amount: "is required when providing amount"

data/config/locales/pl.yml

@@ -0,0 +1,10 @@
+pl:
+  payu_pl:
+    validation:
+      max_length: "musi mieć maksymalnie %{max} znaków"
+      ip_address: "musi być poprawnym adresem IPv4 lub IPv6"
+      iso_4217: "musi być 3-literowym kodem ISO 4217"
+      numeric_string: "musi być ciągiem cyfr"
+      min_items: "musi zawierać co najmniej %{min} element(y)"
+      required_with_currency_code: "jest wymagane, gdy podano currency_code"
+      required_with_amount: "jest wymagane, gdy podano amount"

data/lib/payu_pl/authorize/oauth_token.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Authorize
+    class OAuthToken < Operations::Base
+      def call(grant_type: "client_credentials")
+        form = {
+          grant_type: grant_type,
+          client_id: client.client_id,
+          client_secret: client.client_secret
+        }
+
+        response = transport.request(
+          :post,
+          Endpoints::OAUTH_TOKEN,
+          headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+          form: form,
+          authorize: false
+        )
+
+        token = response.fetch("access_token")
+        client.access_token = token
+        response
+      end
+    end
+  end
+end

data/lib/payu_pl/client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module PayuPl
+  class Client
+    DEFAULT_PRODUCTION_BASE_URL = "https://secure.payu.com"
+    DEFAULT_SANDBOX_BASE_URL = "https://secure.snd.payu.com"
+
+    attr_reader :base_url, :client_id, :client_secret, :transport
+    attr_accessor :access_token
+
+    def initialize(
+      client_id:,
+      client_secret:,
+      access_token: nil,
+      base_url: nil,
+      environment: :production,
+      open_timeout: 10,
+      read_timeout: 30
+    )
+      @client_id = client_id
+      @client_secret = client_secret
+      @access_token = access_token
+
+      @base_url = base_url || default_base_url_for(environment)
+      validate!
+
+      @transport = Transport.new(
+        base_url: @base_url,
+        access_token_provider: -> { @access_token },
+        open_timeout: open_timeout,
+        read_timeout: read_timeout
+      )
+    end
+
+    # OAuth
+    def oauth_token(grant_type: "client_credentials")
+      Authorize::OAuthToken.new(client: self).call(grant_type: grant_type)
+    end
+
+    # Orders
+    def create_order(order_create_request)
+      Orders::Create.new(client: self).call(order_create_request)
+    end
+
+    def retrieve_order(order_id)
+      Orders::Retrieve.new(client: self).call(order_id)
+    end
+
+    def capture_order(order_id, amount: nil, currency_code: nil)
+      Orders::Capture.new(client: self).call(order_id, amount: amount, currency_code: currency_code)
+    end
+
+    def cancel_order(order_id)
+      Orders::Cancel.new(client: self).call(order_id)
+    end
+
+    def retrieve_transactions(order_id)
+      Orders::Transactions.new(client: self).call(order_id)
+    end
+
+    # Refunds
+    def create_refund(order_id, description:, amount: nil, ext_refund_id: nil)
+      Refunds::Create.new(client: self).call(order_id, description: description, amount: amount, ext_refund_id: ext_refund_id)
+    end
+
+    def list_refunds(order_id)
+      Refunds::List.new(client: self).call(order_id)
+    end
+
+    def retrieve_refund(order_id, refund_id)
+      Refunds::Retrieve.new(client: self).call(order_id, refund_id)
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "client_id is required" if client_id.nil? || client_id.to_s.empty?
+      raise ArgumentError, "client_secret is required" if client_secret.nil? || client_secret.to_s.empty?
+
+      uri = URI.parse(base_url)
+      raise ArgumentError, "base_url must be http(s)" unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url is invalid"
+    end
+
+    def default_base_url_for(environment)
+      case environment&.to_sym
+      when :production
+        DEFAULT_PRODUCTION_BASE_URL
+      when :sandbox
+        DEFAULT_SANDBOX_BASE_URL
+      else
+        raise ArgumentError, "Unknown environment: #{environment.inspect} (use :production or :sandbox)"
+      end
+    end
+  end
+end

data/lib/payu_pl/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+module PayuPl
+  class Configuration
+    attr_accessor :locale
+
+    def initialize
+      @locale = :en
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  def self.load_translations!
+    locales_glob = File.expand_path("../../config/locales/*.yml", __dir__)
+    I18n.load_path |= Dir[locales_glob]
+
+    # Ensure the backend actually loads newly added paths.
+    I18n.backend.load_translations
+
+    # Do not overwrite user's configuration, only extend.
+    I18n.available_locales = (I18n.available_locales | %i[en pl])
+  end
+
+  def self.t(key, **opts)
+    I18n.t(key, **opts, scope: %i[payu_pl validation], locale: config.locale)
+  end
+end
+
+PayuPl.load_translations!

data/lib/payu_pl/contracts/capture_contract.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module PayuPl
+  module Contracts
+    class CaptureContract < Dry::Validation::Contract
+      params do
+        required(:order_id).filled(:string)
+        optional(:amount).maybe(:string)
+        optional(:currency_code).maybe(:string)
+      end
+
+      rule(:amount, :currency_code) do
+        amount_raw = values[:amount]
+        currency_raw = values[:currency_code]
+
+        amount = amount_raw.is_a?(String) ? amount_raw.strip : amount_raw
+        currency_code = currency_raw.is_a?(String) ? currency_raw.strip : currency_raw
+
+        amount_present = !(amount.nil? || (amount.respond_to?(:empty?) && amount.empty?))
+        currency_present = !(currency_code.nil? || (currency_code.respond_to?(:empty?) && currency_code.empty?))
+
+        next if !amount_present && !currency_present
+
+        key(:amount).failure(PayuPl.t(:required_with_currency_code)) if currency_present && !amount_present
+        key(:currency_code).failure(PayuPl.t(:required_with_amount)) if amount_present && !currency_present
+
+        key(:currency_code).failure(PayuPl.t(:iso_4217)) if currency_present && !currency_code.match?(/\A[A-Z]{3}\z/)
+
+        key(:amount).failure(PayuPl.t(:numeric_string)) if amount_present && !amount.to_s.match?(/\A\d+\z/)
+      end
+    end
+  end
+end

data/lib/payu_pl/contracts/id_contract.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module PayuPl
+  module Contracts
+    class IdContract < Dry::Validation::Contract
+      params do
+        required(:id).filled(:string)
+      end
+    end
+  end
+end

data/lib/payu_pl/contracts/order_create_contract.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require "ipaddr"
+
+module PayuPl
+  module Contracts
+    class OrderCreateContract < Dry::Validation::Contract
+      IPV4_SEGMENT = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)"
+      IPV4_REGEX = /\A#{IPV4_SEGMENT}(?:\.#{IPV4_SEGMENT}){3}\z/.freeze
+
+      params do
+        optional(:continueUrl).filled(:string)
+        optional(:notifyUrl).filled(:string)
+
+        required(:customerIp).filled(:string)
+        required(:merchantPosId).filled(:string)
+        required(:description).filled(:string)
+
+        optional(:additionalDescription).filled(:string)
+        optional(:visibleDescription).filled(:string)
+        optional(:statementDescription).filled(:string)
+        optional(:extOrderId).filled(:string)
+
+        required(:currencyCode).filled(:string)
+        required(:totalAmount).filled(:string)
+
+        required(:products).array(:hash) do
+          required(:name).filled(:string)
+          required(:unitPrice).filled(:string)
+          required(:quantity).filled(:string)
+        end
+      end
+
+      rule(:continueUrl) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 1024)) if value.length > 1024
+      end
+
+      rule(:notifyUrl) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 1024)) if value.length > 1024
+      end
+
+      rule(:customerIp) do
+        ip = value.to_s
+
+        ipv4 = IPV4_REGEX.match?(ip)
+        ipv6 = begin
+          addr = IPAddr.new(ip)
+          addr.ipv6? && ip.include?(":")
+        rescue IPAddr::InvalidAddressError
+          false
+        end
+
+        key.failure(PayuPl.t(:ip_address)) unless ipv4 || ipv6
+      end
+
+      rule(:description) do
+        key.failure(PayuPl.t(:max_length, max: 4000)) if value.length > 4000
+      end
+
+      rule(:additionalDescription) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 1024)) if value.length > 1024
+      end
+
+      rule(:visibleDescription) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 80)) if value.length > 80
+      end
+
+      rule(:statementDescription) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 22)) if value.length > 22
+      end
+
+      rule(:extOrderId) do
+        next if value.nil?
+
+        key.failure(PayuPl.t(:max_length, max: 1024)) if value.length > 1024
+      end
+
+      rule(:currencyCode) do
+        code = value
+        key.failure(PayuPl.t(:iso_4217)) unless code.match?(/\A[A-Z]{3}\z/)
+      end
+
+      rule(:totalAmount) do
+        # API uses a string containing minor units
+        key.failure(PayuPl.t(:numeric_string)) unless value.match?(/\A\d+\z/)
+      end
+
+      rule(:products) do
+        key.failure(PayuPl.t(:min_items, min: 1)) if value.nil? || value.empty?
+      end
+
+      rule(:products).each do
+        unit_price = value[:unitPrice]
+        quantity = value[:quantity]
+
+        key(:unitPrice).failure(PayuPl.t(:numeric_string)) if unit_price && !unit_price.match?(/\A\d+\z/)
+
+        key(:quantity).failure(PayuPl.t(:numeric_string)) if quantity && !quantity.match?(/\A\d+\z/)
+      end
+    end
+  end
+end