payu_pl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b782044448418c46fdc1576fc1e2a8b1c3855930e4758dfb692ca5707accc4e2
-  data.tar.gz: 18f16cc358d142bd54bd2ed9c696e4ee4300686e47cee7502bf104ca4f0558d5
+  metadata.gz: a3153797e232dc9495c8f175f37558a8f360688b9f53e311cf925652a55db620
+  data.tar.gz: ca4dcc6531dec57bbc908c39cd5dd801d8fb9e5e33de22eca1df876e40abdd8e
 SHA512:
-  metadata.gz: 93a1fc0a92eb1031ad67cb93aef28f2997a48f500fb4d8d3353bbcb55c2b389b01c67e88cd0612c227ce337e421984921469149f212d1e3b03ea8a2b123750b9
-  data.tar.gz: 3e40a0fe16dbbf8e83e5ce7bde53697f1273f34f3c5b1705174d40d9232a365f4466b2feb4667545d4a89ae6e11e37ee417fcdf3f22518d357f5fd1704137d24
+  metadata.gz: 144220b42c84c7745c1f41755afe6c118bf9b0d2b06567abdea30ab21403341c7991525f914e70da3f971781ae4944d66b22cb6826603c4fcf96f18a2c88f1c8
+  data.tar.gz: c7a8325b86ca1102977cbfbe776b6013c31c4a78ddf7f16d7401933aeebf881d8aa47ac427a47a3f9ab28ed7ff539e5f5f4cc56c0dce074a7a3af2cdbc712d64

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-12-31
+
+- Add Shop Data endpoint: `GET /api/v2_1/shops/{shopId}` (`Client#retrieve_shop_data`)
+- Add Payouts endpoints: `POST /api/v2_1/payouts`, `GET /api/v2_1/payouts/{payoutId}` (`Client#create_payout`, `Client#retrieve_payout`)
+- Add Statements endpoint: `GET /api/v2_1/reports/{reportId}` (`Client#retrieve_statement`) returning binary `data` + extracted `filename`
+- Extend `Transport#request` with `return_headers:` to expose response headers for binary downloads
+- Update README and RBS, and add client specs for the new endpoints
+
 ## [0.1.0] - 2025-12-30
 
 - Add i18n-backed validation messages (English + Polish) and `PayuPl.configure` locale support

data/README.md

@@ -14,6 +14,12 @@ This gem focuses on the standard payment flow endpoints:
 - Refunds
 - Transaction retrieve
 
+Additional supported areas:
+
+- Retrieve Shop Data
+- Payouts
+- Statements
+
 ## Installation
 
 Add to your Gemfile:
