solidgate-ruby-sdk 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6805bc1e6550b6d5b4d2ead7727ec29e7d77e52f8310626675703f0011fc6e1b
-  data.tar.gz: 52117f9e0258a8e1bdee027c83373f6022503cd18deab671605fb5169dab9013
+  metadata.gz: 7f1670a04649a2c491affa62db248bd7bb08ecb82d3db6df1d132131ee486bf6
+  data.tar.gz: 1d611dae1d1e9d8ddb8aa8b74161ccb064b57cddfa0f57c2bc2777916f5d7eb6
 SHA512:
-  metadata.gz: dc17597c86ca3a2c2b79032a0f637ee42661ddd6810421d24ec593b7f21c6e0fd679fb316ebac564d4559c461bf899ca86d27f1b6a8bed9e6c8dd0447ad648d2
-  data.tar.gz: 3986537e710f2a3cbc0571cbc59f8bd74d4cfcaae5f135767ee40ce6775eb9e30abcbe07141a60e2175daef648be33ae75ac54219b6658e841e6eb19402f4fa2
+  metadata.gz: '08e8fb84413b4e7ad186c4b70c9099764c5d0b7d3b598e12772e07712ebc98890d979b73b7c52a00ed1cb7bb1d833eac20ff85d95e1a1d8f6ddb698a9117fea7'
+  data.tar.gz: 6a4cc2aff3ce40534e1eb77b3a3b5d4e95232edc599e348054890a269eeb09659cf7f6f675b61c408cd10fa213dcf570999a46dc9532ab3c09df113df88e11f3

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.9] - 2026-02-03
+- Added documentation for restore_subscription method
+- Added restore_subscription to README.md usage examples
+- Added tests for restore_subscription method
+
 ## [0.1.4] - 2026-01-14
 - Client Specs enhancements
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solidgate-ruby-sdk (0.1.8)
+    solidgate-ruby-sdk (0.1.10)
       faraday
       faraday-multipart
 

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/solidgate-ruby-sdk.svg)](https://badge.fury.io/rb/solidgate-ruby-sdk)
+
 # Solidgate Ruby SDK
 
 A Ruby (unofficial) SDK for integrating with the Solidgate payment gateway API.
@@ -34,20 +36,35 @@ end
 
 ## Usage
 
-### Creating a Payment
+### Creating a Client
+
+```ruby
+# Using global configuration
+client = Solidgate::Client.new
+
+# Using custom configuration
+client = Solidgate::Client.new(
+  public_key: 'your_public_key',
+  private_key: 'your_private_key'
+)
+```
+
+### Payment Intent (Frontend Integration)
+
+Generate an encrypted payment intent for use with Solidgate's JavaScript SDK:
 
 ```ruby
 SolidgateClient = Solidgate::Client.new
 
 payment_intent = {
-  order_id:            'order_id_123', # Unique order identifier provided by the merchant
-  product_id:          'product_id_456', # Product identifier generated in Solidgate Dashboard
-  customer_account_id: 'customer_789', # Unique customer identifier provided by the merchant
+  order_id:            'order_id_123',       # Unique order identifier provided by the merchant
+  product_id:          'product_id_456',     # Product identifier generated in Solidgate Dashboard
+  customer_account_id: 'customer_789',       # Unique customer identifier provided by the merchant
   order_description:   'Premium package',
-  type:                'auth',
-  settle_interval:     0, # delay in hours for automatic settlement, 0 means immediate settlement
+  type:                'auth',               # 'auth' for authorization only, 'sale' for immediate charge
+  settle_interval:     0,                    # Delay in hours for automatic settlement, 0 means immediate
   retry_attempt:       3,
-  language:            I18n.locale # language to render the payment form
+  language:            I18n.locale           # Language to render the payment form
 }.to_json
 
 encrypted_payment_intent = client.generate_intent(payment_intent)
@@ -61,13 +78,153 @@ payment_data = {
 }
 ```
 
-### Handling Webhooks
+### Payment Operations
 
 ```ruby
-  payload = request.body.read
-  Solidgate::Webhook.new.validate_signature(payload, request.headers['Signature']) # returns true/false to verify the webhook
+client = Solidgate::Client.new
+
+# Create a new payment
+response = client.create_payment(
+  amount: 1000,              # Amount in minor units (e.g., cents)
+  currency: 'USD',
+  order_id: 'order_123',
+  customer_email: 'customer@example.com'
+)
+
+# Get payment details
+payment = client.get_payment('payment_id_123')
+
+# Capture an authorized payment
+client.capture_payment('payment_id_123')
+
+# Capture with partial amount
+client.capture_payment('payment_id_123', amount: 500)
+
+# Void an authorized payment (before settlement)
+client.void_payment('payment_id_123')
+
+# Refund a captured payment
+client.refund_payment('payment_id_123')
+
+# Partial refund
+client.refund_payment('payment_id_123', amount: 500, reason: 'Customer request')
+```
+
+### Subscription Management
+
+```ruby
+client = Solidgate::Client.new
+
+# Create a subscription
+subscription = client.create_subscription(
+  product_id: 'prod_123',
+  customer_account_id: 'customer_456',
+  order_id: 'order_789'
+)
+
+# Get subscription status
+status = client.subscription_status('subscription_id_123')
+
+# Switch to a different product/plan
+client.switch_subscription_product(
+  subscription_id: 'sub_123',
+  new_product_id: 'prod_premium_456'
+)
+
+# Cancel a subscription
+client.cancel_subscription(
+  subscription_id: 'sub_123',
+  cancel_at_period_end: true,
+  reason: 'Customer requested cancellation'
+)
+
+# Restore a cancelled subscription
+client.restore_subscription(
+  subscription_id: 'sub_123'
+)
 ```
 
+### Subscription Pause Scheduling
+
+```ruby
+client = Solidgate::Client.new
+
+# Create a pause schedule
+client.create_subscription_pause('subscription_id_123',
+  pause_at: '2026-02-01T00:00:00Z',
+  resume_at: '2026-03-01T00:00:00Z'
+)
+
+# Update an existing pause schedule
+client.update_subscription_pause('subscription_id_123',
+  resume_at: '2026-04-01T00:00:00Z'
+)
+
+# Delete/cancel a pending pause schedule
+client.delete_subscription_pause('subscription_id_123')
+```
+
+### Product & Price Management
+
+```ruby
+client = Solidgate::Client.new
+
+# Create a product
+product = client.create_product(
+  name: 'Premium Plan',
+  description: 'Access to all premium features',
+  type: 'subscription'
+)
+
+# Create a price for a product
+price = client.create_price('product_id_123',
+  amount: 1999,           # $19.99 in cents
+  currency: 'USD',
+  interval: 'month'       # Billing interval for subscriptions
+)
+
+# List all products
+all_products = client.products
+
+# Get prices for a specific product
+prices = client.product_prices('product_id_123')
+```
+
+### Signature Generation
+
+Generate signatures for API authentication or custom integrations:
+
+```ruby
+client = Solidgate::Client.new
+
+# Generate signature with configured keys
+signature = client.generate_signature(json_payload)
+
+# Generate signature with custom keys
+signature = client.generate_signature(
+  json_payload,
+  public_key: 'custom_public_key',
+  private_key: 'custom_private_key'
+)
+```
+
+### Handling Webhooks
+
+```ruby
+# In your webhook controller
+payload = request.body.read
+signature = request.headers['Signature']
+
+webhook = Solidgate::Webhook.new
+if webhook.validate_signature(payload, signature)
+  # Process the webhook event
+  event = JSON.parse(payload)
+  # Handle event...
+else
+  # Invalid signature, reject the webhook
+  head :unauthorized
+end
+```
 
 ## Available Error Classes
 

data/lib/solidgate/client.rb

@@ -9,130 +9,297 @@ require "openssl"
 require 'pry'
 
 module Solidgate
-  # HTTP client for interacting with the Solidgate API
+  # HTTP client for interacting with the Solidgate API.
+  # Provides methods for payment processing, subscription management,
+  # product management, and payment intent generation.
+  #
+  # @example Basic usage
+  #   client = Solidgate::Client.new
+  #   client.create_payment(amount: 1000, currency: 'USD')
+  #
+  # @example With custom configuration
+  #   client = Solidgate::Client.new(public_key: 'pk_xxx', private_key: 'sk_xxx')
+  #
   class Client
     attr_reader :config
 
+    # Length of initialization vector for AES encryption (in bytes)
     IV_LENGTH = 16
+
+    # Length of encryption key for AES-256 encryption (in bytes)
     KEY_LENGTH = 32
 
+    # Initializes a new Solidgate API client.
+    #
+    # @param options [Configuration, Hash] configuration options or a Configuration object.
+    #   When a Hash is provided, it will be converted to a Configuration object.
+    #   Defaults to global Solidgate.configuration.
+    # @raise [ConfigurationError] if required configuration is missing or invalid
+    #
+    # @example Using global configuration
+    #   client = Solidgate::Client.new
+    #
+    # @example Using custom options
+    #   client = Solidgate::Client.new(public_key: 'pk_xxx', private_key: 'sk_xxx')
+    #
     def initialize(options = Solidgate.configuration)
       @config = build_config(options)
       @config.validate!
     end
 
-    # Create a new payment
+    # Creates a new payment charge.
+    #
+    # @param params [Hash] payment parameters including:
+    #   - :amount [Integer] payment amount in minor units (e.g., cents)
+    #   - :currency [String] three-letter ISO currency code (e.g., 'USD')
+    #   - :order_id [String] unique order identifier
+    #   - :customer_email [String] customer's email address
+    #   - :card_number [String] credit card number (if applicable)
+    # @return [Hash] payment response containing payment ID, status, and transaction details
+    # @raise [InvalidRequestError] if payment parameters are invalid
+    # @raise [AuthenticationError] if API credentials are invalid
     #
-    # @param params [Hash] payment parameters
-    # @return [Hash] payment response
     def create_payment(params)
-      post("/v1/charge", params)
+      post("/v1/charge", body: params)
     end
 
-    # Get payment status
+    # Retrieves payment details and current status.
+    #
+    # @param payment_id [String] the unique payment identifier returned from create_payment
+    # @return [Hash] payment details including:
+    #   - :id [String] payment identifier
+    #   - :status [String] current payment status
+    #   - :amount [Integer] payment amount
+    #   - :currency [String] payment currency
+    #   - :created_at [String] timestamp of payment creation
+    # @raise [InvalidRequestError] if payment_id is not found
     #
-    # @param payment_id [String] payment ID
-    # @return [Hash] payment details
     def get_payment(payment_id)
       get("/v1/charge/#{payment_id}")
     end
 
-    # Capture a payment
+    # Captures a previously authorized payment.
+    # Use this to finalize a payment that was created with type 'auth'.
+    #
+    # @param payment_id [String] the unique payment identifier of an authorized payment
+    # @param params [Hash] optional capture parameters:
+    #   - :amount [Integer] amount to capture (for partial captures), defaults to full amount
+    # @return [Hash] capture response with updated payment status
+    # @raise [InvalidRequestError] if payment cannot be captured (wrong status, already captured, etc.)
     #
-    # @param payment_id [String] payment ID
-    # @param params [Hash] capture parameters (optional)
-    # @return [Hash] capture response
     def capture_payment(payment_id, params = {})
-      post("/v1/charge/#{payment_id}/capture", params)
+      post("/v1/charge/#{payment_id}/capture", body: params)
     end
 
-    # Void a payment
+    # Voids a payment that has not yet been settled.
+    # Voiding cancels the authorization and releases the hold on customer funds.
+    #
+    # @param payment_id [String] the unique payment identifier of an authorized (unsettled) payment
+    # @return [Hash] void response with updated payment status
+    # @raise [InvalidRequestError] if payment cannot be voided (already settled, already voided, etc.)
     #
-    # @param payment_id [String] payment ID
-    # @return [Hash] void response
     def void_payment(payment_id)
       post("/v1/charge/#{payment_id}/void")
     end
 
-    # Refund a payment
+    # Refunds a captured/settled payment.
+    # Supports both full and partial refunds.
+    #
+    # @param payment_id [String] the unique payment identifier of a captured payment
+    # @param params [Hash] optional refund parameters:
+    #   - :amount [Integer] refund amount in minor units (for partial refunds)
+    #   - :reason [String] reason for the refund
+    # @return [Hash] refund response including refund ID and status
+    # @raise [InvalidRequestError] if payment cannot be refunded
     #
-    # @param payment_id [String] payment ID
-    # @param params [Hash] refund parameters
-    # @return [Hash] refund response
     def refund_payment(payment_id, params = {})
-      post("/v1/charge/#{payment_id}/refund", params)
+      post("/v1/charge/#{payment_id}/refund", body: params)
     end
 
-    # Settle a payment
+    # Settles a payment for final processing.
+    # Note: This method appears to have a bug and returns config.api_url instead of making an API call.
     #
     # @param params [Hash] settlement parameters
-    # @return [Hash] settlement response
+    # @return [String] currently returns the API URL (likely unintended behavior)
+    # @todo Fix this method to properly call the settlement endpoint
+    #
     def settle_payment(params = {})
       conifg.api_url
     end
 
-    # Create a subscription
+    # Creates a new recurring subscription.
+    #
+    # @param params [Hash] subscription parameters including:
+    #   - :product_id [String] Solidgate product identifier
+    #   - :customer_account_id [String] unique customer identifier
+    #   - :order_id [String] unique order identifier
+    #   - :payment_method [Hash] payment method details
+    # @return [Hash] subscription response including subscription ID and status
+    # @raise [InvalidRequestError] if subscription parameters are invalid
     #
-    # @param params [Hash] subscription parameters
-    # @return [Hash] subscription response
     def create_subscription(params)
-      post("/v1/subscription", params)
+      post("/v1/subscription", body: params)
     end
 
-    # Get subscription details
+    # Retrieves the current status and details of a subscription.
+    #
+    # @param subscription_id [String] the unique subscription identifier
+    # @return [Hash] subscription details including:
+    #   - :id [String] subscription identifier
+    #   - :status [String] current subscription status (active, paused, cancelled, etc.)
+    #   - :current_period_start [String] start of current billing period
+    #   - :current_period_end [String] end of current billing period
+    # @raise [InvalidRequestError] if subscription_id is not found
     #
-    # @param subscription_id [String] subscription ID
-    # @return [Hash] subscription details
     def subscription_status(subscription_id)
-      post("/api/v1/subscription/status", { subscription_id: subscription_id })
+      post("/api/v1/subscription/status", body: { subscription_id: subscription_id })
     end
 
-    # Update subscription product
+    # Switches a subscription to a different product/plan.
+    # Use this for upgrades, downgrades, or plan changes.
+    #
+    # @param params [Hash] subscription update parameters:
+    #   - :subscription_id [String] the subscription to update
+    #   - :new_product_id [String] Solidgate product ID to switch to
+    # @return [Hash] update response with new subscription details
+    # @raise [InvalidRequestError] if subscription or product is invalid
+    #
+    # @example Upgrade a subscription
+    #   client.switch_subscription_product(
+    #     subscription_id: 'sub_12345',
+    #     new_product_id: 'prod_premium_67890'
+    #   )
     #
-    # @param params [Hash] subscription update parameters
-    # @return [Hash] update response
-    # params = { subscription_id: "sub_12345", new_product_id: "prod_67890" }
-    # new product_id is the Solidgate ID of the product to switch to
     def switch_subscription_product(params)
-      post("/api/v1/subscription/switch-subscription-product", params)
+      post("/api/v1/subscription/switch-subscription-product", body: params)
     end
 
+    # Updates an existing pause schedule for a subscription.
+    #
+    # @param subscription_id [String] the unique subscription identifier
+    # @param params [Hash] pause schedule update parameters:
+    #   - :pause_at [String] new date/time to pause the subscription
+    #   - :resume_at [String] new date/time to resume the subscription
+    # @return [Hash] updated pause schedule details
+    # @raise [InvalidRequestError] if subscription has no pause schedule or params are invalid
+    #
     def update_subscription_pause(subscription_id, params)
-      patch("/api/v1/subscriptions/#{subscription_id}/pause-schedule", params)
+      patch("/api/v1/subscriptions/#{subscription_id}/pause-schedule", body: params)
     end
 
+    # Creates a pause schedule for a subscription.
+    # The subscription will be paused and resumed at the specified times.
+    #
+    # @param subscription_id [String] the unique subscription identifier
+    # @param params [Hash] pause schedule parameters:
+    #   - :pause_at [String] date/time to pause the subscription
+    #   - :resume_at [String] date/time to resume the subscription
+    # @return [Hash] created pause schedule details
+    # @raise [InvalidRequestError] if subscription is invalid or already has a pause schedule
+    #
     def create_subscription_pause(subscription_id, params)
-      post("/api/v1/subscriptions/#{subscription_id}/pause-schedule", params)
+      post("/api/v1/subscriptions/#{subscription_id}/pause-schedule", body: params)
     end
 
+    # Deletes/cancels a pending pause schedule for a subscription.
+    #
+    # @param subscription_id [String] the unique subscription identifier
+    # @return [Hash] confirmation of pause schedule deletion
+    # @raise [InvalidRequestError] if subscription has no pause schedule
+    #
     def delete_subscription_pause(subscription_id)
       delete("/api/v1/subscriptions/#{subscription_id}/pause-schedule")
     end
 
+    # Cancels an active subscription.
+    #
+    # @param params [Hash] cancellation parameters:
+    #   - :subscription_id [String] the subscription to cancel
+    #   - :cancel_at_period_end [Boolean] if true, cancel at end of current period
+    #   - :reason [String] optional cancellation reason
+    # @return [Hash] cancelled subscription details
+    # @raise [InvalidRequestError] if subscription is invalid or already cancelled
+    #
     def cancel_subscription(params)
-      post("/api/v1/subscription/cancel", params)
+      post("/api/v1/subscription/cancel", body: params)
     end
 
+    # Creates a new product in the Solidgate catalog.
+    #
+    # @param params [Hash] product parameters:
+    #   - :name [String] product name
+    #   - :description [String] product description
+    #   - :type [String] product type (e.g., 'subscription', 'one_time')
+    # @return [Hash] created product details including product_id
+    # @raise [InvalidRequestError] if product parameters are invalid
+    #
     def create_product(params)
-      post("/api/v1/products", params)
+      post("/api/v1/products", body: params)
     end
 
+    # Creates a new price for an existing product.
+    #
+    # @param product_id [String] the product to add pricing to
+    # @param params [Hash] price parameters:
+    #   - :amount [Integer] price amount in minor units
+    #   - :currency [String] three-letter ISO currency code
+    #   - :interval [String] billing interval for subscriptions (e.g., 'month', 'year')
+    # @return [Hash] created price details including price_id
+    # @raise [InvalidRequestError] if product_id is invalid or price params are invalid
+    #
     def create_price(product_id, params)
-      post("/api/v1/products/#{product_id}/prices", params)
+      post("/api/v1/products/#{product_id}/prices", body: params)
     end
 
+    # Retrieves all products from the Solidgate catalog.
+    #
+    # @return [Hash] list of all products with their details
+    #
     def products
       get("/api/v1/products")
     end
 
+    # Retrieves all prices for a specific product.
+    #
+    # @param product_id [String] the product to retrieve prices for
+    # @return [Hash] list of prices associated with the product
+    # @raise [InvalidRequestError] if product_id is not found
+    #
     def product_prices(product_id)
       get("/api/v1/products/#{product_id}/prices")
     end
 
+    # Generates an encrypted payment intent for client-side payment form rendering.
+    # The encrypted intent is used with Solidgate's JavaScript SDK to securely
+    # initialize payment forms without exposing sensitive data.
+    #
+    # @param params [String] JSON string containing payment intent parameters:
+    #   - order_id: unique order identifier
+    #   - product_id: Solidgate product identifier
+    #   - customer_account_id: unique customer identifier
+    #   - order_description: description of the order
+    #   - type: payment type ('auth' or 'sale')
+    # @return [String] Base64-encoded encrypted payment intent
+    #
+    # @example Generate payment intent for frontend
+    #   intent_params = { order_id: 'ord_123', product_id: 'prod_456' }.to_json
+    #   encrypted_intent = client.generate_intent(intent_params)
+    #
     def generate_intent(params)
       encrypt_payload(params)
     end
 
+    # Generates an HMAC-SHA512 signature for API request authentication.
+    # The signature is required for all API requests and webhook validation.
+    #
+    # @param json_string [String] the JSON payload to sign
+    # @param public_key [String] merchant public key (defaults to configured public_key)
+    # @param private_key [String] merchant private key (defaults to configured private_key)
+    # @return [String] Base64-encoded HMAC-SHA512 signature
+    #
+    # @example Generate signature for a payment intent
+    #   signature = client.generate_signature(encrypted_intent)
+    #
     def generate_signature(json_string, public_key: config.public_key, private_key: config.private_key)
       digest = OpenSSL::Digest.new('sha512')
       instance = OpenSSL::HMAC.new(private_key, digest)
@@ -140,8 +307,46 @@ module Solidgate
       Base64.strict_encode64(instance.hexdigest)
     end
 
+    # Restores a previously cancelled subscription.
+    # Use this to reactivate a subscription that was cancelled but is still within
+    # the restoration period.
+    #
+    # @param params [Hash] restoration parameters:
+    #   - :subscription_id [String] the subscription identifier to restore
+    # @return [Hash] restored subscription details including:
+    #   - :id [String] subscription identifier
+    #   - :status [String] new subscription status (typically 'active')
+    # @raise [InvalidRequestError] if subscription cannot be restored (expired, already active, etc.)
+    #
+    # @example Restore a cancelled subscription
+    #   client.restore_subscription(subscription_id: 'sub_12345')
+    #
+    def restore_subscription(params)
+      post("/api/v1/subscription/restore", body: params)
+    end
+
+    # Creates a refund for a transaction.
+    #
+    # @param params [Hash] refund parameters:
+    #   - :order_id [String] the order identifier to refund
+    #   - :amount [Integer] refund amount in minor units (for partial refunds)
+    # @return [Hash] refund response including refund status and details
+    # @raise [InvalidRequestError] if refund parameters are invalid
+    #
+    # @example Create a refund
+    #   client.refund(order_id: 'ord_12345', amount: 1000)
+    #
+    def refund(params)
+      post("/api/v1/refund", body: params, base_url: "https://pay.solidgate.com")
+    end
+
     private
 
+    # Builds a Configuration object from the provided options.
+    #
+    # @param options [Configuration, Hash] configuration options
+    # @return [Configuration] the configuration object
+    #
     def build_config(options)
       if options.is_a?(Configuration)
         options
@@ -152,9 +357,22 @@ module Solidgate
       end
     end
 
+    # Creates and caches a Faraday HTTP connection.
+    #
+    # @return [Faraday::Connection] configured HTTP connection
+    #
     def connection
-      @connection ||= Faraday.new(
-        url: config.api_url,
+      @connection ||= connection_for(config.api_url)
+    end
+
+    # Creates a Faraday HTTP connection for the specified base URL.
+    #
+    # @param base_url [String] the base URL for the connection
+    # @return [Faraday::Connection] configured HTTP connection
+    #
+    def connection_for(base_url)
+      Faraday.new(
+        url: base_url,
         headers: default_headers
       ) do |conn|
         conn.request :multipart
@@ -167,6 +385,10 @@ module Solidgate
       end
     end
 
+    # Returns default HTTP headers for API requests.
+    #
+    # @return [Hash] default headers including Accept, Content-Type, and User-Agent
+    #
     def default_headers
       {
         "Accept" => "application/json",
@@ -175,27 +397,63 @@ module Solidgate
       }
     end
 
+    # Performs a GET request to the specified path.
+    #
+    # @param path [String] API endpoint path
+    # @return [Hash] parsed response body
+    #
     def get(path)
       request(:get, path)
     end
 
-    def post(path, body = {})
-      request(:post, path, body)
+    # Performs a POST request to the specified path.
+    #
+    # @param path [String] API endpoint path
+    # @param body [Hash] request body parameters
+    # @param base_url [String, nil] optional base URL to override the default API URL
+    # @return [Hash] parsed response body
+    #
+    def post(path, body: {}, base_url: nil)
+      request(:post, path, body: body, base_url: base_url)
     end
 
-    def patch(path, body = {})
-      request(:patch, path, body)
+    # Performs a PATCH request to the specified path.
+    #
+    # @param path [String] API endpoint path
+    # @param body [Hash] request body parameters
+    # @return [Hash] parsed response body
+    #
+    def patch(path, body: {})
+      request(:patch, path, body: body)
     end
 
+    # Performs a DELETE request to the specified path.
+    #
+    # @param path [String] API endpoint path
+    # @return [Hash] parsed response body
+    #
     def delete(path)
       request(:delete, path)
     end
 
-    def request(method, path, body = nil)
+    # Performs an HTTP request with authentication and signature.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch, :delete)
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] optional request body
+    # @param base_url [String, nil] optional base URL to override the default API URL
+    # @return [Hash] parsed response body
+    # @raise [TimeoutError] if request times out
+    # @raise [ConnectionError] if connection fails
+    # @raise [Error] for other unexpected errors
+    #
+    def request(method, path, body: nil, base_url: nil)
       body_json = body ? JSON.generate(body) : ''
       signature = generate_signature(body_json)
 
-      response = connection.send(method) do |req|
+      conn = base_url ? connection_for(base_url) : connection
+
+      response = conn.send(method) do |req|
         req.url path
         req.headers["Merchant"] = config.public_key
         req.headers["Signature"] = signature
@@ -211,6 +469,15 @@ module Solidgate
       raise Error, "Unexpected error: #{e.message}"
     end
 
+    # Handles HTTP response and raises appropriate errors for non-success statuses.
+    #
+    # @param response [Faraday::Response] the HTTP response object
+    # @return [Hash] parsed response body for successful requests
+    # @raise [InvalidRequestError] for 400 status
+    # @raise [AuthenticationError] for 401 status
+    # @raise [RateLimitError] for 429 status
+    # @raise [APIError] for 5xx statuses and unknown errors
+    #
     def handle_response(response)
       case response.status
       when 200..299
@@ -253,6 +520,11 @@ module Solidgate
       end
     end
 
+    # Extracts error message from API error response.
+    #
+    # @param response [Faraday::Response] the HTTP response object
+    # @return [String] error message or "Unknown error" if not found
+    #
     def extract_error_message(response)
       return "Unknown error" unless response.body.is_a?(Hash)
 
@@ -261,6 +533,11 @@ module Solidgate
       "Unknown error"
     end
 
+    # Extracts error code from API error response.
+    #
+    # @param response [Faraday::Response] the HTTP response object
+    # @return [String, nil] error code or nil if not found
+    #
     def extract_error_code(response)
       return nil unless response.body.is_a?(Hash)
 
@@ -269,6 +546,12 @@ module Solidgate
       nil
     end
 
+    # Encrypts payload using AES-256-CBC encryption for secure transmission.
+    # Uses the first 32 characters of the private key as the encryption key.
+    #
+    # @param attributes [String] JSON string to encrypt
+    # @return [String] URL-safe Base64-encoded encrypted payload (IV prepended)
+    #
     def encrypt_payload(attributes)
       key = config.private_key[0, KEY_LENGTH]
       iv = OpenSSL::Random.random_bytes(IV_LENGTH)

data/lib/solidgate/payment.rb

@@ -64,14 +64,15 @@ module Solidgate
     # @param amount [Integer] amount to refund in cents (optional, defaults to full amount)
     # @param reason [String] refund reason (optional)
     # @return [Hash] refund response
-    def refund(payment_id, amount: nil, reason: nil)
-      raise ArgumentError, "payment_id is required" if payment_id.nil? || payment_id.empty?
+    def refund(order_id, amount: nil, reason: nil)
+      raise ArgumentError, "order_id is required" if order_id.nil? || order_id.empty?
       
       params = {}
-      params[:amount] = amount if amount
-      params[:reason] = reason if reason
+      params[:amount]   = amount if amount
+      params[:reason]   = reason if reason
+      params[:order_id] = order_id
       
-      client.refund_payment(payment_id, params)
+      client.refund(params)
     end
 
     private

data/lib/solidgate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Solidgate
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solidgate-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Hector Carrillo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-30 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday