paystack_sdk 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfe0137a6cc918043bc34e2be6dcb579713ef3dfec0641763234e66d51e08717
-  data.tar.gz: a331be86e1c23da3621d4b6a1d6d6c5ecfa31de7685c3776872b3ff6f3adc99d
+  metadata.gz: 5dc8af5f5a8c1305ac52bb936f3601982204a1ccab20ee7d63b2b7ad89c03b3f
+  data.tar.gz: 30c6c8e89a107566d079ca22f78f56cbb6d48701db2d97f60ddb6357a2f5c5b7
 SHA512:
-  metadata.gz: de4c777e2d89ce4cf1e30a13a352d4dab8bee5696716af0eb771964ce3aad3a10b0a6381c67b64c42dea342954c5e6d69d05b75fa43e72c288f55eeb45192a7d
-  data.tar.gz: cc889820541066ea486dfe9b4aa86d1009c692efd7c1fa52929a0791ae1f954ecabd0c66bb75b733bae0af44398e6687004867a78dc64bf7f33b33ec81eaebbc
+  metadata.gz: b5f448b8d57b73b3837542791f56418b1711dc697b7551b1240eac3b86d5337d7a125b70d006654ef41a84e16b40da38ad5bb5178faf50fee12ac72ca9d8c7f1
+  data.tar.gz: 6c3d0d9eb5c06106e1fea26e7434034a42693925cae29a7cbf9288d5655c48598a91a80cc353b238dfdd9bb73be957d4f2e511fc54004260521aa8fedaf17cf3

data/.standard.yml

@@ -1,3 +1,5 @@
 # For available configuration options, see:
 #   https://github.com/standardrb/standard
 ruby_version: 3.2.2
+fix: true
+format: progress

data/README.md

