solidgate-ruby-sdk 0.1.17 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b83cbd4040caae35563e9c6ee94f0c1b7527f8bc20860a5590db41cfd4f863c1
-  data.tar.gz: 2d9d52fe8fcb04ecf1e61a3349383958af3a615a01970318acbf34be9d141e44
+  metadata.gz: 2c09427f81d0f0efc89e60222716d8d66490eec414145f244df791d9c6f486dd
+  data.tar.gz: 87b350ffcec8b48c8506278fd3c0cb24892c99a04348990ffa36f2d242aabfa6
 SHA512:
-  metadata.gz: 8fbf089574bf7a8e1dd1215708bea4326d5efaca50189d1bf9962924c60f655c3a6be5b60e8fe5a0f54978a4b70c4e7afb67be1ef0526a815f97f671d331f5bc
-  data.tar.gz: f34708de83f200743353cd76276c0208cebb0750c620abe63506027ad229f57702da85e319afd798808aeb46b564a13decd50ecffed438c399c2bb8ab424a28e
+  metadata.gz: 58cbef4744fbf27bf91b43921d25284b46af5c0be8b50b05c5a938172b418f7d762d708c0f19a59b3686b62d6002a290a3e01ac532d9f8d933e46ad729f89266
+  data.tar.gz: 4244c8c9944e9c1175868ed53726781a36d26d21cd00acf75efe67cc4cbd3fce1a3cbdaf425c38c04d471d06e116b814309c0c640b5d03a5ad04772549290c3e

data/AGENTS.md

@@ -5,6 +5,9 @@
 Solidgate Ruby SDK is an unofficial Ruby library for integrating with the Solidgate payment gateway API.
 It provides a clean, object-oriented interface for payment processing, subscription management, and webhook handling.
 
+## Integration Documentation
+- Payment integration guide for humans and LLM agents: `docs/payment-integration-guide.md`
+
 ## Project Structure
 
 ### Core Components
@@ -32,9 +35,9 @@ It provides a clean, object-oriented interface for payment processing, subscript
 - Handles authentication via HMAC-SHA512 signatures
 - Provides methods for all Solidgate API endpoints:
   - Payment operations: `create_payment`, `get_payment`, `capture_payment`, `void_payment`, `refund_payment`, `settle_payment`
-  - Subscription operations: `create_subscription`, `subscription_status`, `switch_subscription_product`, `update_subscription_pause`, `create_subscription_pause`, `delete_subscription_pause`, `cancel_subscription`, `restore_subscription`
+  - Subscription operations: `create_subscription`, `subscription_status`, `switch_subscription_product`, `update_subscription_pause`, `create_subscription_pause`, `delete_subscription_pause`, `cancel_subscription`, `restore_subscription`, `update_subscription_payment_method`
   - Product operations: `create_product`, `update_product`, `create_price`, `products`, `product_prices`, `update_product_price`
-  - Utility methods: `generate_intent`, `generate_signature`, `refund`, `order_status`
+  - Utility methods: `generate_intent`, `generate_signature`, `refund`, `alt_refund`, `order_status`, `apm_order_status`, `make_card_recurring`, `make_apm_recurring`
 - Private methods for HTTP operations: `get`, `post`, `patch`, `delete`, `request`
 - Encryption: `encrypt_payload` for payment intent generation (AES-256-CBC)
 
@@ -62,7 +65,7 @@ It provides a clean, object-oriented interface for payment processing, subscript
   - `Solidgate::ValidationError` - Parameter validation (includes errors hash)
 
 #### `lib/solidgate/version.rb`
