Class: Solidgate::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/solidgate/client.rb

Overview

HTTP client for interacting with the Solidgate API. Provides methods for payment processing, subscription management, product management, and payment intent generation.

Examples:

Basic usage

client = Solidgate::Client.new
client.create_payment(amount: 1000, currency: 'USD')

With custom configuration

client = Solidgate::Client.new(public_key: 'pk_xxx', private_key: 'sk_xxx')

Constant Summary collapse

IV_LENGTH =

Length of initialization vector for AES encryption (in bytes)

16
KEY_LENGTH =

Length of encryption key for AES-256 encryption (in bytes)

32

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = Solidgate.configuration) ⇒ Client

Initializes a new Solidgate API client.

Examples:

Using global configuration

client = Solidgate::Client.new

Using custom options

client = Solidgate::Client.new(public_key: 'pk_xxx', private_key: 'sk_xxx')

Parameters:

  • options (Configuration, Hash) (defaults to: Solidgate.configuration) —

    configuration options or a Configuration object. When a Hash is provided, it will be converted to a Configuration object. Defaults to global Solidgate.configuration.

Raises:



45
46
47
48
 
# File 'lib/solidgate/client.rb', line 45

def initialize(options = Solidgate.configuration)
  @config = build_config(options)
  @config.validate!
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



24
25
26
 
# File 'lib/solidgate/client.rb', line 24

def config
  @config
end

Instance Method Details

#alt_refund(params) ⇒ Hash

Creates a refund for an alternative transaction (paypal, bizum, others).

Examples:

Create a refund

client.refund(order_id: 'ord_12345', amount: 1000)

Parameters:

  • params (Hash) —

    refund parameters:

    • :order_id [String] the order identifier to refund

    • :amount [Integer] refund amount in minor units (for partial refunds)

Returns:

  • (Hash) —

    refund response including refund status and details

Raises:



385
386
387
 
# File 'lib/solidgate/client.rb', line 385

def alt_refund(params)
  post("/api/v1/refund", body: params, base_url: "https://gate.solidgate.com")
end

#cancel_subscription(params) ⇒ Hash

Cancels an active subscription.

Parameters:

  • 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

Returns:

  • (Hash) —

    cancelled subscription details

Raises:



223
224
225
 
# File 'lib/solidgate/client.rb', line 223

def cancel_subscription(params)
  post("/api/v1/subscription/cancel", body: params)
end

#capture_payment(payment_id, params = {}) ⇒ Hash

Captures a previously authorized payment. Use this to finalize a payment that was created with type ‘auth’.

Parameters:

  • payment_id (String) —

    the unique payment identifier of an authorized payment

  • params (Hash) (defaults to: {}) —

    optional capture parameters:

    • :amount [Integer] amount to capture (for partial captures), defaults to full amount

Returns:

  • (Hash) —

    capture response with updated payment status

Raises:

  • (InvalidRequestError) —

    if payment cannot be captured (wrong status, already captured, etc.)



90
91
92
 
# File 'lib/solidgate/client.rb', line 90

def capture_payment(payment_id, params = {})
  post("/v1/charge/#{payment_id}/capture", body: params)
end

#create_payment(params) ⇒ Hash

Creates a new payment charge.

Parameters:

  • 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)

Returns:

  • (Hash) —

    payment response containing payment ID, status, and transaction details

Raises:



62
63
64
 
# File 'lib/solidgate/client.rb', line 62

def create_payment(params)
  post("/v1/charge", body: params)
end

#create_price(product_id, params) ⇒ Hash

Creates a new price for an existing product.

Parameters:

  • product_id (String) —

    the product to add pricing to

  • 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’)

Returns:

  • (Hash) —

    created price details including price_id

Raises:



250
251
252
 
# File 'lib/solidgate/client.rb', line 250

def create_price(product_id, params)
  post("/api/v1/products/#{product_id}/prices", body: params)
end

#create_product(params) ⇒ Hash

Creates a new product in the Solidgate catalog.

Parameters:

  • params (Hash) —

    product parameters:

    • :name [String] product name

    • :description [String] product description

    • :type [String] product type (e.g., ‘subscription’, ‘one_time’)

Returns:

  • (Hash) —

    created product details including product_id

Raises:



236
237
238
 
# File 'lib/solidgate/client.rb', line 236

def create_product(params)
  post("/api/v1/products", body: params)
end

#create_subscription(params) ⇒ Hash

Creates a new recurring subscription.

Parameters:

  • 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

Returns:

  • (Hash) —

    subscription response including subscription ID and status

Raises:



140
141
142
 
# File 'lib/solidgate/client.rb', line 140

def create_subscription(params)
  post("/v1/subscription", body: params)
end

#create_subscription_pause(subscription_id, params) ⇒ Hash

Creates a pause schedule for a subscription. The subscription will be paused and resumed at the specified times.

Parameters:

  • subscription_id (String) —

    the unique subscription identifier

  • params (Hash) —

    pause schedule parameters:

    • :pause_at [String] date/time to pause the subscription

    • :resume_at [String] date/time to resume the subscription

Returns:

  • (Hash) —

    created pause schedule details

Raises:



200
201
202
 
# File 'lib/solidgate/client.rb', line 200

def create_subscription_pause(subscription_id, params)
  post("/api/v1/subscriptions/#{subscription_id}/pause-schedule", body: params)
end

#delete_subscription_pause(subscription_id) ⇒ Hash

Deletes/cancels a pending pause schedule for a subscription.

Parameters:

  • subscription_id (String) —

    the unique subscription identifier

Returns:

  • (Hash) —

    confirmation of pause schedule deletion

Raises:



210
211
212
 
# File 'lib/solidgate/client.rb', line 210

def delete_subscription_pause(subscription_id)
  delete("/api/v1/subscriptions/#{subscription_id}/pause-schedule")
end

#generate_intent(params) ⇒ String

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.

Examples:

Generate payment intent for frontend

intent_params = { order_id: 'ord_123', product_id: 'prod_456' }.to_json
encrypted_intent = client.generate_intent(intent_params)

Parameters:

  • 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’)

Returns:

  • (String) —

    Base64-encoded encrypted payment intent



288
289
290
 
# File 'lib/solidgate/client.rb', line 288

def generate_intent(params)
  encrypt_payload(params)
end

#generate_signature(json_string, public_key: config.public_key, private_key: config.private_key) ⇒ String

Generates an HMAC-SHA512 signature for API request authentication. The signature is required for all API requests and webhook validation.

Examples:

Generate signature for a payment intent

signature = client.generate_signature(encrypted_intent)

Parameters:

  • json_string (String) —

    the JSON payload to sign

  • public_key (String) (defaults to: config.public_key) —

    merchant public key (defaults to configured public_key)

  • private_key (String) (defaults to: config.private_key) —

    merchant private key (defaults to configured private_key)

Returns:

  • (String) —

    Base64-encoded HMAC-SHA512 signature



334
335
336
337
338
339
 
# File 'lib/solidgate/client.rb', line 334

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)
  instance.update(public_key + json_string + public_key)
  Base64.strict_encode64(instance.hexdigest)
end

#get_payment(payment_id) ⇒ Hash

Retrieves payment details and current status.

Parameters:

  • payment_id (String) —

    the unique payment identifier returned from create_payment