@@ -2,6 +2,30 @@
 
 The `paystack_sdk` gem provides a simple and intuitive interface for interacting with Paystack's payment gateway API. It allows developers to easily integrate Paystack's payment processing features into their Ruby applications. With support for various endpoints, this SDK simplifies tasks such as initiating transactions, verifying payments, managing customers, and more.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Client Initialization](#client-initialization)
+  - [Transactions](#transactions)
+    - [Initialize a Transaction](#initialize-a-transaction)
+    - [Verify a Transaction](#verify-a-transaction)
+    - [List Transactions](#list-transactions)
+    - [Fetch a Transaction](#fetch-a-transaction)
+    - [Get Transaction Totals](#get-transaction-totals)
+  - [Response Handling](#response-handling)
+    - [Working with Response Objects](#working-with-response-objects)
+    - [Accessing the Original Response](#accessing-the-original-response)
+    - [Error Handling](#error-handling)
+- [Advanced Usage](#advanced-usage)
+  - [Environment Variables](#environment-variables)
+  - [Direct Resource Instantiation](#direct-resource-instantiation)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,52 +46,284 @@ Or install it yourself as:
 gem install paystack_sdk
 ```
 
+## Quick Start
+
+```ruby
+require 'paystack_sdk'
+
+# Initialize the client with your secret key
+paystack = PaystackSdk::Client.new(secret_key: "sk_test_xxx")
+
+# Initialize a transaction
+params = {
+  email: "customer@email.com",
+  amount: 2300,  # Amount in the smallest currency unit (kobo for NGN)
+  currency: "NGN"
+}
+
+response = paystack.transactions.initiate(params)
+
+if response.success?
+  puts "Visit this URL to complete payment: #{response.authorization_url}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
 ## Usage
 
-Here’s a basic example of how to use the `paystack_sdk` gem:
+### Client Initialization
 
 ```ruby
-require 'paystack_sdk'
+# Initialize with your Paystack secret key
+paystack = PaystackSdk::Client.new(secret_key: "sk_test_xxx")
+
+# Or set the PAYSTACK_SECRET_KEY in your environment and do this instead
+paystack = PaystackSdk::Client.new # => This will dynamically fetch the secret key
+
+# You can access the connection directly if needed
+connection = paystack.connection
+```
 
-# Initialize the SDK with your Paystack secret key
-paystack = PaystackSdk::Client.new(api_key: "sk_test_xxx")
+### Transactions
 
-# Example: Initialize a payment
-params = {email: "customer@email.com", amount: "2300", currency: "USD"}
-response = paystack.transactions.initialize_transaction(params)
+The SDK provides comprehensive support for Paystack's Transaction API.
+
+#### Initialize a Transaction
+
+```ruby
+# Prepare transaction parameters
+params = {
+  email: "customer@example.com",
+  amount: 10000,  # Amount in the smallest currency unit (e.g., kobo, pesewas, cents)
+  currency: "GHS",
+  callback_url: "https://example.com/callback"
+}
+
+# Initialize the transaction
+response = paystack.transactions.initiate(params)
 
 if response.success?
-  puts response.authorization_url
+  puts "Transaction initialized successfully!"
+  puts "Authorization URL: #{response.authorization_url}"
+  puts "Access Code: #{response.access_code}"
+  puts "Reference: #{response.reference}"
 else
-  puts resposne.error_message
+  puts "Error: #{response.error_message}"
 end
+```
 
-# Example: Verify a payment
+#### Verify a Transaction
+
+```ruby
+# Verify using transaction reference
 response = paystack.transactions.verify(reference: "transaction_reference")
+
+if response.success?
+  transaction = response.data
+  puts "Transaction verified successfully!"
+  puts "Status: #{transaction.status}"
+  puts "Amount: #{transaction.amount}"
+  puts "Currency: #{transaction.currency}"
+  puts "Customer Email: #{transaction.customer.email}"
+
+  # Check specific transaction status
+  case transaction.status
+  when "success"
+    puts "Payment successful!"
+  when "pending"
+    puts "Payment is pending."
+  else
+    puts "Current status: #{transaction.status}"
+  end
+else
+  puts "Verification failed: #{response.error_message}"
+end
+```
+
+#### List Transactions
+
+```ruby
+# Get all transactions (default pagination: 50 per page)
+response = paystack.transactions.list
+
+# With custom pagination
+response = paystack.transactions.list(per_page: 20, page: 2)
+
+# With additional filters
+response = paystack.transactions.list(
+  per_page: 10,
+  page: 1,
+  from: "2025-01-01",
+  to: "2025-04-30",
+  status: "success"
+)
+
 if response.success?
-  puts "Payment verified successfully!"
+  puts "Total transactions: #{response.count}" # response.size is another way
+
+  response.data.each do |transaction|
+    puts "ID: #{transaction.id}"
+    puts "Reference: #{transaction.reference}"
+    puts "Amount: #{transaction.amount}"
+    puts "----------------"
+  end
+
+  # Get the first transaction
+  first_transaction = response.data.first
+  puts "First transaction reference: #{first_transaction.reference}"
+
+  # Get the last transaction
+  last_transaction = response.data.last
+  puts "Last transaction amount: #{last_transaction.amount}"
 else
-  puts "Payment verification failed: #{response.error_message}"
+  puts "Error: #{response.error_message}"
 end
 ```
 
-### The Orginal Response
+#### Fetch a Transaction
 
-There will be times you may need access to the original API response. For such cases, you
-can use the `#original_response` method on the response object.
+```ruby
+# Fetch a specific transaction by ID
+transaction_id = "12345"
+response = paystack.transactions.fetch(transaction_id)
 
-The return value is a hash with all the values from the HTTP request. This could be useful
-when you need to debug or gain access to the response its raw state.
+if response.success?
+  transaction = response.data
+  puts "Transaction details:"
+  puts "ID: #{transaction.id}"
+  puts "Reference: #{transaction.reference}"
+  puts "Amount: #{transaction.amount}"
+  puts "Status: #{transaction.status}"
+
+  # Access customer information
+  puts "Customer Email: #{transaction.customer.email}"
+  puts "Customer Name: #{transaction.customer.name}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Get Transaction Totals
 
-For example
 ```ruby
-response = transaction.list
+# Get transaction volume and success metrics
+response = paystack.transactions.totals
+
+if response.success?
+  puts "Total Transactions: #{response.data.total_transactions}"
+  puts "Total Volume: #{response.data.total_volume}"
+  puts "Pending Transfers: #{response.data.pending_transfers}"
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+### Response Handling
+
+#### Working with Response Objects
+
+All API requests return a `PaystackSdk::Response` object that provides easy access to the response data.
+
+```ruby
+response = paystack.transactions.initiate(params)
+
+# Check if the request was successful
+response.success?  # => true or false
+
+# Access response message
+response.api_message  # => "Authorization URL created"
+
+# Access data using dot notation
+response.data.authorization_url
+response.data.access_code
+
+# Access data directly from the response
+response.authorization_url  # Same as response.data.authorization_url
+
+# Access nested data
+response.data.customer.email
+
+# For arrays, use array methods
+response.data.first  # First item in an array
+response.data.last   # Last item in an array
+response.data.size   # Size of the array
+
+# Iterate through array data
+response.data.each do |item|
+  puts item.id
+end
+```
+
+#### Accessing the Original Response
+
+Sometimes you may need access to the original API response:
+
+```ruby
+response = paystack.transactions.list
+
+# Access the original response body
+original = response.original_response
+
+# Access metadata from the original response
+total_count = original.dig("meta", "total")
+current_page = original.dig("meta", "page")
+```
+
+#### Error Handling
+
+```ruby
+response = paystack.transactions.verify(reference: "invalid_reference")
+
+unless response.success?
+  puts "Error: #{response.error_message}"
+
+  # Take action based on the error
+  if response.error_message.include?("not found")
+    puts "The transaction reference was not found."
+  elsif response.error_message.include?("Invalid key")
+    puts "API authentication failed. Check your API key."
+  end
+end
+```
+
+## Advanced Usage
+
+### Environment Variables
+
+You can use environment variables to configure the SDK:
+
+```ruby
+# Set the PAYSTACK_SECRET_KEY environment variable
+ENV["PAYSTACK_SECRET_KEY"] = "sk_test_xxx"
+
+# Then initialize resources without specifying the key
+transactions = PaystackSdk::Resources::Transactions.new
+```
+
+### Direct Resource Instantiation
+
+For more advanced usage, you can instantiate resource classes directly:
+
+```ruby
+# With a secret key
+transactions = PaystackSdk::Resources::Transactions.new(secret_key: "sk_test_xxx")
+
+# With an existing Faraday connection
+connection = Faraday.new(url: "https://api.paystack.co") do |conn|
+  # Configure the connection
+end
 
-puts response.original_response # => This will return the exact response received from Paystack
+# The secret key can be omitted if set in an environment
+transactions = PaystackSdk::Resources::Transactions.new(connection, secret_key:)
 ```
 
+For more detailed documentation on specific resources, please refer to the following guides:
 
-Refer to the [documentation](https://github.com/nanafox/paystack_sdk) for more detailed usage examples and supported endpoints.
+- [Transactions](https://paystack.com/docs/api/transaction/)
+- [Customers](https://paystack.com/docs/api/customer/)
+- [Plans](https://paystack.com/docs/api/plan/)
+- [Subscriptions](https://paystack.com/docs/api/subscription/)
 
 ## Development
 

data/lib/paystack_sdk/client.rb

@@ -1,29 +1,36 @@
 # frozen_string_literal: true
 
 require_relative "resources/transactions"
+require_relative "utils/connection_utils"
 
 module PaystackSdk
   # The `Client` class serves as the main entry point for interacting with the Paystack API.
   # It initializes a connection to the Paystack API and provides access to various resources.
   class Client
-    # The base URL for the Paystack API.
-    BASE_URL = "https://api.paystack.co"
+    # Include connection utilities
+    include Utils::ConnectionUtils
+
+    # @return [Faraday::Connection] The Faraday connection object used for API requests
+    attr_reader :connection
 
     # Initializes a new `Client` instance.
     #
-    # @param api_key [String] The secret API key for authenticating with the Paystack API.
+    # @param connection [Faraday::Connection, nil] The Faraday connection object used for API requests.
+    #   If nil, a new connection will be created using the default API key.
+    # @param secret_key [String, nil] Optional API key to use for creating a new connection.
+    #   Only used if connection is nil.
     #
-    # @example
-    #   client = PaystackSdk::Client.new(api_key: "sk_test_xxx")
-    def initialize(api_key:)
-      @connection = Faraday.new(url: BASE_URL) do |conn|
-        conn.request :json
-        conn.response :json, content_type: /\bjson$/
-        conn.headers["Authorization"] = "Bearer #{api_key}"
-        conn.headers["Content-Type"] = "application/json"
-        conn.headers["User-Agent"] = "paystack_sdk/#{PaystackSdk::VERSION}"
-        conn.adapter Faraday.default_adapter
-      end
+    # @example With an existing connection
+    #   connection = Faraday.new(...)
+    #   client = PaystackSdk::Client.new(connection)
+    #
+    # @example With an API key
+    #   client = PaystackSdk::Client.new(secret_key: "sk_test_xxx")
+    #
+    # @example With default connection (requires PAYSTACK_SECRET_KEY environment variable)
+    #   client = PaystackSdk::Client.new
+    def initialize(connection = nil, secret_key: nil)
+      @connection = initialize_connection(connection, secret_key: secret_key)
     end
 
     # Provides access to the `Transactions` resource.
@@ -32,8 +39,10 @@ module PaystackSdk
     #  `Transactions` resource.
     #
     # @example
+    # ```ruby
     #   transactions = client.transactions
-    #   response = transactions.initialize_transaction(params)
+    #   response = transactions.initiate(params)
+    # ```
     def transactions
       @transactions ||= Resources::Transactions.new(@connection)
     end

data/lib/paystack_sdk/resources/base.rb

@@ -1,25 +1,44 @@
 # frozen_string_literal: true
 
 require_relative "../response"
+require_relative "../client"
+require_relative "../validations"
+require_relative "../utils/connection_utils"
 
 module PaystackSdk
   module Resources
     # The `Base` class serves as a parent class for all resource classes in the SDK.
     # It provides shared functionality, such as handling API responses.
     class Base
+      include PaystackSdk::Validations
+      include PaystackSdk::Utils::ConnectionUtils
+
       # Initializes a new `Base` instance.
       #
-      # @param connection [Faraday::Connection] The Faraday connection object used for API requests.
-      def initialize(connection)
-        @connection = connection
+      # @param connection [Faraday::Connection, nil] The Faraday connection object used for API requests.
+      #   If nil, a new connection will be created using the default API key.
+      # @param secret_key [String, nil] Optional API key to use for creating a new connection.
+      #   Only used if connection is nil.
+      #
+      # @example With an existing connection
+      #   connection = Faraday.new(...)
+      #   resource = PaystackSdk::Resources::SomeResource.new(connection)
+      #
+      # @example With an API key
+      #   resource = PaystackSdk::Resources::SomeResource.new(secret_key: "sk_test_xxx")
+      #
+      # @example With default connection (requires PAYSTACK_SECRET_KEY environment variable)
+      #   resource = PaystackSdk::Resources::SomeResource.new
+      def initialize(connection = nil, secret_key: nil)
+        @connection = initialize_connection(connection, secret_key: secret_key)
       end
 
       private
 
-      # Handles the API response, raising an error if the response is unsuccessful.
+      # Handles the API response, wrapping it in a Response object.
       #
       # @param response [Faraday::Response] The response object returned by the Faraday connection.
-      # @return [PaystackSdk::Response] The parsed response body wrapped in a `PaystackSdk::Response` object if the request was successful.
+      # @return [PaystackSdk::Response] The parsed response body wrapped in a `PaystackSdk::Response` object.
       # @raise [PaystackSdk::Error] If the response indicates an error.
       def handle_response(response)
         PaystackSdk::Response.new(response)

data/lib/paystack_sdk/resources/transactions.rb

@@ -12,20 +12,25 @@ module PaystackSdk
     #
     # Example usage:
     # ```ruby
-    #   transactions = PaystackSdk::Resources::Transactions.new(connection)
+    #   transactions = PaystackSdk::Resources::Transactions.new(secret_key:)
     #
     #   # Initialize a transaction
     #   payload = { email: "customer@email.com", amount: 10000, currency: "GHS" }
-    #   response = transactions.initialize_transaction(payload)
+    #   response = transactions.initiate(payload)
     #   if response.success?
     #     puts "Transaction initialized successfully."
-    #     puts "Authorization URL: #{response.data.authorization_url}"
+    #     puts "Authorization URL: #{response.authorization_url}"
     #   else
     #     puts "Error initializing transaction: #{response.error_message}"
     #   end
     #
     #   # Verify a transaction
     #   response = transactions.verify(reference: "transaction_reference")
+    #   if response.status == "success"
+    #     puts "The payment with reference '#{response.reference}' is verified"
+    #   else
+    #     puts "Current status: #{response.status}"
+    #   end
     #
     #   # List transactions
     #   response = transactions.list(per_page: 50, page: 1)
@@ -40,14 +45,26 @@ module PaystackSdk
       # Initializes a new transaction.
       #
       # @param payload [Hash] The payload containing transaction details (e.g., email, amount, currency).
-      # @return [Hash] The response from the Paystack API.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
       # @raise [PaystackSdk::Error] If the payload is invalid or the API request fails.
       #
       # @example
+      # ```ruby
       #   payload = { email: "customer@email.com", amount: 10000, currency: "GHS" }
-      #   response = transactions.initialize_transaction(payload)
+      #   response = transactions.initiate(payload)
+      # ```
       def initiate(payload)
-        raise PaystackSdk::Error, "Payload must be a hash" unless payload.is_a?(Hash)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            email: {type: :email, required: true},
+            amount: {type: :positive_integer, required: true},
+            currency: {type: :currency, required: false},
+            reference: {type: :reference, required: false},
+            callback_url: {required: false}
+          }
+        )
+
         response = @connection.post("/transaction/initialize", payload)
         handle_response(response)
       end
@@ -55,12 +72,14 @@ module PaystackSdk
       # Verifies a transaction using its reference.
       #
       # @param reference [String] The unique reference for the transaction.
-      # @return [Hash] The response from the Paystack API.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
-      #   response = transactions.verify("transaction_reference")
+      #   response = transactions.verify(reference: "transaction_reference")
       def verify(reference:)
+        validate_presence!(value: reference, name: "Reference")
+
         response = @connection.get("/transaction/verify/#{reference}")
         handle_response(response)
       end
@@ -69,39 +88,208 @@ module PaystackSdk
       #
       # @param per_page [Integer] Number of records per page (default: 50)
       # @param page [Integer] Page number to retrieve (default: 1)
+      # @param from [String] A timestamp from which to start listing transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @param to [String] A timestamp at which to stop listing transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @param status [String] Filter transactions by status ('failed', 'success', 'abandoned')
+      # @param customer [Integer] Specify an ID for the customer whose transactions you want to retrieve
+      # @param currency [String] Specify the transaction currency to filter
+      # @param amount [Integer] Filter by transaction amount
       # @return [PaystackSdk::Response] The response from the Paystack API containing a
       # list of transactions.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
       #   response = transactions.list(per_page: 20, page: 2)
-      def list(per_page: 50, page: 1)
-        response = @connection.get("/transaction", {perPage: per_page, page: page})
+      #   # With filters
+      #   response = transactions.list(per_page: 10, from: "2023-01-01", to: "2023-12-31", status: "success")
+      def list(per_page: 50, page: 1, **params)
+        # Create a combined parameter hash for validation
+        all_params = {per_page: per_page, page: page}.merge(params)
+
+        # Validate parameters
+        validate_fields!(
+          payload: all_params,
+          validations: {
+            per_page: {type: :positive_integer, required: false},
+            page: {type: :positive_integer, required: false},
+            from: {type: :date, required: false},
+            to: {type: :date, required: false},
+            status: {type: :inclusion, allowed_values: %w[failed success abandoned], required: false},
+            customer: {type: :positive_integer, required: false},
+            amount: {type: :positive_integer, required: false},
+            currency: {type: :currency, required: false}
+          }
+        )
+
+        # Prepare request parameters
+        request_params = {perPage: per_page, page: page}.merge(params)
+        response = @connection.get("/transaction", request_params)
         handle_response(response)
       end
 
       # Fetches details of a single transaction by its ID.
       #
-      # @param transaction_id [Integer] The ID of the transaction to fetch.
-      # @return [Hash] The response from the Paystack API containing transaction details.
+      # @param transaction_id [String, Integer] The ID of the transaction to fetch.
+      # @return [PaystackSdk::Response] The response from the Paystack API containing transaction details.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
-      #   response = transactions.fetch("transaction_id")
+      #   response = transactions.fetch("12345")
       def fetch(transaction_id)
+        validate_presence!(value: transaction_id, name: "Transaction ID")
+
         response = @connection.get("/transaction/#{transaction_id}")
         handle_response(response)
       end
 
       # Fetches the totals of all transactions.
       #
-      # @return [Hash] The response from the Paystack API containing transaction totals.
+      # @param from [String] A timestamp from which to start listing transaction totals e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @param to [String] A timestamp at which to stop listing transaction totals e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @return [PaystackSdk::Response] The response from the Paystack API containing transaction totals.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      #
+      # @example
+      #   response = transactions.totals
+      #   # With date filters
+      #   response = transactions.totals(from: "2023-01-01", to: "2023-12-31")
+      def totals(**params)
+        validate_fields!(
+          payload: params,
+          validations: {
+            from: {type: :date, required: false},
+            to: {type: :date, required: false}
+          }
+        )
+
+        response = @connection.get("/transaction/totals", params)
+        handle_response(response)
+      end
+
+      # Exports transactions as a downloadable file.
+      #
+      # @param from [String] A timestamp from which to start the export e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @param to [String] A timestamp at which to stop the export e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
+      # @param status [String] Export only transactions with a specific status ('failed', 'success', 'abandoned')
+      # @param currency [String] Specify the transaction currency to export
+      # @param amount [Integer] Filter by transaction amount
+      # @param settled [Boolean] Set to true to export only settled transactions
+      # @param payment_page [Integer] Specify a payment page ID to export only transactions conducted through the page
+      # @param customer [Integer] Specify an ID for the customer whose transactions you want to export
+      # @param settlement [Integer] Specify a settlement ID to export only transactions in the settlement
+      # @return [PaystackSdk::Response] The response from the Paystack API containing the export details.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      #
+      # @example
+      #   response = transactions.export
+      #   # With filters
+      #   response = transactions.export(from: "2023-01-01", to: "2023-12-31", status: "success", currency: "NGN")
+      def export(**params)
+        validate_fields!(
+          payload: params,
+          validations: {
+            from: {type: :date, required: false},
+            to: {type: :date, required: false},
+            status: {type: :inclusion, allowed_values: %w[failed success abandoned], required: false},
+            currency: {type: :currency, required: false},
+            amount: {type: :positive_integer, required: false},
+            payment_page: {type: :positive_integer, required: false},
+            customer: {type: :positive_integer, required: false},
+            settlement: {type: :positive_integer, required: false}
+          }
+        )
+
+        response = @connection.get("/transaction/export", params)
+        handle_response(response)
+      end
+
+      # Charges an authorization code for subsequent payments.
+      #
+      # @param payload [Hash] The payload containing charge details.
+      # @option payload [String] :authorization_code Authorization code for the transaction (required)
+      # @option payload [String] :email Customer's email address (required)
+      # @option payload [Integer] :amount Amount in kobo, pesewas, or cents to charge (required)
+      # @option payload [String] :reference Unique transaction reference. Only -, ., = and alphanumeric characters allowed
+      # @option payload [String] :currency Currency in which amount should be charged (default: NGN)
+      # @option payload [Hash] :metadata Additional transaction information
+      # @option payload [Array<Hash>] :split_code Split payment among multiple accounts
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the payload is invalid or the API request fails.
+      #
+      # @example
+      #   payload = {
+      #     authorization_code: "AUTH_72btv547",
+      #     email: "customer@email.com",
+      #     amount: 10000
+      #   }
+      #   response = transactions.charge_authorization(payload)
+      def charge_authorization(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            authorization_code: {required: true},
+            email: {type: :email, required: true},
+            amount: {type: :positive_integer, required: true},
+            reference: {type: :reference, required: false},
+            currency: {type: :currency, required: false}
+          }
+        )
+
+        response = @connection.post("/transaction/charge_authorization", payload)
+        handle_response(response)
+      end
+
+      # Performs a partial debit on a customer's account.
+      #
+      # @param payload [Hash] The payload containing partial debit details.
+      # @option payload [String] :authorization_code Authorization code for the transaction (required)
+      # @option payload [String] :currency Currency in which amount should be charged (required)
+      # @option payload [Integer] :amount Amount in kobo, pesewas, or cents to charge (required)
+      # @option payload [String] :email Customer's email address (required)
+      # @option payload [String] :reference Unique transaction reference. Only -, ., = and alphanumeric characters allowed
+      # @option payload [Hash] :metadata Additional transaction information
+      # @option payload [Array<Hash>] :split_code Split payment among multiple accounts
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the payload is invalid or the API request fails.
+      #
+      # @example
+      #   payload = {
+      #     authorization_code: "AUTH_72btv547",
+      #     currency: "NGN",
+      #     amount: 10000,
+      #     email: "customer@email.com"
+      #   }
+      #   response = transactions.partial_debit(payload)
+      def partial_debit(payload)
+        validate_fields!(
+          payload: payload,
+          validations: {
+            authorization_code: {required: true},
+            currency: {type: :currency, required: true},
+            amount: {type: :positive_integer, required: true},
+            email: {type: :email, required: true},
+            reference: {type: :reference, required: false}
+          }
+        )
+
+        response = @connection.post("/transaction/partial_debit", payload)
+        handle_response(response)
+      end
+
+      # View the timeline of a transaction
+      #
+      # @param id_or_reference [String] The ID or reference of the transaction
+      # @return [PaystackSdk::Response] The response from the Paystack API containing timeline details.
       # @raise [PaystackSdk::Error] If the API request fails.
       #
       # @example
-      #  response = transactions.totals
-      def totals
-        response = @connection.get("/transaction/totals")
+      #   response = transactions.timeline("12345")
+      #   # OR
+      #   response = transactions.timeline("ref_123456789")
+      def timeline(id_or_reference)
+        validate_presence!(value: id_or_reference, name: "Transaction ID or Reference")
+
+        response = @connection.get("/transaction/timeline/#{id_or_reference}")
         handle_response(response)
       end
     end

data/lib/paystack_sdk/utils/connection_utils.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaystackSdk
+  module Utils
+    # The `ConnectionUtils` module provides shared functionality for creating
+    # and initializing API connections. This is used by both the Client class
+    # and resource classes.
+    module ConnectionUtils
+      # The base URL for the Paystack API.
+      BASE_URL = "https://api.paystack.co"
+
+      # Initializes a connection based on the provided parameters.
+      #
+      # @param connection [Faraday::Connection, nil] An existing connection object.
+      # @param secret_key [String, nil] Optional API key to use for creating a new connection.
+      # @return [Faraday::Connection] A connection object for API requests.
+      # @raise [PaystackSdk::Error] If no connection or API key can be found.
+      def initialize_connection(connection = nil, secret_key: nil)
+        if connection
+          connection
+        elsif secret_key
+          create_connection(secret_key:)
+        else
+          # Try to get API key from environment variable
+          env_secret_key = ENV["PAYSTACK_SECRET_KEY"]
+          raise PaystackSdk::Error, "No connection or API key provided" unless env_secret_key
+
+          create_connection(secret_key: env_secret_key)
+        end
+      end
+
+      # Creates a new Faraday connection with the Paystack API.
+      #
+      # @param secret_key [String] The secret API key for authenticating with the Paystack API.
+      # @return [Faraday::Connection] A configured Faraday connection.
+      def create_connection(secret_key:)
+        Faraday.new(url: BASE_URL) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          conn.headers["Authorization"] = "Bearer #{secret_key}"
+          conn.headers["Content-Type"] = "application/json"
+          conn.headers["User-Agent"] = "paystack_sdk/#{PaystackSdk::VERSION}"
+          conn.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/paystack_sdk/validations.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module PaystackSdk
+  # The Validations module provides shared validation methods for Paystack SDK resources.
+  # It includes methods for validating common parameters like references, amounts, dates, etc.
+  #
+  # This module is intended to be included in resource classes to provide consistent
+  # parameter validation before making API calls.
+  module Validations
+    # Validates that input is a hash.
+    #
+    # @param input [Object] The input to validate
+    # @param name [String] Name of the parameter for error messages
+    # @raise [PaystackSdk::Error] If input is not a hash
+    def validate_hash!(input:, name: "Payload")
+      raise PaystackSdk::Error, "#{name} must be a hash" unless input.is_a?(Hash)
+    end
+
+    # Validates that required parameters are present in a payload.
+    #
+    # @param payload [Hash] The payload to validate
+    # @param required_params [Array<Symbol>] List of required parameter keys
+    # @param operation_name [String] Name of the operation for error messages
+    # @raise [PaystackSdk::Error] If any required parameters are missing
+    def validate_required_params!(payload:, required_params:, operation_name: "Operation")
+      missing_params = required_params.select do |param|
+        !payload.key?(param) && !payload.key?(param.to_s)
+      end
+
+      unless missing_params.empty?
+        missing_list = missing_params.map(&:to_s).join(", ")
+        raise PaystackSdk::Error, "#{operation_name} requires these missing parameter(s): #{missing_list}"
+      end
+    end
+
+    # Validates that a value is present (not nil or empty).
+    #
+    # @param value [Object] The value to validate
+    # @param name [String] Name of the parameter for error messages
+    # @raise [PaystackSdk::Error] If value is nil or empty
+    def validate_presence!(value:, name: "Parameter")
+      if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        raise PaystackSdk::Error, "#{name} cannot be empty"
+      end
+    end
+
+    # Validates that a number is a positive integer.
+    #
+    # @param value [Object] The value to validate
+    # @param name [String] Name of the parameter for error messages
+    # @param allow_nil [Boolean] Whether nil values are allowed
+    # @raise [PaystackSdk::Error] If value is not a positive integer (and not nil if allow_nil is true)
+    def validate_positive_integer!(value:, name: "Parameter", allow_nil: true)
+      if value.nil?
+        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+      elsif !value.is_a?(Integer) || value < 1
+        raise PaystackSdk::Error, "#{name} must be a positive integer"
+      end
+    end
+
+    # Validates a transaction reference format.
+    #
+    # @param reference [String] The reference to validate
+    # @param name [String] Name of the parameter for error messages
+    # @raise [PaystackSdk::Error] If reference format is invalid
+    def validate_reference_format!(reference:, name: "Reference")
+      unless reference.to_s.match?(/^[a-zA-Z0-9._=-]+$/)
+        raise PaystackSdk::Error, "#{name} can only contain alphanumeric characters and the following: -, ., ="
+      end
+    end
+
+    # Validates a date string format.
+    #
+    # @param date_str [String] The date string to validate
+    # @param name [String] Name of the parameter for error messages
+    # @param allow_nil [Boolean] Whether nil values are allowed
+    # @raise [PaystackSdk::Error] If date format is invalid
+    def validate_date_format!(date_str:, name: "Date", allow_nil: true)
+      if date_str.nil?
+        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        return
+      end
+
+      begin
+        Date.parse(date_str.to_s)
+      rescue Date::Error
+        raise PaystackSdk::Error, "Invalid #{name.downcase} format. Use format: YYYY-MM-DD or ISO8601"
+      end
+    end
+
+    # Validates that a value is within an allowed set of values.
+    #
+    # @param value [Object] The value to validate
+    # @param allowed_values [Array] List of allowed values
+    # @param name [String] Name of the parameter for error messages
+    # @param allow_nil [Boolean] Whether nil values are allowed
+    # @param case_sensitive [Boolean] Whether the comparison is case-sensitive
+    # @raise [PaystackSdk::Error] If value is not in the allowed set
+    def validate_inclusion!(value:, allowed_values:, name: "Parameter", allow_nil: true, case_sensitive: false)
+      if value.nil?
+        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        return
+      end
+
+      check_value = case_sensitive ? value.to_s : value.to_s.downcase
+      check_allowed = case_sensitive ? allowed_values : allowed_values.map(&:downcase)
+
+      unless check_allowed.include?(check_value)
+        allowed_list = allowed_values.join("', '")
+        raise PaystackSdk::Error, "#{name} must be one of: '#{allowed_list}'"
+      end
+    end
+
+    # Validates an email format.
+    #
+    # @param email [String] The email to validate
+    # @param name [String] Name of the parameter for error messages
+    # @param allow_nil [Boolean] Whether nil values are allowed
+    # @raise [PaystackSdk::Error] If email format is invalid
+    def validate_email!(email:, name: "Email", allow_nil: false)
+      if email.nil?
+        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        return
+      end
+
+      unless email.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+        raise PaystackSdk::Error, "Invalid #{name.downcase} format"
+      end
+    end
+
+    # Validates a currency code format.
+    #
+    # @param currency [String] The currency code to validate
+    # @param name [String] Name of the parameter for error messages
+    # @param allow_nil [Boolean] Whether nil values are allowed
+    # @raise [PaystackSdk::Error] If currency format is invalid
+    def validate_currency!(currency:, name: "Currency", allow_nil: true)
+      if currency.nil?
+        raise PaystackSdk::Error, "#{name} cannot be nil" unless allow_nil
+        return
+      end
+
+      unless currency.to_s.match?(/\A[A-Z]{3}\z/)
+        raise PaystackSdk::Error, "#{name} must be a 3-letter ISO code (e.g., NGN, USD, GHS)"
+      end
+    end
+
+    # Validates multiple fields at once.
+    #
+    # @param payload [Hash] The payload containing fields to validate
+    # @param validations [Hash] Mapping of field names to validation options
+    # @raise [PaystackSdk::Error] If any validation fails
+    #
+    # @example
+    #   validate_fields!(
+    #     payload: params,
+    #     validations: {
+    #       email: { type: :email, required: true },
+    #       amount: { type: :positive_integer, required: true },
+    #       currency: { type: :currency, required: false },
+    #       reference: { type: :reference, required: false }
+    #     }
+    #   )
+    def validate_fields!(payload:, validations:)
+      # First check required fields
+      required_fields = validations.select { |_, opts| opts[:required] }.keys
+      validate_required_params!(payload: payload, required_params: required_fields) unless required_fields.empty?
+
+      # Then validate each field
+      validations.each do |field, options|
+        value = payload[field] || payload[field.to_s]
+        next if value.nil? && !options[:required]
+
+        case options[:type]
+        when :email
+          validate_email!(email: value, name: field.to_s.capitalize, allow_nil: !options[:required])
+        when :positive_integer
+          validate_positive_integer!(value: value, name: field.to_s, allow_nil: !options[:required])
+        when :reference
+          validate_reference_format!(reference: value, name: field.to_s) if value
+        when :date
+          validate_date_format!(date_str: value, name: field.to_s, allow_nil: !options[:required])
+        when :currency
+          validate_currency!(currency: value, name: field.to_s, allow_nil: !options[:required])
+        when :inclusion
+          if value
+            validate_inclusion!(
+              value: value,
+              allowed_values: options[:allowed_values],
+              name: field.to_s,
+              allow_nil: !options[:required],
+              case_sensitive: options[:case_sensitive]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paystack_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackSdk
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paystack_sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Maxwell Nana Forson (theLazyProgrammer)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-13 00:00:00.000000000 Z
+date: 2025-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -119,6 +119,8 @@ files:
 - lib/paystack_sdk/resources/base.rb
 - lib/paystack_sdk/resources/transactions.rb
 - lib/paystack_sdk/response.rb
+- lib/paystack_sdk/utils/connection_utils.rb
+- lib/paystack_sdk/validations.rb
 - lib/paystack_sdk/version.rb
 - mise.toml
 - sig/paystack_sdk.rbs