paystack_sdk 0.1.0 → 0.2.0

data/lib/paystack_sdk/client.rb

@@ -5,7 +5,9 @@ require_relative "resources/customers"
 require_relative "resources/transfer_recipients"
 require_relative "resources/transfers"
 require_relative "resources/banks"
-require_relative "resources/verification"
+require_relative "resources/charges"
+require_relative "resources/miscellaneous"
+require_relative "resources/refunds"
 require_relative "utils/connection_utils"
 
 module PaystackSdk
@@ -15,6 +17,10 @@ module PaystackSdk
     # Include connection utilities
     include Utils::ConnectionUtils
 
+    # Prefix of Paystack's test and live secret keys.
+    TEST_KEY_PREFIX = "sk_test_"
+    LIVE_KEY_PREFIX = "sk_live_"
+
     # @return [Faraday::Connection] The Faraday connection object used for API requests
     attr_reader :connection
 
@@ -24,6 +30,9 @@ module PaystackSdk
     #   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.
+    # @param sandbox_only [Boolean] Refuse to build a client unless the key is a test key
+    #   (`sk_test_...`). Set this in staging and CI so they can never charge real money.
+    # @raise [ArgumentError] If `sandbox_only` is true and the key is not a test key.
     #
     # @example With an existing connection
     #   connection = Faraday.new(...)
@@ -34,8 +43,25 @@ module PaystackSdk
     #
     # @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)
+    # @example Refuse live keys (staging, CI)
+    #   client = PaystackSdk::Client.new(secret_key: ENV["PAYSTACK_SECRET_KEY"], sandbox_only: true)
+    def initialize(connection = nil, secret_key: nil, sandbox_only: false, **options)
+      if sandbox_only
+        key = connection ? key_from(connection) : (secret_key || ENV["PAYSTACK_SECRET_KEY"])
+        unless key.to_s.start_with?(TEST_KEY_PREFIX)
+          raise ArgumentError, "sandbox_only is set, but the secret key is not a test key (#{TEST_KEY_PREFIX}...)"
+        end
+      end
+
+      @connection = initialize_connection(connection, secret_key: secret_key, **options)
+    end
+
+    # Whether this client is using a live key (`sk_live_...`), so requests move real money.
+    # A test key, or a key in any other form, is not live.
+    #
+    # @return [Boolean]
+    def live?
+      key_from(@connection).to_s.start_with?(LIVE_KEY_PREFIX)
     end
 
     # Provides access to the `Transactions` resource.
@@ -46,7 +72,7 @@ module PaystackSdk
     # @example
     # ```ruby
     #   transactions = client.transactions
-    #   response = transactions.initiate(params)
+    #   response = transactions.initiate(email: "ama@example.com", amount: 10000)
     # ```
     def transactions
       @transactions ||= Resources::Transactions.new(@connection)
@@ -74,7 +100,7 @@ module PaystackSdk
     # @example
     # ```ruby
     #   recipients = client.transfer_recipients
-    #   response = recipients.create(params)
+    #   response = recipients.create(type: "nuban", name: "Ama Mensah", account_number: "0123456789", bank_code: "058")
     # ```
     def transfer_recipients
       @transfer_recipients ||= Resources::TransferRecipients.new(@connection)
@@ -88,7 +114,7 @@ module PaystackSdk
     # @example
     # ```ruby
     #   transfers = client.transfers
-    #   response = transfers.create(params)
+    #   response = transfers.create(source: "balance", amount: 100_000, recipient: "RCP_xxx", reference: "payout-2025-0001-ama")
     # ```
     def transfers
       @transfers ||= Resources::Transfers.new(@connection)
@@ -102,24 +128,56 @@ module PaystackSdk
     # @example
     # ```ruby
     #   banks = client.banks
-    #   response = banks.list
+    #   response = banks.list(country: "nigeria")
     # ```
     def banks
       @banks ||= Resources::Banks.new(@connection)
     end
 
-    # Provides access to the `Verification` resource.
+    # Provides access to the `Charges` resource.
+    #
+    # @return [PaystackSdk::Resources::Charges] An instance of the
+    #  `Charges` resource.
+    #
+    # @example
+    # ```ruby
+    #   charges = client.charges
+    #   response = charges.mobile_money(
+    #     email: "ama@example.com",
+    #     amount: 10000,
+    #     mobile_money: {phone: "0551234987", provider: "mtn"}
+    #   )
+    # ```
+    def charges
+      @charges ||= Resources::Charges.new(@connection)
+    end
+
+    # Provides access to the `Miscellaneous` resource.
     #
