payriff 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34ca8457b73de24291fd8233c3b2b3ef39f9bebcb9fc0b3f55d993b70c528339
+  data.tar.gz: 618c510f75c442dca74c577216d4e22d1087a4413f645573dea8678a5e171107
+SHA512:
+  metadata.gz: 76b857cbcc8e0597772e842871e3845676ba9d879cd08759a618dbd93c655eb3c0228b25141c060d7f53125f2a2fd4e059a22ac78a6c86f87042c1c4b7657fe5
+  data.tar.gz: b57f285973dffe727c31440ce0178f5f6e45a6f6e676d362db035f2592c9974eb3a68ec08d32ff0b5372648406fbf728f217c6398a44cc013f720f31788d150c

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.2 (2026-10-15)
+
+- First RubyGems release: install with `gem "payriff"`.
+- Test suite runs under Bundler on Ruby 4.0 (`logger` is no longer a default gem).
+
+## 0.1.1 (2026-10-07)
+
+- Fix `cannot load such file -- base64` under Bundler on Ruby 3.4+ (base64 is no longer a default gem).
+
+## 0.1.0 (2026-10-07)
+
+- Initial release: orders, direct and saved-card payments, saved cards, transactions, payouts,
+  v2 invoices, order callback parsing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Payriff
+
+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,266 @@
+# Payriff Ruby SDK
+
+Ruby client for the Payriff merchant API: orders, direct (host-to-host) card payments, saved cards,
+transactions, payouts and invoices.
+
+- Ruby 3.1 or newer
+- No runtime dependencies (standard library `net/http`, `json` and `openssl` only)
+- Talks to `https://api.payriff.com`
+
+## Installation
+
+```ruby
+# Gemfile
+gem "payriff"
+```
+
+Then run `bundle install`, or install it directly with `gem install payriff`.
+
+## Quick start
+
+```ruby
+require "payriff"
+
+payriff = Payriff::Client.new(app_key: ENV.fetch("PAYRIFF_APP_KEY"))
+
+order = payriff.orders.create(
+  amount: "10.00",
+  description: "Order #1001",
+  callback_url: "https://shop.example/payriff/callback",
+  request_rrn: "order-1001"
+)
+
+# Send the customer to the hosted payment page
+redirect_to order.payment_url, allow_other_host: true
+```
+
+Responses are `Payriff::PayriffObject`s: read fields with snake_case methods (`order.payment_url`)
+or `order[:payment_url]`, and convert with `to_h`. Fields Payriff did not send read as `nil`.
+
+Create one `Payriff::Client` and reuse it.
+
+## Configuration
+
+| Argument | Required | Default | Notes |
+|---|---|---|---|
+| `app_key:` | yes | — | Application key from the Payriff dashboard. |
+| `merchant_id:` | for payouts and invoices | — | Merchant ID (e.g. `ES1000000`). |
+| `timeout:` | no | `60` | Read/write timeout in seconds. Bank operations can take tens of seconds. |
+| `open_timeout:` | no | `10` | Connection timeout in seconds. |
+| `card_encryption_key:` | no | built-in Payriff key | Only if Payriff rotates the card-encryption key. Base64 or PEM. |
+
+Keep the app key in an environment variable or secret store. Never commit it.
+
+## Orders
+
+```ruby
+created = payriff.orders.create(
+  amount: "25.00",
+  currency: "AZN",            # default AZN
+  operation: "PRE_AUTH",      # default PURCHASE
+  language: "AZ",
+  description: "Booking #77",
+  callback_url: "https://shop.example/payriff/callback",
+  metadata: { "bookingId" => "77" }
+)
+
+info = payriff.orders.get(created.order_id)
+by_ref = payriff.orders.get_by_request_rrn("order-1001")   # the request_rrn you sent on create
+
+payriff.orders.complete(created.order_id, amount: "25.00")
+payriff.orders.refund(created.order_id, amount: "5.00", refund_reason: "Partial return")
+payriff.orders.expire(created.order_id)                    # cancel an unpaid order
+
+receipt_pdf = payriff.orders.download_receipt(created.order_id)
+```
+
+`payment_status` is a string such as `"APPROVED"`, `"DECLINED"`, `"PREAUTH_APPROVED"` or `"REFUNDED"`.
+Enum arguments also accept symbols (`language: :az`).
+
+Amounts can be passed as numeric strings (`"10.50"`), integers, floats or `BigDecimal`s.
+
+## Direct payments (host-to-host)
+
+You collect the card details yourself, and the SDK encrypts them before sending
+(AES-256-GCM + RSA-OAEP). Raw card data never leaves your server in clear text, but your
+systems still handle card data, so PCI DSS requirements apply to you.
+
+```ruby
+result = payriff.payments.direct_pay(
+  amount: "1.00",
+  description: "Order #1002",
+  callback_url: "https://shop.example/payriff/callback",
+  request_rrn: "order-1002",
+  card: Payriff::Card.new(
+    pan: "4169 7413 3015 1979",
+    card_holder: "JOHN DOE",
+    expiry_month: "11",
+    expiry_year: "27",
+    cvv: "123"
+  )
+)
+
+if result.redirect
+  # 3-D Secure: send the customer's browser to result.redirect_url.
+  # The final status arrives via your callback or payriff.orders.get(result.order_id).
+end
+```
+
+`Payriff::Card` strips spaces and dashes, pads the month (`1` → `01`), expands a 2-digit year
+(`27` → `2027`) and rejects malformed values before any network call. It is frozen, prints and logs
+with a masked number and no CVV, and cannot be serialized with `Marshal`.
+
+### Charging a saved card
+
+```ruby
+charge = payriff.payments.auto_pay(
+  card_uuid: saved_card_uuid,
+  amount: "9.99",
+  description: "Monthly subscription",
+  request_rrn: "sub-2026-10"
+)
+```
+
+## Saved cards
+
+```ruby
+session = payriff.cards.save(
+  customer_ref: "customer-42",
+  callback_url: "https://shop.example/payriff/card-saved",
+  idempotency_key: SecureRandom.uuid
+)
+# Redirect the customer to session.payment_url to verify the card.
+
+details = payriff.cards.get_save(session.card_save_id)
+if details.status == "VERIFIED"
+  card_uuid = details.card_uuid   # store it; use with auto_pay
+end
+
+cards = payriff.cards.list("customer-42")
+payriff.cards.delete(cards.first.card_uuid)
+```
+
+## Transactions
+
+```ruby
+page = payriff.transactions.list(
+  status: "APPROVED",
+  from: Date.new(2026, 9, 1),    # Date, Time or "YYYY-MM-DD"
+  to: "2026-09-30",
+  page: 0,
+  size: 20                       # server maximum is 20
+)
+
+page.content.each { |tx| puts "#{tx.order_id} #{tx.amount}" }
+```
+
+## Payouts
+
+Payouts require `merchant_id` on the client.
+
+```ruby
+payriff = Payriff::Client.new(app_key: ENV.fetch("PAYRIFF_APP_KEY"), merchant_id: ENV.fetch("PAYRIFF_MERCHANT_ID"))
+
+masked_name = payriff.payouts.check_cardholder("4169741330151979")   # e.g. "J*** D**"
+
+payout = payriff.payouts.create(
+  transfer_amount: "50.00",      # minimum 1
+  description: "Refund for order #1001",
+  full_name: "JOHN DOE",
+  fin_code: "1AB2C3D",
+  card_pan: "4169741330151979",
+  request_rrn: "payout-1001",
+  idempotency_key: "payout-1001"
+)
+
+status = payriff.payouts.get_by_request_rrn("payout-1001")
+history = payriff.payouts.list(status: "SUCCESS")
+receipt = payriff.payouts.download_receipt("payout-1001")
+```
+
+## Invoices
+
+Invoices require `merchant_id` on the client.
+
+```ruby
+invoice = payriff.invoices.create(
+  amount: "15.00",
+  full_name: "JOHN DOE",
+  phone_number: "+994501234567",
+  description: "Consultation",
+  expire_date: Time.now + 7 * 24 * 3600,
+  send_sms: true
+)
+
+link = invoice.payment_url   # share with the customer
+details = payriff.invoices.get(invoice.invoice_uuid)
+```
+
+## Callbacks
+
+When an order changes state, Payriff POSTs JSON to the `callback_url` you set on the order.
+
+```ruby
+class PayriffCallbacksController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    notified = Payriff.parse_order_callback(request.raw_post)   # also accepts a parsed Hash
+
+    # Callbacks are not signed: confirm the state with Payriff before fulfilling.
+    confirmed = PAYRIFF.orders.get(notified.order_id)
+    if confirmed.payment_status == "APPROVED"
+      # fulfil the order (make this idempotent: the same callback can arrive more than once)
+    end
+    head :ok
+  end
+end
+```
+
+## Errors
+
+Every SDK error extends `Payriff::Error`, which provides `http_status`, `code` (Payriff result code)
+and `response_id` (quote it when contacting support).
+
+| Exception | When |
+|---|---|
+| `Payriff::AuthenticationError` | App key rejected (`14010`, `14013`, `14014`, `14015`) |
+| `Payriff::ValidationError` | Invalid request (`15400` or HTTP 400) |
+| `Payriff::RequestRejectedError` | Business refusal (`01000`), e.g. application under review |
+| `Payriff::InsufficientBalanceError` | Not enough wallet balance for a payout (`01200`) |
+| `Payriff::PayoutLimitError` | Payout limit reached (`01300`, `01400`, `01500`) |
+| `Payriff::ApiError` | Any other failure reported by Payriff |
+| `Payriff::ConnectionError` | No response: network error or timeout |
+
+Payriff can report a failure with HTTP 200. The SDK checks the result code in the body, so you
+only need to rescue exceptions. Invalid arguments raise `ArgumentError` before any request is sent.
+
+```ruby
+begin
+  payriff.orders.refund(order_id)
+rescue Payriff::ValidationError => e
+  Rails.logger.warn("Refund rejected: #{e.message} (#{e.code})")
+rescue Payriff::ConnectionError
+  # Outcome unknown: check payriff.orders.get(order_id) before retrying
+rescue Payriff::Error => e
+  Rails.logger.error("Payriff error #{e.code} response_id=#{e.response_id}")
+end
+```
+
+### Retries
+
+The SDK never retries on its own, because payment calls are not safe to repeat blindly. After a
+`Payriff::ConnectionError`, look the operation up first (`orders.get_by_request_rrn`,
+`payouts.get_by_request_rrn`) and retry only if it does not exist. Set `request_rrn` /
+`idempotency_key` on every request so that this lookup is possible.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/payriff/card.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Payriff
+  class Card
+    def initialize(pan:, card_holder:, expiry_month:, expiry_year:, cvv:)
+      pan = digits(pan, "pan")
+      raise ArgumentError, "pan must contain 12-19 digits" unless pan.length.between?(12, 19)
+
+      month = digits(expiry_month, "expiry_month").to_i
+      raise ArgumentError, "expiry_month must be 1-12" unless month.between?(1, 12)
+
+      year = digits(expiry_year, "expiry_year")
+      year = "20#{year}" if year.length == 2
+      raise ArgumentError, "expiry_year must have 2 or 4 digits" unless year.length == 4
+
+      cvv = digits(cvv, "cvv")
+      raise ArgumentError, "cvv must contain 3-4 digits" unless cvv.length.between?(3, 4)
+      raise ArgumentError, "card_holder is required" if card_holder.nil?
+
+      @payload = JSON.generate(
+        "pan" => pan,
+        "cardHolder" => card_holder.to_s.strip,
+        "expiryYear" => year,
+        "expiryMonth" => format("%02d", month),
+        "cvv" => cvv
+      ).freeze
+      @masked = "#{pan[0, 6]}******#{pan[-4, 4]}"
+      @expiry = "#{format('%02d', month)}/#{year}"
+      freeze
+    end
+
+    def to_s
+      "#<Payriff::Card #{@masked} #{@expiry}>"
+    end
+    alias inspect to_s
+
+    def to_json(*args)
+      to_s.to_json(*args)
+    end
+
+    def marshal_dump
+      raise TypeError, "Payriff::Card cannot be serialized"
+    end
+
+    def encrypted_payload(public_key)
+      CardEncryptor.encrypt(public_key, @payload)
+    end
+
+    private
+
+    def digits(value, field)
+      raise ArgumentError, "#{field} must contain digits only" if value.nil?
+
+      v = value.to_s.gsub(/[\s-]/, "")
+      raise ArgumentError, "#{field} must contain digits only" unless v.match?(/\A[0-9]+\z/)
+
+      v
+    end
+  end
+
+  module CardEncryptor
+    PRODUCTION_KEY =
+      "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxRq5a+44T6Dac60XmVRQ/7cpPyFsBnamXbJlRVJk8CnES5Re5tVMohyD0hZr" \
+      "3zcQj+bxodYB4zZpQTPlrXvFBC3zz+rXnGlevxBQ6W2d3QC9q8vWH8p3ZOwTO3qVvDSHH9o+hMMRNbJ7kueq/KZlX/F+bjZ23CZw7iXE" \
+      "GQT3HYVYnnHsvpaguYDteWBag2sPPLLsVjeB3zhTfQ7OsWp5XTkDuRwLugHPvs6RHLcwGCnodukWyvwUaEUQR/kMGC+RbMsAIVkcLMP5" \
+      "csfR3Xo7Gi98+i44iLN00f7gE8QvEmvv8xDspyTAjDEL1a5gK7TijJ3yLG/Bwa1rr1uskYy7lwIDAQAB"
+
+    OAEP = { rsa_padding_mode: "oaep", rsa_oaep_md: "sha256", rsa_mgf1_md: "sha256" }.freeze
+
+    module_function
+
+    def parse_key(base64_or_pem)
+      body = base64_or_pem.to_s.gsub(/-----(BEGIN|END) PUBLIC KEY-----|\s/, "")
+      key = OpenSSL::PKey.read(body.unpack1("m0"))
+      raise ArgumentError, "Invalid RSA public key" unless key.is_a?(OpenSSL::PKey::RSA) && !key.private?
+
+      key
+    rescue OpenSSL::PKey::PKeyError, ArgumentError
+      raise ArgumentError, "Invalid RSA public key"
+    end
+
+    def encrypt(public_key, payload)
+      aes_key = OpenSSL::Random.random_bytes(32)
+      iv = OpenSSL::Random.random_bytes(12)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+      cipher.key = aes_key
+      cipher.iv = iv
+      ciphertext = cipher.update(payload) + cipher.final + cipher.auth_tag(16)
+      secret = public_key.encrypt(aes_key + iv, OAEP)
+      { message: [ciphertext].pack("m0"), secret_key: [secret].pack("m0") }
+    end
+  end
+end

data/lib/payriff/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Payriff
+  class Client
+    PRODUCTION_URL = "https://api.payriff.com"
+
+    attr_reader :orders, :payments, :cards, :transactions, :payouts, :invoices
+
+    def initialize(app_key:, merchant_id: nil, timeout: 60, open_timeout: 10, card_encryption_key: nil, base_url: PRODUCTION_URL)
+      raise ArgumentError, "app_key is required" if app_key.nil? || app_key.to_s.strip.empty?
+      raise ArgumentError, "timeouts must be positive" unless timeout.to_f.positive? && open_timeout.to_f.positive?
+
+      transport = Transport.new(base_url: base_url, app_key: app_key, merchant_id: merchant_id,
+                                timeout: timeout, open_timeout: open_timeout)
+      key = CardEncryptor.parse_key(card_encryption_key || CardEncryptor::PRODUCTION_KEY)
+      @orders = Services::Orders.new(transport)
+      @payments = Services::Payments.new(transport, key)
+      @cards = Services::Cards.new(transport)
+      @transactions = Services::Transactions.new(transport)
+      @payouts = Services::Payouts.new(transport)
+      @invoices = Services::Invoices.new(transport)
+    end
+
+    def inspect
+      "#<Payriff::Client>"
+    end
+  end
+end

