multicard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4deef0f73a9d0f65799ff892e950f24b744a350cadd90b2956fc5dd4c91f6f2f
+  data.tar.gz: 1471a57173d4a1b868867350f9de3e9e72513f6fe873bba4fa10767f79044eba
+SHA512:
+  metadata.gz: 9ba05346db8cf1fe2b16577f06423fe19b24652c4cb5210124ef313c94355c4645008be1d57157095c33acce7f4b2197f159905fde1188977bc1cc0c2ae44aa4
+  data.tar.gz: e9e987599830d737e9f878bd46938df9308607bc79a5cf3314bf6b4df4f7076ec81a4389deba588ace709ed517b111844da9c1ebe8ec22661e56cf9df6148802

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-16
+
+### Added
+
+- Initial release
+- Configuration (global and per-client with immutable merge)
+- HTTP client (HTTP.rb) with retry logic and exponential backoff
+- Thread-safe token management with Mutex (23h TTL, auto-refresh)
+- Automatic retry on 401 (token expiry)
+- Resources: Invoices, Payments, Cards, Holds, Payouts, Registry (33 methods, 100% API coverage)
+- Split payments support (multi-recipient)
+- Wallet payments (Payme, Click, Uzum, Anorbank, Xazna, etc.)
+- Webhook signature verification (MD5, constant-time comparison, amount normalization)
+- Full error hierarchy with Multicard-specific error codes (ERROR_MAP)
+- Comprehensive test suite (90 specs, WebMock)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Honey Murena
+
+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,405 @@
+# Multicard Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/multicard.svg)](https://badge.fury.io/rb/multicard)
+[![CI](https://github.com/pashgo/multicard-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/pashgo/multicard-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Ruby client for the [Multicard](https://multicard.uz) payment gateway (Uzbekistan).
+
+Supports Uzcard, Humo, and wallet apps: Payme, Click, Uzum, Anorbank, Xazna, and more.
+
+## Why This Gem?
+
+Before this SDK, integrating with Multicard meant writing raw HTTP calls, managing tokens manually, and handling errors ad-hoc. Here's what the gem gives you:
+
+### Full API Coverage
+
+30 methods across 6 resource groups — invoices, payments (token/card/wallet/split), card binding, holds (pre-auth), payouts, and registry. No need to study the API docs for every endpoint.
+
+### Clean Resource-Based Interface
+
+Stripe/Shopify-style SDK design:
+
+```ruby
+client.payments.create_by_token(card_token: 'tok_abc', amount: 500_000, invoice_id: 'ORD-1')
+client.holds.capture(hold_id, amount: 300_000)
+client.cards.create_binding_link
+```
+
+Discoverable, self-documenting API — IDE autocompletion works out of the box.
+
+### Automatic Token Management
+
+Bearer tokens (24h TTL) are fetched, cached, and refreshed transparently. Thread-safe with Mutex. On 401, the gem automatically refreshes the token and retries the request — zero manual intervention.
+
+### Typed Error Hierarchy
+
+Multicard error codes map to specific Ruby exceptions:
+
+```ruby
+rescue Multicard::InsufficientFundsError  # not enough funds
+rescue Multicard::CardExpiredError         # card expired
+rescue Multicard::DebitUnknownError        # need to poll for status
+rescue Multicard::NetworkError             # timeout / connection lost
+```
+
+Each exception carries `http_status`, `error_code`, `error_details`, and `response_body` — no parsing required.
+
+### Framework-Agnostic
+
+Zero runtime dependencies. Uses Ruby's built-in `Net::HTTP` — no external gems required. Works in any Ruby app — Rails, Sinatra, Hanami, plain scripts.
+
+### Built-In Security
+
+- Webhook signature verification with constant-time comparison (timing-attack safe)
+- No sensitive data in logs (token values are never logged)
+- Automatic retry with exponential backoff for transient failures
+
+### Production-Ready
+
+- 91 specs with WebMock (no real HTTP calls in tests)
+- Thread-safe token caching
+- Configurable timeouts (connect + read)
+- Optional logger support for debugging
+- Global config + per-client overrides for multi-tenant setups
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'multicard'
+```
+
+Or install directly:
+
+```
+gem install multicard
+```
+
+## Quick Start
+
+```ruby
+require 'multicard'
+
+client = Multicard::Client.new(
+  application_id: ENV['MULTICARD_APPLICATION_ID'],
+  secret: ENV['MULTICARD_SECRET'],
+  store_id: 123  # default register ID
+)
+
+# Create a hosted checkout invoice
+invoice = client.invoices.create(
+  amount: 500_000,          # 5,000 UZS in tiyin
+  invoice_id: 'ORD-001',
+  callback_url: 'https://example.com/webhooks/multicard'
+)
+
+# Redirect user to payment page
+invoice.data[:checkout_url]
+```
+
+## Configuration
+
+### Global (optional)
+
+```ruby
+Multicard.configure do |config|
+  config.application_id = ENV['MULTICARD_APPLICATION_ID']
+  config.secret = ENV['MULTICARD_SECRET']
+  config.base_url = 'https://api.multicard.uz'  # default
+  config.timeout = 30                            # default (seconds)
+  config.open_timeout = 10                       # default (seconds)
+  config.logger = Logger.new($stdout)            # optional
+  config.store_id = 123                          # default store/register ID
+end
+
+# Then create clients without repeating credentials:
+client = Multicard::Client.new
+```
+
+### Per-client (overrides global)
+
+```ruby
+client = Multicard::Client.new(
+  application_id: 'other_app_id',
+  secret: 'other_secret',
+  store_id: 456
+)
+```
+
+## Invoices (Hosted Checkout)
+
+```ruby
+# Create invoice
+invoice = client.invoices.create(
+  amount: 500_000,
+  invoice_id: 'ORD-001',
+  callback_url: 'https://example.com/cb',
+  return_url: 'https://example.com/success',
+  description: 'Order payment'
+)
+invoice.data[:checkout_url]  # redirect user here
+
+# Get invoice info
+info = client.invoices.retrieve('ORD-001')
+
+# Cancel unpaid invoice
+client.invoices.cancel('ORD-001')
+
+# Quick Pay (Payme, Click, Uzum QR)
+client.invoices.quick_pay(invoice_id: 'ORD-001', service: 'payme')
+```
+
+## Payments
+
+### By Card Token
+
+```ruby
+payment = client.payments.create_by_token(
+  card_token: 'tok_abc',
+  amount: 500_000,
+  invoice_id: 'ORD-001',
+  callback_url: 'https://example.com/cb'
+)
+```
+
+### By Card Number (PCI DSS required)
+
+```ruby
+payment = client.payments.create_by_card(
+  card_number: '8600123456781234',
+  card_expiry: '1228',
+  amount: 500_000,
+  invoice_id: 'ORD-002'
+)
+```
+
+### Wallet Payment
+
+```ruby
+payment = client.payments.create_wallet(
+  service: 'payme',  # or 'click', 'uzum', etc.
+  amount: 300_000,
+  invoice_id: 'ORD-003'
+)
+```
+
+### Split Payment
+
+```ruby
+payment = client.payments.create_split(
+  card_token: 'tok_abc',
+  amount: 500_000,
+  invoice_id: 'ORD-004',
+  split: [
+    { type: 'account', amount: 400_000, details: 'Store share', recipient: 'uuid-1' },
+    { type: 'wallet', amount: 100_000, details: 'Platform fee' }
+  ]
+)
+```
+
+### OTP Confirmation
+
+```ruby
+client.payments.confirm('payment-uuid', otp_code: '123456')
+```
+
+### Refunds
+
+```ruby
+# Full refund
+client.payments.refund('payment-uuid')
+
+# Partial refund
+client.payments.partial_refund('payment-uuid', amount: 100_000)
+```
+
+### Fiscal Receipt
+
+```ruby
+client.payments.send_fiscal_link('payment-uuid', fiscal_url: 'https://ofd.uz/receipt/123')
+```
+
+### With OFD Data
+
+```ruby
+client.payments.create_by_token(
+  card_token: 'tok_abc',
+  amount: 500_000,
+  invoice_id: 'ORD-005',
+  ofd: [
+    { name: 'Product', price: 500_000, qty: 1, vat: 12,
+      tin: '123456789', mxik: '10202001001000000', package_code: '1508574' }
+  ]
+)
+```
+
+## Card Binding
+
+### Form-Based (recommended)
+
+```ruby
+# Get binding link
+link = client.cards.create_binding_link
+# Redirect user to: link.data[:url]
+
+# Check status (polling)
+status = client.cards.binding_status(link.data[:session_id])
+status.data[:token]  # card token when bound
+```
+
+### API-Based (PCI DSS required)
+
+```ruby
+# Send OTP
+client.cards.add(card_number: '8600123456781234', card_expiry: '1228')
+
+# Confirm with OTP
+result = client.cards.confirm_binding(otp_code: '123456')
+result.data[:token]
+```
+
+### Card Operations
+
+```ruby
+# Get card info
+card = client.cards.retrieve('card_token')
+
+# Check card number
+client.cards.check('8600123456781234')
+
+# Verify ownership (PINFL)
+client.cards.verify_pinfl(token: 'card_token', pinfl: '12345678901234')
+
+# Unbind card
+client.cards.revoke('card_token')
+```
+
+## Holds (Pre-Authorization)
+
+```ruby
+# Create hold
+hold = client.holds.create(
+  card_token: 'tok_abc',
+  amount: 500_000,
+  invoice_id: 'HOLD-001'
+)
+
+# Confirm hold (block funds)
+client.holds.confirm(hold.data[:id], otp_code: '123456')
+
+# Capture full amount
+client.holds.capture(hold.data[:id])
+
+# Capture partial amount
+client.holds.capture(hold.data[:id], amount: 300_000)
+
+# Cancel hold (release funds)
+client.holds.cancel(hold.data[:id])
+
+# Check hold status
+client.holds.retrieve(hold.data[:id])
+```
+
+## Payouts
+
+```ruby
+# Create payout
+payout = client.payouts.create(card_number: '8600999988887777', amount: 100_000)
+
+# Confirm payout
+client.payouts.confirm(payout.data[:id])
+
+# Check status
+client.payouts.retrieve(payout.data[:id])
+```
+
+## Registry
+
+```ruby
+# Payment registry
+client.registry.payments(date_from: '2025-01-01', date_to: '2025-01-31')
+
+# Payout history
+client.registry.payouts
+
+# Application info
+client.registry.application_info
+
+# Merchant banking details
+client.registry.merchant_details
+```
+
+## Webhook Verification
+
+Multicard signs callback requests with MD5: `sign = md5(store_id + invoice_id + amount + secret)`.
+
+`Signature.verify` handles this for you, including:
+- **Constant-time comparison** — prevents timing attacks (no `Rack` dependency needed)
+- **Amount normalization** — Multicard callbacks inconsistently format amounts (`"50000"`, `"50000.0"`, or `"50000.00"`). The signature is always computed against the integer form, so trailing `.0`/`.00` are stripped automatically.
+- **Case-insensitive** — uppercase/lowercase hex signatures both accepted
+
+```ruby
+# In your webhook controller:
+def multicard_callback
+  params = request.params.symbolize_keys
+
+  unless Multicard::Signature.verify(params, secret: ENV['MULTICARD_SECRET'])
+    head :unauthorized
+    return
+  end
+
+  payment = client.payments.retrieve(params[:uuid])
+  # Process payment...
+  head :ok
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.payments.create_by_token(
+    card_token: 'tok_abc',
+    amount: 500_000,
+    invoice_id: 'ORD-001'
+  )
+rescue Multicard::CardNotFoundError => e
+  # Card token is invalid or revoked
+rescue Multicard::InsufficientFundsError => e
+  # Not enough funds on the card
+rescue Multicard::CardExpiredError => e
+  # Card has expired
+rescue Multicard::DebitUnknownError => e
+  # Unknown debit status - poll for result
+  payment = client.payments.retrieve(e.response_body.dig(:data, :uuid))
+rescue Multicard::InvalidFieldsError => e
+  # Validation error - check e.error_details
+rescue Multicard::AuthenticationError => e
+  # Invalid credentials
+rescue Multicard::NetworkError => e
+  # Timeout or connection failure
+rescue Multicard::ServerError => e
+  # Multicard server error (5xx)
+rescue Multicard::Error => e
+  # Any other Multicard error
+  e.http_status     # HTTP status code
+  e.error_code      # Multicard error code string
+  e.error_details   # Human-readable error description
+  e.response_body   # Full response body hash
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec          # run tests
+bundle exec rubocop        # lint
+gem build multicard.gemspec  # build gem
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

data/lib/multicard/client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Multicard
+  class Client
+    attr_reader :config
+
+    def initialize(**options)
+      @config = if Multicard.configuration
+        Multicard.configuration.merge(options)
+      else
+        Configuration.new(**options)
+      end
+      @config.validate!
+      @http_client = HttpClient.new(@config)
+      @token_manager = TokenManager.new(@http_client, @config)
+    end
+
+    # Resource accessors (lazy-initialized)
+    def invoices  = @invoices ||= Resources::Invoices.new(self)
+    def payments  = @payments ||= Resources::Payments.new(self)
+    def cards     = @cards ||= Resources::Cards.new(self)
+    def holds     = @holds ||= Resources::Holds.new(self)
+    def payouts   = @payouts ||= Resources::Payouts.new(self)
+    def registry  = @registry ||= Resources::Registry.new(self)
+
+    # Execute an authenticated API request. Automatically retries once on 401.
+    #
+    # @param method [Symbol] :get, :post, or :delete
+    # @param path [String] API path
+    # @param body [Hash, nil] request body (for POST)
+    # @param params [Hash, nil] query params (for GET/DELETE)
+    # @return [Response]
+    def authenticated_request(method, path, body: nil, params: nil)
+      execute_authenticated(method, path, body: body, params: params)
+    rescue AuthenticationError
+      @token_manager.reset!
+      execute_authenticated(method, path, body: body, params: params)
+    end
+
+    private
+
+    def execute_authenticated(method, path, body: nil, params: nil)
+      headers = { 'Authorization' => "Bearer #{@token_manager.token}" }
+
+      case method
+      when :get
+        # GET is idempotent — safe to retry on transient failures (timeout, 429, 5xx)
+        @http_client.get_with_retry(path, params: params || {}, headers: headers)
+      when :post
+        # POST is NOT retried by default — retrying a payment could cause double charges.
+        # The 401 retry in authenticated_request is still applied (token refresh).
+        @http_client.post(path, body: body || {}, headers: headers)
+      when :delete
+        @http_client.delete(path, params: params || {}, headers: headers)
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+  end
+end

data/lib/multicard/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Multicard
+  class Configuration
+    attr_accessor :application_id, :secret, :base_url, :timeout, :open_timeout, :logger, :store_id
+
+    DEFAULT_BASE_URL = 'https://api.multicard.uz'
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    def initialize(**options)
+      @application_id = options[:application_id]
+      @secret = options[:secret]
+      @base_url = options[:base_url] || DEFAULT_BASE_URL
+      @timeout = options[:timeout] || DEFAULT_TIMEOUT
+      @open_timeout = options[:open_timeout] || DEFAULT_OPEN_TIMEOUT
+      @logger = options[:logger]
+      @store_id = options[:store_id]
+    end
+
+    def validate!
+      raise ArgumentError, 'application_id is required' if application_id.nil? || application_id.to_s.empty?
+      raise ArgumentError, 'secret is required' if secret.nil? || secret.to_s.empty?
+    end
+
+    # Merge per-client overrides into this configuration.
+    # Uses .key? for fields where nil/0/false are valid override values
+    # (e.g., store_id: nil to clear, timeout: 0 to disable).
+    def merge(overrides)
+      self.class.new(
+        application_id: overrides[:application_id] || application_id,
+        secret: overrides[:secret] || secret,
+        base_url: overrides[:base_url] || base_url,
+        timeout: overrides.key?(:timeout) ? overrides[:timeout] : timeout,
+        open_timeout: overrides.key?(:open_timeout) ? overrides[:open_timeout] : open_timeout,
+        logger: overrides.key?(:logger) ? overrides[:logger] : logger,
+        store_id: overrides.key?(:store_id) ? overrides[:store_id] : store_id
+      )
+    end
+  end
+end

data/lib/multicard/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Multicard
+  class Error < StandardError
+    attr_reader :http_status, :error_code, :error_details, :response_body
+
+    def initialize(message = nil, http_status: nil, error_code: nil, error_details: nil, response_body: nil)
+      @http_status = http_status
+      @error_code = error_code
+      @error_details = error_details
+      @response_body = response_body
+      super(message || error_details || 'Multicard API error')
+    end
+  end
+
+  # HTTP errors
+  class AuthenticationError < Error; end
+  class ValidationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+  class NetworkError < Error; end
+
+  # Business errors (from error.code in API response)
+  class CardNotFoundError < ValidationError; end
+  class InsufficientFundsError < ValidationError; end
+  class CardExpiredError < ValidationError; end
+  class DebitUnknownError < Error; end
+  class CallbackTimeoutError < Error; end
+  class InvalidFieldsError < ValidationError; end
+
+  # Maps Multicard error codes to Ruby exception classes
+  ERROR_MAP = {
+    'ERROR_CARD_NOT_FOUND' => CardNotFoundError,
+    'ERROR_INSUFFICIENT_FUNDS' => InsufficientFundsError,
+    'ERROR_CARD_EXPIRED' => CardExpiredError,
+    'ERROR_DEBIT_UNKNOWN' => DebitUnknownError,
+    'ERROR_CALLBACK_TIMEOUT' => CallbackTimeoutError,
+    'ERROR_FIELDS' => InvalidFieldsError
+  }.freeze
+end