-- Version constant: `Solidgate::VERSION = "0.1.17"`
+- Version constant: `Solidgate::VERSION = "0.2.0"`
 
 ### Test Structure
 

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-06-11
+### Added
+- `decrypt_intent` public method to decrypt payment intents generated by `generate_intent`.
+- Internal `decrypt_payload` helper using AES-256-CBC with IV-prefix parsing.
+
+### Changed
+- Added client spec coverage for encrypt/decrypt round-trip and invalid payload handling.
+
+## [0.2.0] - 2026-05-05
+### Added
+- `apm_order_status` endpoint for checking alternative payment method order status.
+- Spec coverage for previously untested client methods added in this worktree.
+
+### Fixed
+- Recurring payment spec coverage bug affecting the recurring endpoint test suite.
+
+### Changed
+- Documentation updates and version bump for the `0.2.0` release.
+
 ## [0.1.17] - 2026-03-03
 ### Added
 - `update_product` endpoint (`Solidgate::Client#update_product`) to modify product attributes.
@@ -18,6 +37,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `alt_refund` endpoint to create refunds using an alternative payment method (`Solidgate::Client#alt_refund`).
 
+## [0.1.15] - 2026-02-20
+### Added
+- `make_apm_recurring` endpoint to create recurring alternative payment method charges (`Solidgate::Client#make_apm_recurring`).
+
+## [0.1.14] - 2026-02-17
+### Added
+- `make_card_recurring` endpoint to create recurring card charges (`Solidgate::Client#make_card_recurring`).
+
 ## [0.1.13] - 2026-02-13
 ### Added
 - `order_status` endpoint to check order/payment status on `pay.solidgate.com` (`Solidgate::Client#order_status`).
@@ -75,9 +102,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Thread-safe configuration
 - Comprehensive documentation and examples
 
-[Unreleased]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.1.17...HEAD
+[Unreleased]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.1.17...v0.2.0
 [0.1.17]: https://github.com/carrfane/solidgate-ruby-sdk/releases/tag/v0.1.17
 [0.1.16]: https://github.com/carrfane/solidgate-ruby-sdk/releases/tag/v0.1.16
+[0.1.15]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.1.14...v0.1.15
+[0.1.14]: https://github.com/carrfane/solidgate-ruby-sdk/compare/v0.1.13...v0.1.14
 [0.1.13]: https://github.com/carrfane/solidgate-ruby-sdk/releases/tag/v0.1.13
 [0.1.12]: https://github.com/carrfane/solidgate-ruby-sdk/releases/tag/v0.1.12
 [0.1.11]: https://github.com/carrfane/solidgate-ruby-sdk/releases/tag/v0.1.11

data/Gemfile.lock

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

data/README.md

@@ -4,6 +4,10 @@
 
 A Ruby (unofficial) SDK for integrating with the Solidgate payment gateway API.
 