data/lib/payriff/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Payriff
+  class Error < StandardError
+    attr_reader :http_status, :code, :response_id
+
+    def initialize(message, http_status: 0, code: nil, response_id: nil)
+      super(message)
+      @http_status = http_status
+      @code = code
+      @response_id = response_id
+    end
+  end
+
+  class ApiError < Error; end
+  class AuthenticationError < ApiError; end
+  class ValidationError < ApiError; end
+  class RequestRejectedError < ApiError; end
+  class InsufficientBalanceError < ApiError; end
+  class PayoutLimitError < ApiError; end
+  class ConnectionError < Error; end
+
+  module ResultCodes
+    SUCCESS = "00000"
+
+    BY_CODE = {
+      "14010" => AuthenticationError,
+      "14013" => AuthenticationError,
+      "14014" => AuthenticationError,
+      "14015" => AuthenticationError,
+      "01300" => PayoutLimitError,
+      "01400" => PayoutLimitError,
+      "01500" => PayoutLimitError,
+      "01200" => InsufficientBalanceError,
+      "01000" => RequestRejectedError,
+      "15400" => ValidationError
+    }.freeze
+
+    def self.to_error(message, http_status, code, response_id)
+      msg = message.nil? || message.empty? ? "Payriff request failed (HTTP #{http_status})" : message
+      klass = BY_CODE[code] ||
+              case http_status
+              when 401, 403 then AuthenticationError
+              when 400 then ValidationError
+              else ApiError
+              end
+      klass.new(msg, http_status: http_status, code: code, response_id: response_id)
+    end
+  end
+end