Returns:

  • (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

Raises:



77
78
79
 
# File 'lib/solidgate/client.rb', line 77

def get_payment(payment_id)
  get("/v1/charge/#{payment_id}")
end

#make_apm_recurring(params) ⇒ Object 



424
425
426
 
# File 'lib/solidgate/client.rb', line 424

def make_apm_recurring(params)
  post('/api/v1/recurring', body: params, base_url: "https://gate.solidgate.com")
end

#make_card_recurring(params) ⇒ Object 



420
421
422
 
# File 'lib/solidgate/client.rb', line 420

def make_card_recurring(params)
  post('/api/v1/recurring', body: params, base_url: "https://pay.solidgate.com")
end

#order_status(params) ⇒ Hash

Retrieves order status from Solidgate pay domain.

Examples:

Get order status

client.order_status(order_id: 'order_123')

Parameters:

  • params (Hash) —

    status request parameters:

    • :order_id [String] unique order identifier

    • :payment_id [String] optional payment identifier

Returns:

  • (Hash) —

    order status response

Raises:



416
417
418
 
# File 'lib/solidgate/client.rb', line 416

def order_status(params)
  post('/api/v1/status', body: params, base_url: "https://pay.solidgate.com")
end

#product_prices(product_id) ⇒ Hash

Retrieves all prices for a specific product.

Parameters:

  • product_id (String) —

    the product to retrieve prices for

Returns:

  • (Hash) —

    list of prices associated with the product

Raises:



268
269
270
 
# File 'lib/solidgate/client.rb', line 268

def product_prices(product_id)
  get("/api/v1/products/#{product_id}/prices")
end

#products ⇒ Hash

Retrieves all products from the Solidgate catalog.

Returns:

  • (Hash) —

    list of all products with their details



258
259
260
 
# File 'lib/solidgate/client.rb', line 258

def products
  get("/api/v1/products")
end

#refund(params) ⇒ Hash

Creates a refund for a transaction.

Examples:

Create a refund

client.refund(order_id: 'ord_12345', amount: 1000)

Parameters:

  • params (Hash) —

    refund parameters:

    • :order_id [String] the order identifier to refund

    • :amount [Integer] refund amount in minor units (for partial refunds)

Returns:

  • (Hash) —

    refund response including refund status and details

Raises:



370
371
372
 
# File 'lib/solidgate/client.rb', line 370

def refund(params)
  post("/api/v1/refund", body: params, base_url: "https://pay.solidgate.com")
end

#refund_payment(payment_id, params = {}) ⇒ Hash

Refunds a captured/settled payment. Supports both full and partial refunds.

Parameters:

  • payment_id (String) —

    the unique payment identifier of a captured payment

  • params (Hash) (defaults to: {}) —

    optional refund parameters:

    • :amount [Integer] refund amount in minor units (for partial refunds)

    • :reason [String] reason for the refund

Returns:

  • (Hash) —

    refund response including refund ID and status

Raises:



115
116
117
 
# File 'lib/solidgate/client.rb', line 115

def refund_payment(payment_id, params = {})
  post("/v1/charge/#{payment_id}/refund", body: params)
end

#restore_subscription(params) ⇒ Hash

Restores a previously cancelled subscription. Use this to reactivate a subscription that was cancelled but is still within the restoration period.

Examples:

Restore a cancelled subscription

client.restore_subscription(subscription_id: 'sub_12345')

Parameters:

  • params (Hash) —

    restoration parameters:

    • :subscription_id [String] the subscription identifier to restore

Returns:

  • (Hash) —

    restored subscription details including:

    • :id [String] subscription identifier

    • :status [String] new subscription status (typically ‘active’)

Raises:



355
356
357
 
# File 'lib/solidgate/client.rb', line 355

def restore_subscription(params)
  post("/api/v1/subscription/restore", body: params)
end

#settle_payment(params = {}) ⇒ String

TODO:

Fix this method to properly call the settlement endpoint

Settles a payment for final processing. Note: This method currently has a bug and returns config.api_url instead of making an API call.

Parameters:

  • params (Hash) (defaults to: {}) —

    settlement parameters

Returns:

  • (String) —

    currently returns the API URL (likely unintended behavior)



126
127
128
 
# File 'lib/solidgate/client.rb', line 126

def settle_payment(params = {})
  config.api_url
end

#subscription_status(subscription_id) ⇒ Hash

Retrieves the current status and details of a subscription.

Parameters:

  • subscription_id (String) —

    the unique subscription identifier

Returns:

  • (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

Raises:



154
155
156
 
# File 'lib/solidgate/client.rb', line 154

def subscription_status(subscription_id)
  post("/api/v1/subscription/status", body: { subscription_id: subscription_id })
end

#switch_subscription_product(params) ⇒ Hash

Switches a subscription to a different product/plan. Use this for upgrades, downgrades, or plan changes.

Examples:

Upgrade a subscription

client.switch_subscription_product(
  subscription_id: 'sub_12345',
  new_product_id: 'prod_premium_67890'
)

Parameters:

  • params (Hash) —

    subscription update parameters:

    • :subscription_id [String] the subscription to update

    • :new_product_id [String] Solidgate product ID to switch to

Returns:

  • (Hash) —

    update response with new subscription details

Raises:



173
174
175
 
# File 'lib/solidgate/client.rb', line 173

def switch_subscription_product(params)
  post("/api/v1/subscription/switch-subscription-product", body: params)
end

#update_product(product_id, params) ⇒ Hash

Updates an existing price for a product. Use this to modify the amount, currency, or billing interval of a price.

Examples:

Update a price amount

client.update_product('prod_123', { description: 'wepale' })

Parameters:

  • product_id (String) —

    the product identifier that owns the price

  • params (Hash) —

    price update parameters:

Returns:

  • (Hash) —

    updated price details including price_id

Raises:



319
320
321
 
# File 'lib/solidgate/client.rb', line 319

def update_product(product_id, params)
  patch("/api/v1/products/#{product_id}", body: params)
end

#update_product_price(product_id, price_id, params) ⇒ Hash

Updates an existing price for a product. Use this to modify the amount, currency, or billing interval of a price.

Examples:

Update a price amount

client.update_product_price('prod_123', 'price_456', amount: 2000)

Parameters:

  • product_id (String) —

    the product identifier that owns the price

  • price_id (String) —

    the price identifier to update

  • params (Hash) —

    price update parameters:

Returns:

  • (Hash) —

    updated price details including price_id

Raises:



304
305
306
 
# File 'lib/solidgate/client.rb', line 304

def update_product_price(product_id, price_id, params)
  patch("/api/v1/products/#{product_id}/prices/#{price_id}", body: params)
end

#update_subscription_pause(subscription_id, params) ⇒ Hash

Updates an existing pause schedule for a subscription.

Parameters:

  • subscription_id (String) —

    the unique subscription identifier

  • 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

Returns:

  • (Hash) —

    updated pause schedule details

Raises:



186
187
188
 
# File 'lib/solidgate/client.rb', line 186

def update_subscription_pause(subscription_id, params)
  patch("/api/v1/subscriptions/#{subscription_id}/pause-schedule", body: params)
end

#update_subscription_payment_method(params) ⇒ Hash

Updates the payment method (token) associated with an existing subscription.

Examples:

Update a subscription’s payment method

client.update_subscription_payment_method(
  subscription_id: 'sub_123',
  token: 'tok_abc123'
)

Parameters:

  • params (Hash) —

    update parameters including:

    • :subscription_id [String] the subscription to update

    • :token [String] new payment token / payment method identifier

Returns:

  • (Hash) —

    response from the API with updated subscription/payment method details

Raises:



402
403
404
 
# File 'lib/solidgate/client.rb', line 402

def update_subscription_payment_method(params)
  post("/api/v1/subscription/update-token", body: params)
end

#void_payment(payment_id) ⇒ Hash

Voids a payment that has not yet been settled. Voiding cancels the authorization and releases the hold on customer funds.

Parameters:

  • payment_id (String) —

    the unique payment identifier of an authorized (unsettled) payment

Returns:

  • (Hash) —

    void response with updated payment status

Raises:

  • (InvalidRequestError) —

    if payment cannot be voided (already settled, already voided, etc.)



101
102
103
 
# File 'lib/solidgate/client.rb', line 101

def void_payment(payment_id)
  post("/v1/charge/#{payment_id}/void")
end