+## Additional Documentation
+
+- Integration guide for payments (humans and LLM agents): `docs/payment-integration-guide.md`
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -112,8 +116,32 @@ client.refund_payment('payment_id_123', amount: 500, reason: 'Customer requested
 # Refund by order ID (pay.solidgate.com)
 client.refund(order_id: 'order_123', amount: 1000)
 
+# Refund an alternative payment method order (gate.solidgate.com)
+client.alt_refund(order_id: 'apm_order_123', amount: 750)
+
 # Check order status (pay.solidgate.com)
 client.order_status(order_id: 'order_123')
+
+# Check alternative payment method order status (gate.solidgate.com)
+client.apm_order_status(order_id: 'apm_order_123')
+
+# Charge a saved card payment method for a recurring payment
+client.make_card_recurring(
+  order_id: 'renewal_order_123',
+  amount: 1999,
+  currency: 'USD',
+  customer_email: 'customer@example.com',
+  token: 'card_tok_abc123'
+)
+
+# Charge a saved APM payment method for a recurring payment
+client.make_apm_recurring(
+  order_id: 'apm_renewal_123',
+  amount: 1499,
+  currency: 'EUR',
+  customer_email: 'customer@example.com',
+  token: 'apm_tok_xyz789'
+)
 ```
 
 ### Subscription Management

data/docs/payment-integration-guide.md

@@ -0,0 +1,266 @@
+# Solidgate Ruby SDK Integration Guide (Payments)
+
+> Target version: `solidgate-ruby-sdk` `0.2.0`  
+> Audience: engineers and LLM agents integrating Solidgate payments in Ruby apps.
+
+## 1) What this SDK provides
+
+Core entrypoints:
+
+- `Solidgate.configure` for global credentials/config
+- `Solidgate::Client` as the low-level API client (recommended for full control)
+- `Solidgate::Payment` as a higher-level payment wrapper
+- `Solidgate::Webhook` for webhook signature validation
+
+Main domains used by the SDK:
+
+- `https://subscriptions.solidgate.com` (default API base)
+- `https://pay.solidgate.com` (refund/order-status/recurring card flows)
+- `https://gate.solidgate.com` (alternative refund/APM recurring flows)
+
+---
+
+## 2) Install and initialize
+
+### Gem installation
+
+```ruby
+# Gemfile
+gem "solidgate-ruby-sdk"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+### Require and configure
+
+```ruby
+require "solidgate-ruby-sdk"
+
+Solidgate.configure do |config|
+  config.public_key = ENV.fetch("SOLIDGATE_PUBLIC_KEY")
+  config.private_key = ENV.fetch("SOLIDGATE_PRIVATE_KEY")
+  config.webhook_public_key = ENV["SOLIDGATE_WEBHOOK_PUBLIC_KEY"]
+  config.webhook_private_key = ENV["SOLIDGATE_WEBHOOK_PRIVATE_KEY"]
+
+  # Optional
+  config.sandbox = true
+  config.timeout = 30
+  config.open_timeout = 10
+  # config.api_url = "https://custom.example.com" # optional override
+end
+```
+
+Environment variables commonly used:
+
+- `SOLIDGATE_PUBLIC_KEY`
+- `SOLIDGATE_PRIVATE_KEY`
+- `SOLIDGATE_WEBHOOK_PUBLIC_KEY`
+- `SOLIDGATE_WEBHOOK_PRIVATE_KEY`
+
+---
+
+## 3) Quick start payment flow
+
+Use `Solidgate::Client` directly for integration scripts and backend services.
+
+```ruby
+client = Solidgate::Client.new
+
+# 1) Create charge
+created = client.create_payment(
+  order_id: "order_123",
+  amount: 1000,       # minor units (e.g., cents)
+  currency: "USD",
+  customer_email: "customer@example.com"
+)
+
+payment_id = created["id"] || created["payment_id"]
+
+# 2) Get payment details/status
+payment = client.get_payment(payment_id)
+
+# 3a) Capture (for auth flow)
+captured = client.capture_payment(payment_id)
+# or partial capture
+# captured = client.capture_payment(payment_id, amount: 500)
+
+# 3b) Void (if authorized and not captured)
+# voided = client.void_payment(payment_id)
+
+# 3c) Refund by payment_id
+refunded = client.refund_payment(payment_id, amount: 300, reason: "partial_refund")
+```
+
+---
+
+## 4) API methods relevant for payments
+
+### Charges (`subscriptions.solidgate.com`)
+
+- `create_payment(params)` -> `POST /v1/charge`
+- `get_payment(payment_id)` -> `GET /v1/charge/:payment_id`
+- `capture_payment(payment_id, params = {})` -> `POST /v1/charge/:payment_id/capture`
+- `void_payment(payment_id)` -> `POST /v1/charge/:payment_id/void`
+- `refund_payment(payment_id, params = {})` -> `POST /v1/charge/:payment_id/refund`
+
+### Refund and status helper routes
+
+- `refund(params)` -> `POST https://pay.solidgate.com/api/v1/refund`
+  - typically `order_id`, optional `amount`
+- `order_status(params)` -> `POST https://pay.solidgate.com/api/v1/status`
+- `apm_order_status(params)` -> `POST https://gate.solidgate.com/api/v1/status`
+
+### Alternative payment routes
+
+- `alt_refund(params)` -> `POST https://gate.solidgate.com/api/v1/refund`
+- `make_card_recurring(params)` -> `POST https://pay.solidgate.com/api/v1/recurring`
+- `make_apm_recurring(params)` -> `POST https://gate.solidgate.com/api/v1/recurring`
+
+---
+
+## 5) Frontend payment intent flow (server-side generation)
+
+For hosted/payment-form flows, generate encrypted intent and signature server-side.
+
+```ruby
+client = Solidgate::Client.new
+
+intent_json = {
+  order_id: "order_123",
+  product_id: "product_456",
+  customer_account_id: "cust_789",
+  order_description: "Premium plan",
+  type: "auth",           # or "sale"
+  settle_interval: 0,
+  retry_attempt: 3,
+  language: "en"
+}.to_json
+
+payment_intent = client.generate_intent(intent_json)
+
+payment_data = {
+  merchant: Solidgate.configuration.public_key,
+  signature: client.generate_signature(payment_intent),
+  paymentIntent: payment_intent
+}
+```
+
+Return `payment_data` to the frontend that initializes Solidgate JS.
+
+---
+
+## 6) Webhook verification
+
+Always validate signature before parsing/trusting webhook payload.
+
+```ruby
+payload = request.body.read
+signature = request.headers["Signature"]
+
+webhook = Solidgate::Webhook.new
+
+unless webhook.validate_signature(payload, signature)
+  head :unauthorized
+  return
+end
+
+event = JSON.parse(payload)
+# process event
+```
+
+---
+
+## 7) Error handling
+
+SDK error classes:
+
+- `Solidgate::Error`
+- `Solidgate::ConfigurationError`
+- `Solidgate::ValidationError`
+- `Solidgate::AuthenticationError`
+- `Solidgate::InvalidRequestError`
+- `Solidgate::APIError`
+- `Solidgate::ConnectionError`
+- `Solidgate::TimeoutError`
+- `Solidgate::RateLimitError`
+
+Recommended handling pattern:
+
+```ruby
+begin
+  client.create_payment(order_id: "o1", amount: 1000, currency: "USD")
+rescue Solidgate::ValidationError => e
+  # local validation (wrapper-level)
+rescue Solidgate::ConnectionError, Solidgate::TimeoutError => e
+  # network/retry logic
+rescue Solidgate::APIError => e
+  # inspect e.code, e.http_status, e.details
+rescue Solidgate::Error => e
+  # fallback
+end
+```
+
+---
+
+## 8) Auth/signing model used by this SDK
+
+Each request includes:
+
+- `Merchant: <public_key>`
+- `Signature: <generated_signature>`
+- `Content-Type: application/json`
+
+Signature generation in this SDK:
+
+1. Serialize body to JSON string (empty string for no body)
+2. Build message: `public_key + json_string + public_key`
+3. HMAC-SHA512 with `private_key`
+4. Base64-encode the hex digest string
+
+Use SDK-generated signatures instead of re-implementing to avoid mismatch.
+
+---
+
+## 9) LLM-agent integration playbook
+
+If an LLM agent is integrating this SDK into another project, follow this sequence:
+
+1. Add `gem "solidgate-ruby-sdk"` and install dependencies.
+2. Create initializer with `Solidgate.configure`.
+3. Add a service object wrapping `Solidgate::Client` for:
+   - create/get/capture/void/refund
+4. Add idempotency/order-id strategy in app layer.
+5. Implement webhook endpoint with signature validation first.
+6. Add retries for `ConnectionError`/`TimeoutError` and safe backoff.
+7. Add structured logs with:
+   - `order_id`, `payment_id`, `status`, error code/status
+8. Add integration tests with WebMock/VCR style stubs.
+9. Add runbooks for capture/refund/manual reconciliation.
+
+---
+
+## 10) Known quirks in current SDK (v0.2.0)
+
+- `settle_payment` currently does **not** call an API endpoint; it returns `config.api_url`.
+- `README.md` examples may not fully match actual method signatures in code.
+- `Solidgate::Payment#refund` refunds by `order_id` through `client.refund`, not by `payment_id`.
+- Sandbox and production constants currently point to the same URL in config.
+- Broad rescue in request pipeline may wrap some API exceptions into `Solidgate::Error` depending on failure path.
+
+For robust integrations, prefer `Solidgate::Client` and explicitly test your payment flows.
+
+---
+
+## 11) Minimal production checklist
+
+- [ ] Credentials loaded from secure env/secret manager
+- [ ] Webhook signature validation enabled
+- [ ] Retries/backoff for transient failures
+- [ ] Monitoring for failed captures/refunds
+- [ ] Reconciliation job using `order_status`
+- [ ] Alerting on repeated auth/429/5xx errors
+- [ ] Test mode and live mode credentials isolated

data/lib/solidgate/client.rb

@@ -289,6 +289,19 @@ module Solidgate
       encrypt_payload(params)
     end
 
+    # Decrypts an encrypted payment intent generated by {#generate_intent}.
+    #
+    # @param encrypted_payload [String] URL-safe Base64 encrypted payload
+    # @return [String] decrypted JSON payload
+    # @raise [ArgumentError] if payload cannot be decoded/decrypted
+    #
+    # @example Decrypt payment intent
+    #   payload = client.decrypt_intent(encrypted_intent)
+    #
+    def decrypt_intent(encrypted_payload)
+      decrypt_payload(encrypted_payload)
+    end
+
     # Updates an existing price for a product.
     # Use this to modify the amount, currency, or billing interval of a price.
     #
@@ -417,6 +430,20 @@ module Solidgate
       post('/api/v1/status', body: params, base_url: "https://pay.solidgate.com")
     end
 
+    # Retrieves order status from the Solidgate gate domain for APM transactions.
+    #
+    # @param params [Hash] status request parameters:
+    #   - :order_id [String] unique order identifier
+    #   - :payment_id [String] optional payment identifier
+    # @return [Hash] order status response
+    # @raise [InvalidRequestError] if params are invalid
+    #
+    # @example Get APM order status
+    #   client.apm_order_status(order_id: 'order_123')
+    def apm_order_status(params)
+      post('/api/v1/status', body: params, base_url: "https://gate.solidgate.com")
+    end
+
     def make_card_recurring(params)
       post('/api/v1/recurring', body: params, base_url: "https://pay.solidgate.com")
     end
@@ -649,5 +676,30 @@ module Solidgate
       base64_encoded = Base64.urlsafe_encode64(iv + encrypted)
       base64_encoded.gsub('+', '-').gsub('/', '_')
     end
+
+    # Decrypts a URL-safe Base64 payload encrypted with AES-256-CBC.
+    # Expects the IV to be prepended to the encrypted content.
+    #
+    # @param encrypted_payload [String] URL-safe Base64 encrypted payload
+    # @return [String] decrypted payload
+    # @raise [ArgumentError] if payload format/content is invalid
+    #
+    def decrypt_payload(encrypted_payload)
+      raw_payload = Base64.urlsafe_decode64(encrypted_payload)
+      raise ArgumentError, "Invalid encrypted payload" if raw_payload.bytesize <= IV_LENGTH
+
+      iv = raw_payload[0, IV_LENGTH]
+      encrypted_data = raw_payload[IV_LENGTH..]
+      key = config.private_key[0, KEY_LENGTH]
+
+      cipher = OpenSSL::Cipher.new('aes-256-cbc')
+      cipher.decrypt
+      cipher.key = key
+      cipher.iv = iv
+
+      cipher.update(encrypted_data) + cipher.final
+    rescue ArgumentError, OpenSSL::Cipher::CipherError
+      raise ArgumentError, "Invalid encrypted payload"
+    end
   end
 end

data/lib/solidgate/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solidgate-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.2.1
 platform: ruby
 authors:
 - Hector Carrillo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-03 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -124,6 +124,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/payment-integration-guide.md
 - examples/basic_usage.rb
 - lib/solidgate-ruby-sdk.rb
 - lib/solidgate/client.rb