-    # @return [PaystackSdk::Resources::Verification] An instance of the
-    #  `Verification` resource.
+    # @return [PaystackSdk::Resources::Miscellaneous] An instance of the
+    #  `Miscellaneous` resource.
     #
     # @example
     # ```ruby
-    #   verification = client.verification
-    #   response = verification.resolve_account(account_number: ..., bank_code: ...)
+    #   response = client.miscellaneous.resolve_card_bin(bin: "539983")
     # ```
-    def verification
-      @verification ||= Resources::Verification.new(@connection)
+    def miscellaneous
+      @miscellaneous ||= Resources::Miscellaneous.new(@connection)
+    end
+
+    # Provides access to the `Refunds` resource.
+    #
+    # @return [PaystackSdk::Resources::Refunds] An instance of the
+    #  `Refunds` resource.
+    def refunds
+      @refunds ||= Resources::Refunds.new(@connection)
+    end
+
+    private
+
+    # The secret key a connection sends, read from its Authorization header.
+    def key_from(connection)
+      connection.headers["Authorization"].to_s.delete_prefix("Bearer ")
     end
   end
 end

data/lib/paystack_sdk/middleware/transport_errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PaystackSdk
+  module Middleware
+    # Translates low-level Faraday transport failures into SDK errors so that
+    # `rescue PaystackSdk::Error` catches them. It sits outside the retry
+    # middleware, so it only sees failures that survived all retries.
+    class TransportErrors < Faraday::Middleware
+      def call(env)
+        @app.call(env)
+      rescue Faraday::TimeoutError => e
+        raise PaystackSdk::TimeoutError, "Request to Paystack timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+        # Connect-phase timeouts (Net::OpenTimeout) surface as ConnectionFailed.
+        if e.cause.is_a?(::Timeout::Error)
+          raise PaystackSdk::TimeoutError, "Connecting to Paystack timed out: #{e.message}"
+        end
+
+        raise PaystackSdk::ConnectionError, "Could not connect to Paystack: #{e.message}"
+      end
+    end
+  end
+end

data/lib/paystack_sdk/request_helpers.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "date"
+require "erb"
+require "json"
+
+module PaystackSdk
+  # Small helpers resource classes use to turn idiomatic Ruby arguments into exactly what Paystack
+  # documents on the wire. They are private to the classes that include them.
+  #
+  # Ruby code uses snake_case keywords (`per_page:`, `terminal_id:`); the request carries Paystack's
+  # names (`perPage`, `terminalid`). Each method names its mapping in one place, with {#to_wire}.
+  module RequestHelpers
+    private
+
+    # Escapes a value for use as one segment of a URL path, so a reference or code containing `/`,
+    # `?`, `#` or a space cannot change which endpoint is called.
+    #
+    # `.` and `..` are refused: the URL builder resolves them as relative path steps, so
+    # `/customer/..` would call `/`. No Paystack identifier is ever one of them. An empty value is
+    # refused too, since it would collapse the segment out of the path.
+    #
+    # @param segment [#to_s]
+    # @param name [String] parameter name, for the error message
+    # @return [String]
+    # @raise [PaystackSdk::InvalidValueError] If the segment is empty, `.` or `..`
+    def escape_path(segment, name: "path segment")
+      value = segment.to_s
+      raise InvalidValueError.new(name, "must not be empty") if value.empty?
+      raise InvalidValueError.new(name, %(must not be "#{value}")) if %w[. ..].include?(value)
+
+      ERB::Util.url_encode(value)
+    end
+
+    # Drops nil values, keeping `false`, `0` and empty strings, which are real values.
+    #
+    # @param params [Hash]
+    # @return [Hash]
+    def compact_params(params)
+      params.compact
+    end
+
+    # Renames Ruby-style keys to the parameter names Paystack documents, drops nils and returns
+    # string keys. Keys without a mapping are sent as given.
+    #
+    # @param params [Hash] e.g. `{per_page: 20, status: "success"}`
+    # @param mapping [Hash{Symbol => String}] e.g. `{per_page: "perPage"}`
+    # @return [Hash{String => Object}]
+    def to_wire(params, mapping)
+      compact_params(params).each_with_object({}) do |(key, value), wire|
+        wire[(mapping[key] || key).to_s] = value
+      end
+    end
+
+    # Formats a Date, Time or ISO 8601 String for a Paystack date-time parameter.
+    #
+    # @param value [Date, Time, String, nil]
+    # @param name [String] parameter name, for the error message
+    # @return [String, nil]
+    # @raise [PaystackSdk::InvalidFormatError] If a String is not ISO 8601
+    def format_datetime(value, name: "date")
+      case value
+      when nil then nil
+      when Time, DateTime then value.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      when Date then value.iso8601
+      when String
+        iso8601?(value) ? value : raise(InvalidFormatError.new(name, "ISO 8601 date or date-time (e.g. 2026-01-31 or 2026-01-31T09:00:00Z)"))
+      else raise InvalidFormatError.new(name, "Date, Time or ISO 8601 String")
+      end
+    end
+
+    # Formats a Date, Time or YYYY-MM-DD String for a Paystack date parameter.
+    #
+    # @param value [Date, Time, String, nil]
+    # @param name [String] parameter name, for the error message
+    # @return [String, nil]
+    # @raise [PaystackSdk::InvalidFormatError] If a String is not a real YYYY-MM-DD date
+    def format_date(value, name: "date")
+      case value
+      when nil then nil
+      when Time, Date then value.strftime("%Y-%m-%d")
+      when String
+        valid = value.match?(/\A\d{4}-\d{2}-\d{2}\z/) && begin
+          Date.strptime(value, "%Y-%m-%d")
+        rescue
+          nil
+        end
+        valid ? value : raise(InvalidFormatError.new(name, "YYYY-MM-DD"))
+      else raise InvalidFormatError.new(name, "Date, Time or YYYY-MM-DD String")
+      end
+    end
+
+    # For the few fields Paystack documents as "stringified JSON" (for example customer metadata):
+    # accepts a Hash or Array and sends the JSON string. Strings pass through unchanged.
+    #
+    # @param value [Hash, Array, String, nil]
+    # @return [String, nil]
+    def stringify_json(value)
+      case value
+      when nil, String then value
+      else JSON.generate(value)
+      end
+    end
+
+    def iso8601?(value)
+      Time.iso8601(value)
+      true
+    rescue ArgumentError
+      begin
+        Date.iso8601(value)
+        true
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/banks.rb