@@ -106,6 +112,78 @@ client.retrieve_refund(order_id, "5000000142")
 client.retrieve_transactions(order_id)
 ```
 
+### Retrieve shop data
+
+```ruby
+client.retrieve_shop_data("SHOP_ID")
+```
+
+### Payouts
+
+PayU supports multiple payout request schemas (Standard Payout, Bank Account Payout, Card Payout, Payout for Marketplace, FxPayout).
+This client sends the JSON payload as-is, so your request must match one of the schemas from PayU docs.
+
+Note: Payouts are a permissioned product in PayU. If your POS/shop is not enabled for payouts (common in sandbox or without the right agreement), PayU may respond with HTTP `403` (e.g. `ERROR_VALUE_INVALID` / "Permission denied for given action").
+
+```ruby
+# Standard Payout
+standard_payout = {
+  shopId: "1a2B3Cx",
+  payout: {
+    extPayoutId: "payout-123",
+    amount: 10_000,
+    description: "Payout"
+  }
+}
+
+# Bank Account Payout
+bank_account_payout = {
+  shopId: "1a2B3Cx",
+  payout: { extPayoutId: "payout-124", amount: 10_000, description: "Payout" },
+  account: { accountNumber: "PL61109010140000071219812874" },
+  customerAddress: { name: "Jane Doe" }
+}
+
+# Card Payout (use either cardToken or card)
+card_payout = {
+  shopId: "1a2B3Cx",
+  payout: { extPayoutId: "payout-125", amount: 10_000, description: "Payout" },
+  payee: { extCustomerId: "customer-id-1", accountCreationDate: "2025-03-27T00:00:00.000Z", email: "email@email.com" },
+  customerAddress: { name: "Jane Doe" },
+  cardToken: "TOKC_..."
+}
+
+# Payout for Marketplace
+marketplace_payout = {
+  shopId: "1a2B3Cx",
+  account: { extCustomerId: "submerchant1" },
+  payout: { extPayoutId: "payout-126", amount: 10_000, currencyCode: "PLN", description: "Payout" }
+}
+
+# FxPayout
+fx_payout = {
+  shopId: "1a2B3Cx",
+  account: { extCustomerId: "submerchant1" },
+  payout: { extPayoutId: "payout-127", amount: 10_000, currencyCode: "PLN", description: "Payout" },
+  fxData: { partnerId: "...", currencyCode: "EUR", amount: 2500, rate: 0.25, tableId: "2055" }
+}
+
+client.create_payout(standard_payout)
+client.retrieve_payout("PAYOUT_ID")
+```
+
+### Statements
+
+This endpoint returns binary data and includes filename metadata from `Content-Disposition`.
+
+```ruby
+statement = client.retrieve_statement("REPORT_ID")
+# => { data: "...", filename: "...", content_type: "...", http_status: 200 }
+
+safe_filename = File.basename(statement.fetch(:filename)).gsub(/[^0-9A-Za-z.\-]/, "_")
+File.binwrite(safe_filename, statement.fetch(:data))
+```
+
 ## Errors and validation
 
 HTTP errors are mapped to Ruby exceptions:

data/config/locales/en.yml

@@ -1,6 +1,7 @@
 en:
   payu_pl:
     validation:
+      hash: "must be a hash"
       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"

data/config/locales/pl.yml

@@ -1,6 +1,7 @@
 pl:
   payu_pl:
     validation:
+      hash: "musi być hashem"
       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"

data/lib/payu_pl/client.rb

@@ -73,6 +73,25 @@ module PayuPl
       Refunds::Retrieve.new(client: self).call(order_id, refund_id)
     end
 
+    # Shops
+    def retrieve_shop_data(shop_id)
+      Shops::Retrieve.new(client: self).call(shop_id)
+    end
+
+    # Payouts
+    def create_payout(payout_request)
+      Payouts::Create.new(client: self).call(payout_request)
+    end
+
+    def retrieve_payout(payout_id)
+      Payouts::Retrieve.new(client: self).call(payout_id)
+    end
+
+    # Statements
+    def retrieve_statement(report_id)
+      Statements::Retrieve.new(client: self).call(report_id)
+    end
+
     private
 
     def validate!

data/lib/payu_pl/contracts/order_create_contract.rb

@@ -25,10 +25,13 @@ module PayuPl
         required(:currencyCode).filled(:string)
         required(:totalAmount).filled(:string)
 
+        optional(:validityTime).filled(:string)
+
         required(:products).array(:hash) do
           required(:name).filled(:string)
           required(:unitPrice).filled(:string)
           required(:quantity).filled(:string)
+          optional(:virtual).filled(:bool)
         end
       end
 
@@ -96,6 +99,13 @@ module PayuPl
         key.failure(PayuPl.t(:numeric_string)) unless value.match?(/\A\d+\z/)
       end
 
+      rule(:validityTime) do
+        next if value.nil?
+
+        # OpenAPI: string containing seconds
+        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

data/lib/payu_pl/contracts/payout_create_contract.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module PayuPl
+  module Contracts
+    class PayoutCreateContract < Dry::Validation::Contract
+      params do
+        required(:payload).filled
+      end
+
+      rule(:payload) do
+        val = value
+
+        unless val.is_a?(Hash)
+          key.failure(PayuPl.t(:hash))
+          next
+        end
+
+        key.failure(PayuPl.t(:min_items, min: 1)) if val.empty?
+      end
+    end
+  end
+end

data/lib/payu_pl/endpoints.rb

@@ -8,6 +8,10 @@ module PayuPl
 
     ORDERS = "/api/v2_1/orders"
 
+    SHOPS = "/api/v2_1/shops"
+    PAYOUTS = "/api/v2_1/payouts"
+    REPORTS = "/api/v2_1/reports"
+
     def self.order(order_id)
       "#{ORDERS}/#{URI.encode_www_form_component(order_id.to_s)}"
     end
@@ -27,5 +31,17 @@ module PayuPl
     def self.order_refund(order_id, refund_id)
       "#{order_refunds(order_id)}/#{URI.encode_www_form_component(refund_id.to_s)}"
     end
+
+    def self.shop(shop_id)
+      "#{SHOPS}/#{URI.encode_www_form_component(shop_id.to_s)}"
+    end
+
+    def self.payout(payout_id)
+      "#{PAYOUTS}/#{URI.encode_www_form_component(payout_id.to_s)}"
+    end
+
+    def self.report(report_id)
+      "#{REPORTS}/#{URI.encode_www_form_component(report_id.to_s)}"
+    end
   end
 end

data/lib/payu_pl/payouts/create.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Payouts
+    class Create < Operations::Base
+      def call(payout_request)
+        validate_contract!(Contracts::PayoutCreateContract, { payload: payout_request }, input: payout_request)
+
+        # Do NOT use result.to_h here: dry-schema would drop unknown keys, and PayU supports multiple payout schemas.
+        transport.request(:post, Endpoints::PAYOUTS, json: payout_request)
+      end
+    end
+  end
+end

data/lib/payu_pl/payouts/retrieve.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Payouts
+    class Retrieve < Operations::Base
+      def call(payout_id)
+        validate_id!(payout_id, input_key: :payout_id)
+        transport.request(:get, Endpoints.payout(payout_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/shops/retrieve.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Shops
+    class Retrieve < Operations::Base
+      def call(shop_id)
+        validate_id!(shop_id, input_key: :shop_id)
+        transport.request(:get, Endpoints.shop(shop_id))
+      end
+    end
+  end
+end

data/lib/payu_pl/statements/retrieve.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PayuPl
+  module Statements
+    class Retrieve < Operations::Base
+      FILENAME_REGEX = /filename="?(?<filename>[^";]+)"?/i.freeze
+
+      def call(report_id)
+        validate_id!(report_id, input_key: :report_id)
+
+        response = transport.request(
+          :get,
+          Endpoints.report(report_id),
+          headers: { "Accept" => "application/octet-stream" },
+          return_headers: true
+        )
+
+        headers = response.fetch(:headers)
+        content_type = headers["content-type"]
+        content_disposition = headers["content-disposition"].to_s
+
+        filename = content_disposition.match(FILENAME_REGEX)&.named_captures&.fetch("filename", nil)
+
+        {
+          data: response.fetch(:body),
+          filename: filename,
+          content_type: content_type,
+          http_status: response.fetch(:http_status)
+        }
+      end
+    end
+  end
+end

data/lib/payu_pl/transport.rb

@@ -15,7 +15,7 @@ module PayuPl
       validate!
     end
 
-    def request(method, path, headers: {}, json: :__no_json_argument_given, form: nil, authorize: true)
+    def request(method, path, headers: {}, json: :__no_json_argument_given, form: nil, authorize: true, return_headers: false)
       uri = URI.join(@base_url, path)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == "https")
@@ -66,7 +66,7 @@ module PayuPl
         raise NetworkError.new("Network failure", original: e)
       end
 
-      handle_response(res)
+      handle_response(res, return_headers: return_headers)
     end
 
     private
@@ -78,13 +78,21 @@ module PayuPl
       raise ArgumentError, "base_url is invalid"
     end
 
-    def handle_response(res)
+    def handle_response(res, return_headers: false)
       http_status = res.code.to_i
       correlation_id = res["Correlation-Id"] || res["correlation-id"]
       raw_body = res.body
       parsed = parse_body(res)
 
-      return parsed if http_status >= 200 && http_status < 400
+      if http_status >= 200 && http_status < 400
+        return parsed unless return_headers
+
+        return {
+          body: parsed,
+          headers: extract_headers(res),
+          http_status: http_status
+        }
+      end
 
       message = build_error_message(http_status, parsed, raw_body)
 
@@ -107,6 +115,14 @@ module PayuPl
       )
     end
 
+    def extract_headers(res)
+      return {} unless res.respond_to?(:each_header)
+
+      headers = {}
+      res.each_header { |k, v| headers[k.to_s.downcase] = v }
+      headers
+    end
+
     def parse_body(res)
       body = res.body
       return nil if body.nil? || body.empty?

data/lib/payu_pl/version.rb

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

data/lib/payu_pl.rb

@@ -12,6 +12,7 @@ require_relative "payu_pl/contracts/order_create_contract"
 require_relative "payu_pl/contracts/id_contract"
 require_relative "payu_pl/contracts/capture_contract"
 require_relative "payu_pl/contracts/refund_create_contract"
+require_relative "payu_pl/contracts/payout_create_contract"
 
 require_relative "payu_pl/authorize/oauth_token"
 
@@ -24,6 +25,13 @@ require_relative "payu_pl/orders/transactions"
 require_relative "payu_pl/refunds/create"
 require_relative "payu_pl/refunds/list"
 require_relative "payu_pl/refunds/retrieve"
+
+require_relative "payu_pl/shops/retrieve"
+
+require_relative "payu_pl/payouts/create"
+require_relative "payu_pl/payouts/retrieve"
+
+require_relative "payu_pl/statements/retrieve"
 require_relative "payu_pl/client"
 
 module PayuPl

data/sig/payu_pl.rbs

@@ -56,7 +56,7 @@ module PayuPl
 
   class Transport
     def initialize: (base_url: String, access_token_provider: ^() -> String?, ?open_timeout: Integer, ?read_timeout: Integer) -> void
-    def request: (untyped method, String path, ?headers: Hash[String, String], ?json: untyped, ?form: Hash[untyped, untyped], ?authorize: bool) -> untyped
+    def request: (untyped method, String path, ?headers: Hash[String, String], ?json: untyped, ?form: Hash[untyped, untyped]?, ?authorize: bool, ?return_headers: bool) -> untyped
   end
 
   class Client
@@ -90,5 +90,12 @@ module PayuPl
     def retrieve_refund: (untyped order_id, untyped refund_id) -> untyped
 
     def retrieve_transactions: (untyped order_id) -> untyped
+
+    def retrieve_shop_data: (untyped shop_id) -> untyped
+
+    def create_payout: (untyped payout_request) -> untyped
+    def retrieve_payout: (untyped payout_id) -> untyped
+
+    def retrieve_statement: (untyped report_id) -> untyped
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: payu_pl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dmytro Koval
@@ -73,6 +73,7 @@ files:
 - lib/payu_pl/contracts/capture_contract.rb
 - lib/payu_pl/contracts/id_contract.rb
 - lib/payu_pl/contracts/order_create_contract.rb
+- lib/payu_pl/contracts/payout_create_contract.rb
 - lib/payu_pl/contracts/refund_create_contract.rb
 - lib/payu_pl/endpoints.rb
 - lib/payu_pl/errors.rb
@@ -82,9 +83,13 @@ files:
 - lib/payu_pl/orders/create.rb
 - lib/payu_pl/orders/retrieve.rb
 - lib/payu_pl/orders/transactions.rb
+- lib/payu_pl/payouts/create.rb
+- lib/payu_pl/payouts/retrieve.rb
 - lib/payu_pl/refunds/create.rb
 - lib/payu_pl/refunds/list.rb
 - lib/payu_pl/refunds/retrieve.rb
+- lib/payu_pl/shops/retrieve.rb
+- lib/payu_pl/statements/retrieve.rb
 - lib/payu_pl/transport.rb
 - lib/payu_pl/version.rb
 - sig/payu_pl.rbs