data/lib/payriff/payriff_object.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Payriff
+  class PayriffObject
+    RENAMES = { "comissionRate" => :commission_rate, "_final" => :final_state }.freeze
+
+    def self.convert(value)
+      case value
+      when Hash then new(value)
+      when Array then value.map { |v| convert(v) }
+      else value
+      end
+    end
+
+    def self.snake(key)
+      RENAMES.fetch(key) do
+        key.to_s
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+           .to_sym
+      end
+    end
+
+    def initialize(hash)
+      @values = {}
+      hash.each do |key, value|
+        name = self.class.snake(key)
+        @values[name] = self.class.convert(value) unless @values.key?(name) && value.nil?
+      end
+    end
+
+    def [](key)
+      @values[key.to_sym]
+    end
+
+    def key?(key)
+      @values.key?(key.to_sym)
+    end
+
+    def keys
+      @values.keys
+    end
+
+    def to_h
+      @values.transform_values { |v| unwrap(v) }
+    end
+
+    def ==(other)
+      other.is_a?(PayriffObject) && other.to_h == to_h
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@values.inspect}>"
+    end
+
+    FIELD_NAME = /\A(?!to_)[a-z][a-z0-9_]*\z/
+
+    def respond_to_missing?(name, include_private = false)
+      @values.key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      return super unless args.empty?
+      return @values[name] if @values.key?(name)
+      return nil if FIELD_NAME.match?(name)
+
+      super
+    end
+
+    private
+
+    def unwrap(value)
+      case value
+      when PayriffObject then value.to_h
+      when Array then value.map { |v| unwrap(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/payriff/services.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Payriff
+  module Services
+    class Base
+      include Util
+
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+    end
+
+    class Orders < Base
+      def create(amount:, currency: "AZN", language: nil, operation: "PURCHASE", description: nil, callback_url: nil,
+                 redirect_url: nil, card_save: nil, three_ds: nil, auto_payment_type: nil, installment: nil,
+                 full_name: nil, phone_number: nil, metadata: nil, fields: nil, request_rrn: nil)
+        body = compact(
+          "amount" => to_amount(required(amount, "amount"), "amount"),
+          "currency" => stringify(currency),
+          "language" => stringify(language),
+          "operation" => stringify(operation),
+          "description" => description,
+          "callbackUrl" => callback_url,
+          "redirectUrl" => redirect_url,
+          "cardSave" => card_save,
+          "threeDS" => three_ds,
+          "autoPaymentType" => stringify(auto_payment_type),
+          "installment" => installment&.transform_keys(&:to_s)&.transform_values { |v| stringify(v) },
+          "fullName" => full_name,
+          "phoneNumber" => phone_number,
+          "metadata" => metadata,
+          "fields" => fields
+        )
+        @transport.execute("POST", "/api/v3/orders", headers: { "X-REQUEST-RRN" => request_rrn }, body: body)
+      end
+
+      def get(order_id)
+        @transport.execute("GET", "/api/v3/orders/#{segment(order_id, 'order_id')}")
+      end
+
+      def get_status(order_id)
+        @transport.execute("GET", "/api/v3/orders/#{segment(order_id, 'order_id')}/status")
+      end
+
+      def get_by_request_rrn(request_rrn)
+        @transport.execute("GET", "/api/v3/orders/#{segment(request_rrn, 'request_rrn')}/rrn")
+      end
+
+      def expire(order_id)
+        segment(order_id, "order_id")
+        @transport.execute("PATCH", "/api/v3/expire-status", query: [["orderId", order_id]])
+        nil
+      end
+
+      def refund(order_id, amount: nil, refund_reason: nil, callback_url: nil)
+        body = compact("orderId" => required(order_id, "order_id"), "amount" => to_amount(amount, "amount"),
+                       "refundReason" => refund_reason, "callbackUrl" => callback_url)
+        @transport.execute("POST", "/api/v3/refund", body: body)
+        nil
+      end
+
+      def complete(order_id, amount: nil, callback_url: nil)
+        body = compact("orderId" => required(order_id, "order_id"), "amount" => to_amount(amount, "amount"),
+                       "callbackUrl" => callback_url)
+        @transport.execute("POST", "/api/v3/complete", body: body)
+        nil
+      end
+
+      def download_receipt(order_id_or_rrn)
+        @transport.download("GET", "/api/v3/acquiring/receipt/#{segment(order_id_or_rrn, 'order_id_or_rrn')}")
+      end
+    end
+
+    class Payments < Base
+      def initialize(transport, public_key)
+        super(transport)
+        @public_key = public_key
+      end
+
+      def direct_pay(amount:, description:, card:, operation: "PURCHASE", currency: "AZN", callback_url: nil,
+                     three_ds: nil, custom_fields: nil, card_save: false, request_rrn: nil)
+        body = compact(
+          "amount" => to_amount(required(amount, "amount"), "amount"),
+          "operation" => stringify(operation),
+          "currency" => stringify(currency),
+          "description" => required(description, "description"),
+          "callbackUrl" => callback_url,
+          "threeDS" => three_ds,
+          "customFields" => custom_fields
+        )
+        raise ArgumentError, "card must be a Payriff::Card" unless card.is_a?(Card)
+
+        encrypted = card.encrypted_payload(@public_key)
+        body["paymentData"] = { "paymentWay" => "DIRECT", "encryptedMessage" => encrypted[:message], "cardSave" => card_save ? true : false }
+        @transport.execute("POST", "/api/v3/directPay",
+                           headers: { "X-REQUEST-RRN" => request_rrn, "x-secret-key" => encrypted[:secret_key] }, body: body)
+      end
+
+      def auto_pay(card_uuid:, amount:, description:, operation: "PURCHASE", currency: "AZN", callback_url: nil,
+                   three_ds: nil, one_click_payment: nil, request_rrn: nil)
+        body = compact(
+          "cardUuid" => required(card_uuid, "card_uuid"),
+          "amount" => to_amount(required(amount, "amount"), "amount"),
+          "operation" => stringify(operation),
+          "currency" => stringify(currency),
+          "description" => required(description, "description"),
+          "callbackUrl" => callback_url,
+          "threeDS" => three_ds,
+          "isOneCLickPayment" => one_click_payment
+        )
+        @transport.execute("POST", "/api/v3/autoPay", headers: { "X-REQUEST-RRN" => request_rrn }, body: body)
+      end
+    end
+
+    class Cards < Base
+      def save(customer_ref:, callback_url:, description: nil, language: nil, metadata: nil, idempotency_key: nil)
+        body = compact(
+          "customerRef" => required(customer_ref, "customer_ref"),
+          "callbackUrl" => required(callback_url, "callback_url"),
+          "description" => description,
+          "language" => stringify(language),
+          "metadata" => metadata
+        )
+        @transport.execute("POST", "/api/v3/cards/save", headers: { "X-Idempotency-Key" => idempotency_key }, body: body)
+      end
+
+      def get_save(card_save_id)
+        @transport.execute("GET", "/api/v3/cards/save/#{segment(card_save_id, 'card_save_id')}")
+      end
+
+      def list(customer_ref)
+        segment(customer_ref, "customer_ref")
+        @transport.execute("GET", "/api/v3/cards/save", query: [["customerRef", customer_ref]]) || []
+      end
+
+      def delete(card_uuid)
+        @transport.execute("DELETE", "/api/v3/cards/#{segment(card_uuid, 'card_uuid')}")
+        nil
+      end
+    end
+
+    class Transactions < Base
+      def list(order_id: nil, rrn: nil, status: nil, amount: nil, description: nil, name: nil, full_name: nil,
+               card_number: nil, booking_id: nil, invoice_code: nil, from: nil, to: nil, page: 0, size: 10)
+        query = [
+          ["orderId", order_id], ["rrn", rrn], ["status", stringify(status)], ["amount", amount],
+          ["description", description], ["name", name], ["fullName", full_name], ["cardNumber", card_number],
+          ["bookingId", booking_id], ["invoiceCode", invoice_code],
+          ["from", filter_date(from, "from")], ["to", filter_date(to, "to")]
+        ] + page_query(page, size)
+        @transport.execute("GET", "/api/v3/transactions", query: query)
+      end
+    end
+
+    class Payouts < Base
+      def create(transfer_amount:, description:, full_name:, fin_code:, card_pan: nil, bank_name: nil, card_type: nil,
+                 request_rrn: nil, customer_code: nil, voen: nil, birth_date: nil, callback_url: nil, idempotency_key: nil)
+        amount = to_amount(required(transfer_amount, "transfer_amount"), "transfer_amount")
+        raise ArgumentError, "transfer_amount must be at least 1" if amount < 1
+
+        body = compact(
+          "transferAmount" => amount,
+          "description" => required(description, "description"),
+          "fullName" => required(full_name, "full_name"),
+          "finCode" => required(fin_code, "fin_code"),
+          "cardPan" => card_pan,
+          "bankName" => bank_name,
+          "cardType" => card_type,
+          "requestRrn" => request_rrn,
+          "customerCode" => customer_code,
+          "voen" => voen,
+          "birthDate" => birth_date,
+          "callbackUrl" => callback_url
+        )
+        @transport.execute("POST", "/api/v3/payout", headers: { "X-IDEMPOTENCY-KEY" => idempotency_key },
+                                                     body: body, merchant_envelope: true)
+      end
+
+      def get_by_request_rrn(request_rrn)
+        @transport.execute("GET", "/api/v3/payout/info/#{segment(request_rrn, 'request_rrn')}")
+      end
+
+      def check_cardholder(card_pan)
+        pan = card_pan.to_s.gsub(/[\s-]/, "")
+        raise ArgumentError, "card_pan must be a 16-digit number" unless pan.match?(/\A[0-9]{16}\z/)
+
+        @transport.execute("POST", "/api/v3/payout/check-cardholder", body: { "cardPan" => pan }).to_s
+      end
+
+      def list(rrn: nil, status: nil, amount: nil, description: nil, full_name: nil, fin_code: nil, bank_source: nil,
+               from: nil, to: nil, page: 0, size: 10)
+        query = [
+          ["rrn", rrn], ["status", stringify(status)], ["amount", amount], ["description", description],
+          ["fullName", full_name], ["finCode", fin_code], ["bankSource", bank_source],
+          ["from", filter_date(from, "from")], ["to", filter_date(to, "to")]
+        ] + page_query(page, size)
+        @transport.execute("GET", "/api/v3/payouts", query: query)
+      end
+
+      def download_receipt(request_rrn)
+        @transport.download("GET", "/api/v3/payout/receipt/#{segment(request_rrn, 'request_rrn')}")
+      end
+    end
+
+    class Invoices < Base
+      def create(amount: nil, amount_dynamic: nil, currency: "AZN", language: nil, full_name: nil, email: nil,
+                 phone_number: nil, description: nil, custom_message: nil, expire_date: nil, approve_url: nil,
+                 cancel_url: nil, decline_url: nil, redirect_url: nil, installment_product_type: nil,
+                 installment_period: nil, direct_pay: nil, send_sms: nil, send_whatsapp: nil, send_email: nil,
+                 metadata: nil, external_transaction_id: nil)
+        raise ArgumentError, "amount is required" if amount_dynamic != true && amount.nil?
+
+        body = compact(
+          "amount" => to_amount(amount, "amount"),
+          "amountDynamic" => amount_dynamic,
+          "currencyType" => stringify(currency),
+          "languageType" => stringify(language),
+          "fullName" => full_name,
+          "email" => email,
+          "phoneNumber" => phone_number,
+          "description" => description,
+          "customMessage" => custom_message,
+          "expireDate" => date_time(expire_date),
+          "approveURL" => approve_url,
+          "cancelURL" => cancel_url,
+          "declineURL" => decline_url,
+          "redirectURL" => redirect_url,
+          "installmentProductType" => stringify(installment_product_type),
+          "installmentPeriod" => installment_period,
+          "directPay" => direct_pay,
+          "sendSms" => send_sms,
+          "sendWhatsapp" => send_whatsapp,
+          "sendEmail" => send_email,
+          "metadata" => metadata,
+          "externalTransactionId" => external_transaction_id
+        )
+        @transport.execute("POST", "/api/v2/invoices", body: body, merchant_envelope: true)
+      end
+
+      def get(invoice_uuid)
+        segment(invoice_uuid, "invoice_uuid")
+        @transport.execute("POST", "/api/v2/get-invoice", body: { "uuid" => invoice_uuid }, merchant_envelope: true)
+      end
+    end
+  end
+end

data/lib/payriff/transport.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Payriff
+  class Transport
+    MAX_ERROR_BODY = 500
+    CONNECTION_ERRORS = [
+      IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, EOFError
+    ].freeze
+
+    def initialize(base_url:, app_key:, merchant_id:, timeout:, open_timeout:)
+      @base_uri = URI(base_url.to_s.chomp("/"))
+      @app_key = app_key
+      @merchant_id = merchant_id
+      @timeout = timeout
+      @open_timeout = open_timeout
+    end
+
+    def execute(method, path, query: nil, headers: nil, body: nil, merchant_envelope: false)
+      status, raw = send_request(method, path, query, headers, body, merchant_envelope, "application/json")
+      PayriffObject.convert(unwrap(status, raw))
+    end
+
+    def download(method, path)
+      status, raw = send_request(method, path, nil, nil, nil, false, "application/pdf, application/json")
+      return raw.b if (200..299).cover?(status)
+
+      unwrap(status, raw)
+      raise ApiError.new("Unexpected response", http_status: status)
+    end
+
+    private
+
+    def send_request(method, path, query, headers, body, merchant_envelope, accept)
+      payload = request_body(body, merchant_envelope)
+      uri = URI(@base_uri.to_s + path + query_string(query))
+      request = Net::HTTPGenericRequest.new(method, !payload.nil?, true, uri)
+      request["Accept"] = accept
+      request["User-Agent"] = "payriff-ruby/#{VERSION}"
+      request["Authorization"] = @app_key
+      (headers || {}).each { |name, value| request[name] = value.to_s unless value.nil? || value.to_s.empty? }
+      if payload
+        request["Content-Type"] = "application/json"
+        request.body = payload
+      end
+      response = http(uri).request(request)
+      [response.code.to_i, response.body.to_s]
+    rescue *CONNECTION_ERRORS => e
+      raise ConnectionError, "Payriff request failed: #{e.message}"
+    end
+
+    def http(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |http|
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+      end
+    end
+
+    def query_string(query)
+      pairs = (query || []).reject { |_, v| v.nil? || v.to_s.empty? }
+      return "" if pairs.empty?
+
+      "?" + pairs.map { |k, v| "#{Util.escape(k)}=#{Util.escape(v)}" }.join("&")
+    end
+
+    def request_body(body, merchant_envelope)
+      if merchant_envelope
+        raise ArgumentError, "merchant_id must be configured on Payriff::Client for this operation" if @merchant_id.to_s.empty?
+
+        body = { "merchant" => @merchant_id, "body" => body || {} }
+      end
+      body.nil? ? nil : JSON.generate(body)
+    end
+
+    def unwrap(status, raw)
+      root = begin
+        raw.empty? ? nil : JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+      ok = (200..299).cover?(status)
+      unless root.is_a?(Hash) && root.key?("code")
+        raise ApiError.new(ok ? "Unexpected response from Payriff" : truncate(raw, status), http_status: status)
+      end
+
+      code = root["code"]&.to_s
+      unless ok && code == ResultCodes::SUCCESS
+        raise ResultCodes.to_error(root["message"]&.to_s, status, code, root["responseId"]&.to_s)
+      end
+
+      root["payload"]
+    end
+
+    def truncate(raw, status)
+      return "Payriff request failed (HTTP #{status})" if raw.empty?
+
+      text = raw.dup.force_encoding(Encoding::UTF_8).scrub
+      text.length > MAX_ERROR_BODY ? "#{text[0, MAX_ERROR_BODY]}..." : text
+    end
+  end
+end

data/lib/payriff/util.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Payriff
+  module Util
+    MAX_PAGE_SIZE = 20
+    UNRESERVED = /[^A-Za-z0-9\-._~]/
+
+    module_function
+
+    def escape(value)
+      value.to_s.b.gsub(UNRESERVED) { |c| format("%%%02X", c.ord) }
+    end
+
+    def segment(value, name)
+      raise ArgumentError, "#{name} must not be blank" if !value.is_a?(String) || value.strip.empty?
+
+      escape(value)
+    end
+
+    def required(value, name)
+      raise ArgumentError, "#{name} is required" if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      value
+    end
+
+    def to_amount(value, name)
+      return nil if value.nil?
+
+      Float(value.is_a?(String) ? value : value.to_s)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "#{name} must be a number"
+    end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+    end
+
+    def stringify(value)
+      value.is_a?(Symbol) ? value.to_s.upcase : value
+    end
+
+    def date_time(value)
+      case value
+      when nil then nil
+      when Time, DateTime then value.strftime("%Y-%m-%dT%H:%M:%S")
+      when Date then value.strftime("%Y-%m-%dT00:00:00")
+      else value.to_s
+      end
+    end
+
+    def filter_date(value, name)
+      case value
+      when nil then nil
+      when Date, Time then value.strftime("%d.%m.%Y")
+      when /\A(\d{4})-(\d{2})-(\d{2})\z/ then "#{Regexp.last_match(3)}.#{Regexp.last_match(2)}.#{Regexp.last_match(1)}"
+      else raise ArgumentError, "#{name} must be a Date, Time or YYYY-MM-DD string"
+      end
+    end
+
+    def page_query(page, size)
+      page ||= 0
+      size ||= 10
+      raise ArgumentError, "page must be >= 0" unless page.is_a?(Integer) && page >= 0
+      raise ArgumentError, "size must be 1-#{MAX_PAGE_SIZE}" unless size.is_a?(Integer) && size.between?(1, MAX_PAGE_SIZE)
+
+      [["page", page], ["offset", size]]
+    end
+  end
+end

data/lib/payriff/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Payriff
+  VERSION = "0.1.2"
+end

data/lib/payriff.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "payriff/version"
+require_relative "payriff/errors"
+require_relative "payriff/util"
+require_relative "payriff/payriff_object"
+require_relative "payriff/card"
+require_relative "payriff/transport"
+require_relative "payriff/services"
+require_relative "payriff/client"
+
+module Payriff
+  NOT_A_CALLBACK = "Not a Payriff order callback"
+
+  def self.parse_order_callback(body)
+    root = body.is_a?(Hash) ? body : JSON.parse(body.to_s)
+    payload = root.is_a?(Hash) ? root["payload"] || root[:payload] : nil
+    raise ArgumentError, NOT_A_CALLBACK unless payload.is_a?(Hash) && !(payload["orderId"] || payload[:orderId]).nil?
+
+    PayriffObject.convert(payload.transform_keys(&:to_s))
+  rescue JSON::ParserError
+    raise ArgumentError, NOT_A_CALLBACK
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: payriff
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Payriff
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Orders, direct card payments, saved cards, transactions, payouts and
+  invoices for Payriff merchants.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/payriff.rb
+- lib/payriff/card.rb
+- lib/payriff/client.rb
+- lib/payriff/errors.rb
+- lib/payriff/payriff_object.rb
+- lib/payriff/services.rb
+- lib/payriff/transport.rb
+- lib/payriff/util.rb
+- lib/payriff/version.rb
+homepage: https://github.com/PayRiff/payriff-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/PayRiff/payriff-ruby
+  changelog_uri: https://github.com/PayRiff/payriff-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby client for the Payriff merchant API
+test_files: []