@@ -1,20 +1,170 @@
-require_relative "../validations"
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
+# Do not edit by hand: regenerate it with `bin/paystack-scaffold Bank`. Hand-written extras go in lib/paystack_sdk/resources/extensions/banks.rb.
+# scaffold-digest: 530fc74fc57bba755180a37c395576bd9fc13c76500eae0fce6da7b1a6740ff9
+
+require_relative "base"
 
 module PaystackSdk
   module Resources
-    class Banks < Base
-      # List banks
+    # Bank operations.
+    class Banks < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {per_page: "perPage", next_cursor: "next"}.freeze
+
+      # List Banks.
+      #
+      # List banks supported on Paystack
+      #
+      # @param country [String] The country from which to obtain the list of supported banks One of: ghana, kenya, nigeria, south africa.
+      # @param currency [String] The currency of the banks to list. One of: GHS, KES, NGN, ZAR, USD.
+      # @param use_cursor [Boolean] A flag to indicate if cursor based pagination should be used
+      # @param per_page [Integer] The number of records to fetch per request
+      # @param page [Integer] The offset to retrieve data from
+      # @param next_cursor [String] An alphanumeric value returned for every cursor based retrieval, used to retrieve the next set of data
+      # @param previous [String] An alphanumeric value returned for every cursor based retrieval, used to retrieve the previous set of data
+      # @param pay_with_bank_transfer [Boolean] A flag to filter for available banks a customer can make a transfer to complete a payment
+      # @param pay_with_bank [Boolean] A flag to filter for banks a customer can pay directly from
+      # @param enabled_for_verification [Boolean] A flag to filter the banks that are supported for account verification in South Africa.
+      # @param gateway [String] The type of gateway for a Nigerian bank One of: emandate, digitalbankmandate.
+      # @param type [String] Type of financial channel One of: ghipss, mobile_money, nuban, kepss, basa.
+      # @param include_nip_sort_code [Boolean] A flag that returns Nigerian banks with their NIP institution code.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/miscellaneous/#bank
-      def list(query = {})
-        if query.key?(:currency)
-          validate_allowed_values!(
-            value: query[:currency],
-            name: "currency",
-            allowed_values: %w[NGN GHS ZAR KES USD]
-          )
-        end
-
-        handle_response(@connection.get("/bank", query))
+      def list(
+        country: nil,
+        currency: nil,
+        use_cursor: nil,
+        per_page: nil,
+        page: nil,
+        next_cursor: nil,
+        previous: nil,
+        pay_with_bank_transfer: nil,
+        pay_with_bank: nil,
+        enabled_for_verification: nil,
+        gateway: nil,
+        type: nil,
+        include_nip_sort_code: nil
+      )
+        validate_allowed_values!(
+          value: country,
+          allowed_values: ["ghana", "kenya", "nigeria", "south africa"],
+          name: "country"
+        )
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[GHS KES NGN ZAR USD],
+          name: "currency"
+        )
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+        validate_allowed_values!(
+          value: gateway,
+          allowed_values: %w[emandate digitalbankmandate],
+          name: "gateway"
+        )
+        validate_allowed_values!(
+          value: type,
+          allowed_values: %w[ghipss mobile_money nuban kepss basa],
+          name: "type"
+        )
+
+        wire_query = to_wire(
+          {
+            country:,
+            currency:,
+            use_cursor:,
+            per_page:,
+            page:,
+            next_cursor:,
+            previous:,
+            pay_with_bank_transfer:,
+            pay_with_bank:,
+            enabled_for_verification:,
+            gateway:,
+            type:,
+            include_nip_sort_code:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/bank", wire_query))
+      end
+
+      # Resolve Account Number.
+      #
+      # Resolve an account number to confirm the name associated with it
+      #
+      # @param account_number [String] The account number of interest
+      # @param bank_code [String] The bank code associated with the account number
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/verification/#resolve-account
+      def resolve_account_number(account_number:, bank_code:)
+        validate_presence!(value: account_number, name: "account_number")
+        validate_presence!(value: bank_code, name: "bank_code")
+
+        wire_query = to_wire({account_number:, bank_code:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/bank/resolve", wire_query))
+      end
+
+      # Validate Bank Account.
+      #
+      # Confirm the authenticity of a customer's account number before sending money
+      #
+      # @param account_name [String] Customer's first and last name registered with their bank
+      # @param account_number [String] Customer's account number
+      # @param account_type [String] The type of the customer's account number One of: personal, business.
+      # @param bank_code [String] The bank code of the customer’s bank.
+      # @param country_code [String] The two digit ISO code of the customer’s bank
+      # @param document_type [String] Customer’s mode of identity One of: identityNumber, passportNumber, businessRegistrationNumber.
+      # @param document_number [String] Customer’s mode of identity number
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/verification/#validate-account
+      def validate_account(
+        account_name:,
+        account_number:,
+        account_type:,
+        bank_code:,
+        country_code:,
+        document_type:,
+        document_number: nil
+      )
+        validate_presence!(value: account_name, name: "account_name")
+        validate_presence!(value: account_number, name: "account_number")
+        validate_presence!(value: account_type, name: "account_type")
+        validate_allowed_values!(
+          value: account_type,
+          allowed_values: %w[personal business],
+          name: "account_type"
+        )
+        validate_presence!(value: bank_code, name: "bank_code")
+        validate_presence!(value: country_code, name: "country_code")
+        validate_presence!(value: document_type, name: "document_type")
+        validate_allowed_values!(
+          value: document_type,
+          allowed_values: %w[identityNumber passportNumber businessRegistrationNumber],
+          name: "document_type"
+        )
+
+        wire_body = to_wire(
+          {
+            account_name:,
+            account_number:,
+            account_type:,
+            bank_code:,
+            country_code:,
+            document_type:,
+            document_number:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/bank/validate", wire_body))
       end
     end
   end

data/lib/paystack_sdk/resources/base.rb

@@ -3,6 +3,7 @@
 require_relative "../response"
 require_relative "../client"
 require_relative "../validations"
+require_relative "../request_helpers"
 require_relative "../utils/connection_utils"
 
 module PaystackSdk
@@ -11,6 +12,7 @@ module PaystackSdk
     # It provides shared functionality, such as handling API responses.
     class Base
       include PaystackSdk::Validations
+      include PaystackSdk::RequestHelpers
       include PaystackSdk::Utils::ConnectionUtils
 
       # Initializes a new `Base` instance.
@@ -29,8 +31,8 @@ module PaystackSdk
       #
       # @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)
+      def initialize(connection = nil, secret_key: nil, **options)
+        @connection = initialize_connection(connection, secret_key: secret_key, **options)
       end
 
       private