paystack-gateway 0.1.0

data/lib/paystack_gateway/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+
+# = PaystackGateway
+module PaystackGateway
+  # Encapsulates the configuration options for PaystackGateway including the
+  # secret key, logger, logging_options, and log filter.
+  class Configuration
+    attr_accessor :secret_key, :logger, :logging_options, :log_filter
+
+    def initialize
+      @logger = Logger.new($stdout)
+      @log_filter = lambda(&:dup)
+    end
+  end
+
+  class << self
+    attr_writer :config
+
+    delegate :secret_key, :logger, :logging_options, :log_filter, to: :config
+
+    def config = @config ||= Configuration.new
+    def configure = yield(config)
+  end
+end

data/lib/paystack_gateway/current.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'active_support/isolated_execution_state'
+require 'active_support/code_generator'
+require 'active_support/current_attributes'
+
+module PaystackGateway
+  # Global singleton providing thread isolated attributes, used and reset around
+  # each api method call.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :api_module, :api_method_name
+
+    def response_class
+      class_name = "#{api_method_name}_response".camelize.to_sym
+      api_module.const_defined?(class_name) ? api_module.const_get(class_name) : PaystackGateway::Response
+    end
+
+    def error_class
+      class_name = "#{api_method_name}_error".camelize
+      api_module.const_defined?(class_name) ? api_module.const_get(class_name) : PaystackGateway::ApiError
+    end
+
+    def qualified_api_method_name = "#{api_module.name}##{api_method_name}"
+  end
+end

data/lib/paystack_gateway/customers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage customers https://paystack.com/docs/api/customer/
+  module Customers
+    include PaystackGateway::RequestModule
+
+    # Common helpers for response from customer endpoints
+    module CustomerResponse
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :id, :customer_code, to: :data
+      end
+    end
+
+    class CreateCustomerResponse < PaystackGateway::Response
+      include CustomerResponse
+    end
+
+    api_method def self.create_customer(email:, first_name:, last_name:)
+      use_connection do |connection|
+        connection.post('/customer', { email:, first_name:, last_name: })
+      end
+    end
+
+    # Response from GET /customer/:email_or_id
+    class FetchCustomerResponse < PaystackGateway::Response
+      include CustomerResponse
+
+      delegate :subscriptions, :authorizations, to: :data
+
+      def active_subscriptions = subscriptions.select { _1.status == 'active' }
+      def active_subscription_codes = active_subscriptions.map(&:subscription_code)
+      def reusable_authorizations = authorizations.select(&:reusable)
+    end
+
+    api_method def self.fetch_customer(email:)
+      use_connection do |connection|
+        connection.get("/customer/#{email}")
+      end
+    end
+  end
+end

data/lib/paystack_gateway/dedicated_virtual_accounts.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # The Dedicated Virtual Account API enables Nigerian merchants to manage unique
+  # payment accounts of their customers.
+  # https://paystack.com/docs/api/dedicated-virtual-account/
+  module DedicatedVirtualAccounts
+    include PaystackGateway::RequestModule
+
+    # Response from POST /dedicated_account endpoint.
+    class CreateDedicatedVirtualAccountResponse < PaystackGateway::Response; end
+
+    api_method def self.create_dedicated_virtual_account(customer_id_or_code:, subaccount_code:, preferred_bank:)
+      use_connection do |connection|
+        connection.post(
+          '/dedicated_account',
+          {
+            customer: customer_id_or_code,
+            preferred_bank:,
+            subaccount: subaccount_code,
+            phone: '+2348011111111', # phone number is required by paystack for some reason, use fake phone number
+          },
+        )
+      end
+    end
+
+    # Response from POST /dedicated_account/assign endpoint.
+    class AssignDedicatedVirtualAccountResponse < PaystackGateway::Response; end
+
+    api_method def self.assign_dedicated_virtual_account(
+      email:, first_name:, last_name:, subaccount_code:, preferred_bank:
+    )
+      use_connection do |connection|
+        connection.post(
+          '/dedicated_account/assign',
+          {
+            email:,
+            first_name:,
+            last_name:,
+            preferred_bank:,
+            country: :NG,
+            subaccount: subaccount_code,
+          },
+        )
+      end
+    end
+
+    # Response from POST /dedicated_account/split endpoint
+    class SplitDedicatedAccountTransactionResponse < PaystackGateway::Response; end
+
+    api_method def self.split_dedicated_account_transaction(customer_id_or_code:, subaccount_code:)
+      use_connection do |connection|
+        connection.post('/dedicated_account/split', { customer: customer_id_or_code, subaccount: subaccount_code })
+      end
+    end
+
+    # Response from GET /dedicated_account endpoint
+    class RequeryDedicatedAccountResponse < PaystackGateway::Response; end
+
+    api_method def self.requery_dedicated_account(account_number:, bank:)
+      use_connection do |connection|
+        connection.get('/dedicated_account', { account_number:, provider_slug: bank })
+      end
+    end
+  end
+end

data/lib/paystack_gateway/miscellaneous.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Supporting APIs that can be used to provide more details to other APIs
+  # https://paystack.com/docs/api/#miscellaneous
+  module Miscellaneous
+    include PaystackGateway::RequestModule
+
+    # Response from GET /bank endpoint.
+    class ListBanksResponse < PaystackGateway::Response
+      def bank_names = data.map(&:name)
+      def bank_slugs = data.map(&:slug)
+
+      def bank_details(*attributes) = data.map { _1.slice(*attributes) }
+
+      def by_bank_names = data.index_by(&:name)
+      def by_bank_codes = data.index_by(&:code)
+    end
+
+    # https://paystack.com/docs/api/miscellaneous/#bank
+    api_method def self.list_banks(use_cache: true, pay_with_bank_transfer: false)
+      use_connection(cache_options: use_cache ? {} : nil) do |connection|
+        connection.get('/bank', pay_with_bank_transfer ? { pay_with_bank_transfer: } : {})
+      end
+    end
+  end
+end

data/lib/paystack_gateway/plans.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage installment payment options
+  # https://paystack.com/docs/api/plan/#create
+  module Plans
+    include PaystackGateway::RequestModule
+
+    # Response from POST /plan endpoint.
+    class CreatePlanResponse < PaystackGateway::Response
+      delegate :id, to: :data, prefix: :plan
+      delegate :id, :plan_code, to: :data
+    end
+
+    api_method def self.create_plan(name:, amount:, interval:)
+      use_connection do |connection|
+        connection.post(
+          '/plan',
+          {
+            name:,
+            interval:,
+            amount: amount * 100,
+            send_invoices: false,
+            send_sms: false,
+          },
+        )
+      end
+    end
+
+    # Response from GET /plan endpoint.
+    class ListPlansResponse < PaystackGateway::Response
+      def active_plans = data.select { |plan| !plan.is_deleted && !plan.is_archived }
+
+      def find_active_plan_by_name(name)
+        active_plans.sort_by { -Time.parse(_1.createdAt).to_i }.find { _1.name == name }
+      end
+    end
+
+    api_method def self.list_plans
+      use_connection do |connection|
+        connection.get('/plan')
+      end
+    end
+
+    # Response from GET /plan/:code endpoint.
+    class FetchPlanResponse < PaystackGateway::Response
+      delegate :subscriptions, to: :data
+
+      def active_subscriptions = subscriptions.select { _1.status.to_sym == :active }
+
+      def active_subscription_codes(email: nil)
+        subscriptions =
+          if email
+            active_subscriptions.select { _1.customer.email.casecmp?(email) }
+          else
+            active_subscriptions
+          end
+        subscriptions.map(&:subscription_code)
+      end
+    end
+
+    api_method def self.fetch_plan(code:)
+      use_connection do |connection|
+        connection.get("/plan/#{code}")
+      end
+    end
+
+    class UpdatePlanResponse < PaystackGateway::Response; end
+
+    api_method def self.update_plan(code:, amount:, interval:)
+      use_connection do |connection|
+        connection.put(
+          "/plan/#{code}",
+          {
+            amount: amount * 100,
+            interval:,
+          },
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/refunds.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage transaction refunds.
+  # https://paystack.com/docs/api/refund
+  module Refunds
+    include PaystackGateway::RequestModule
+
+    # Common helpers for responses from refunds endpoints
+    module TransactionRefundResponse
+      def refund_success? = transaction_status == :processed
+      def refund_failed? = transaction_status == :failed
+      def refund_pending? = transaction_status.in?(%i[pending processing])
+    end
+
+    # Response from POST /refund endpoint.
+    class CreateResponse < PaystackGateway::Response
+      include TransactionResponse
+      include TransactionRefundResponse
+    end
+
+    api_method def self.create(transaction_reference_or_id:)
+      use_connection do |connection|
+        connection.post('/refund', { transaction: transaction_reference_or_id })
+      end
+    end
+
+    # Response from GET /refund endpoint.
+    class ListRefundsResponse < PaystackGateway::Response
+      def pending_or_successful
+        filtered = data.select { _1.status&.to_sym.in?(%i[processed pending processing]) }
+
+        ListRefundsResponse.new({ **self, data: filtered })
+      end
+
+      def with_amount(amount)
+        filtered = data.select { _1.amount == amount * 100 }
+
+        ListRefundsResponse.new({ **self, data: filtered })
+      end
+    end
+
+    api_method def self.list_refunds(transaction_id:)
+      use_connection do |connection|
+        connection.get('/refund', { transaction: transaction_id })
+      end
+    end
+
+    # Response from GET /refund/:id endpoint.
+    class FetchRefundResponse < PaystackGateway::Response
+      include TransactionResponse
+      include TransactionRefundResponse
+    end
+
+    api_method def self.fetch_refund(refund_id:)
+      use_connection do |connection|
+        connection.get("/refund/#{refund_id}")
+      end
+    end
+  end
+end

data/lib/paystack_gateway/request_module.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/response/caching'
+require 'faraday/response/mashify'
+require 'active_support/cache'
+require 'active_support/notifications'
+require 'active_support/concern'
+require 'active_support/core_ext/string/inflections' # for #camelize
+require 'active_support/core_ext/numeric/time' # for #days
+
+module PaystackGateway
+  # This module provides methods for making API requests to the Paystack
+  # payment gateway, including handling responses and errors.
+  module RequestModule
+    extend ActiveSupport::Concern
+
+    BASE_URL = 'https://api.paystack.co'
+
+    # ClassMethods
+    module ClassMethods
+      def api_methods = (@api_method_names || Set.new).to_a
+
+      private
+
+      def use_connection(response_class = Current.response_class, cache_options: nil)
+        connection = Faraday.new(BASE_URL) do |conn|
+          conn.request :json
+          conn.request :authorization, 'Bearer', PaystackGateway.secret_key
+
+          conn.response :logger, PaystackGateway.logger, { headers: false, **(PaystackGateway.logging_options || {}) }
+          conn.response :mashify, mash_class: response_class
+
+          conn.response :raise_error
+          conn.response :json
+          conn.response :caching, cache_store(**cache_options) if cache_options
+        end
+
+        if block_given?
+          response = yield connection
+          response.body
+        else
+          connection
+        end
+      end
+
+      def cache_store(expires_in: 7.days.to_i, cache_key: nil)
+        cache_dir = File.join(ENV['TMPDIR'] || '/tmp', 'cache')
+        namespace = cache_key ? "#{name}_#{cache_key}" : name
+
+        ActiveSupport::Cache::FileStore.new cache_dir, namespace:, expires_in: expires_in.to_i
+      end
+
+      def api_method(method_name)
+        @api_method_names ||= Set.new
+        @api_method_names << method_name
+
+        decorate_api_methods(method_name)
+      end
+
+      def decorate_api_methods(*method_names)
+        singleton_class.class_exec do
+          prepend(Module.new do
+            method_names.flatten.each do |method_name|
+              define_method(method_name) do |*args, **kwargs, &block|
+                Current.with(api_module: self, api_method_name: method_name) do
+                  super(*args, **kwargs, &block)
+                rescue Faraday::Error => e
+                  handle_error(e)
+                end
+              end
+            end
+          end)
+        end
+      end
+
+      def handle_error(error)
+        PaystackGateway.logger.error "#{Current.qualified_api_method_name}: #{error.message}"
+        PaystackGateway.logger.error JSON.pretty_generate(filtered_response(error.response) || {}) if error.response
+
+        raise Current.error_class.new(
+          "Paystack error: #{error.message}, status: #{error.response_status}, response: #{error.response_body}",
+          original_error: error,
+        )
+      end
+
+      def filtered_response(response)
+        return unless response
+
+        {
+          request_method: response.dig(:request, :method),
+          request_url: response.dig(:request, :url),
+          request_headers: PaystackGateway.log_filter.call(response.dig(:request, :headers)),
+          request_body: PaystackGateway.log_filter.call(JSON.parse(response.dig(:request, :body) || '{}')),
+
+          response_status: response[:status],
+          response_headers: PaystackGateway.log_filter.call(response[:headers]),
+          response_body: PaystackGateway.log_filter.call(response[:body]),
+        }
+      end
+    end
+  end
+end

data/lib/paystack_gateway/response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'hashie/dash'
+require 'hashie/mash'
+require 'hashie/extensions/coercion'
+
+module PaystackGateway
+  # Wrapper for responses from Paystack.
+  class Response < Hashie::Dash
+    include Hashie::Extensions::Coercion
+
+    property :status
+    property :message
+    property :data
+    property :meta
+
+    coerce_key :data, ->(v) { coerce_data(v) }
+
+    def self.coerce_data(value)
+      case value
+      when Array
+        value.map { coerce_data(_1) }
+      when Hash
+        Hashie::Mash.new(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/paystack_gateway/subaccounts.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage subaccounts https://paystack.com/docs/api/subaccount/
+  module Subaccounts
+    include PaystackGateway::RequestModule
+
+    # Response from POST /subaccount
+    class CreateSubaccountResponse < PaystackGateway::Response
+      delegate :subaccount_code, to: :data
+    end
+
+    api_method def self.create_subaccount(business_name:, settlement_bank:, account_number:, percentage_charge:)
+      use_connection do |connection|
+        connection.post(
+          '/subaccount',
+          { business_name:, settlement_bank:, account_number:, percentage_charge: }.compact,
+        )
+      end
+    end
+
+    # Response from PUT /subaccount/:id_or_code
+    class UpdateSubaccountResponse < CreateSubaccountResponse; end
+
+    api_method def self.update_subaccount(
+      subaccount_code,
+      business_name: nil, settlement_bank: nil, account_number: nil, percentage_charge: nil
+    )
+      use_connection do |connection|
+        connection.put(
+          "/subaccount/#{subaccount_code}",
+          { business_name:, settlement_bank:, account_number:, percentage_charge: }.compact,
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/transaction_response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Common helpers for responses from transaction endpoints
+  module TransactionResponse
+    extend ActiveSupport::Concern
+
+    included do
+      delegate :id, :amount, :subaccount, :fees_split, to: :data
+
+      attr_writer :completed_at
+    end
+
+    def transaction_success? = transaction_status.in?(%i[success reversed reversal_pending])
+    def transaction_abandoned? = transaction_status == :abandoned
+    def transaction_failed? = transaction_status == :failed
+    def transaction_pending? = transaction_status.in?(%i[pending ongoing])
+
+    def transaction_status = data.status.to_sym
+    def transaction_amount = amount / BigDecimal('100')
+    def transaction_completed_at = data[:updatedAt] || @completed_at
+
+    def subaccount_amount
+      return if !subaccount || !fees_split
+
+      fees_split.subaccount / BigDecimal('100')
+    end
+
+    def failure_reason
+      return if !transaction_failed? && !transaction_abandoned?
+
+      data.gateway_response || transaction_status || message
+    end
+  end
+end

data/lib/paystack_gateway/transactions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage payments https://paystack.com/docs/api/#transaction
+  module Transactions
+    include PaystackGateway::RequestModule
+
+    # Response from POST /transaction/initialize endpoint.
+    class InitializeTransactionResponse < PaystackGateway::Response
+      delegate :authorization_url, to: :data
+
+      alias payment_url authorization_url
+    end
+
+    # Raised when an error occurs while calling POST /transaction/initialize
+    class InitializeTransactionError < ApiError
+      def cancellable? = super || network_error?
+    end
+
+    # Response looks like this.
+    # {
+    #   "status": true,
+    #   "message": "Authorization URL created",
+    #   "data": {
+    #     "authorization_url": "https://checkout.paystack.com/n4ysyedbuseog8c",
+    #     "access_code": "n4ysyedbuseog8c",
+    #     "reference": "hlr4bxhypt"
+    #   }
+    # }
+    api_method def self.initialize_transaction(**transaction_data)
+      raise ApiError.new(:invalid_amount, cancellable: true) if transaction_data[:amount].blank?
+      raise ApiError.new(:invalid_reference, cancellable: true) if transaction_data[:reference].blank?
+      raise ApiError.new(:invalid_email, cancellable: true) if transaction_data[:email].blank?
+
+      transaction_data[:amount] = (transaction_data[:amount] * 100).to_i
+
+      use_connection do |connection|
+        connection.post('/transaction/initialize', transaction_data.compact)
+      end
+    end
+
+    # Response from GET /transaction/verify/:reference endpoint.
+    class VerifyTransactionResponse < PaystackGateway::Response
+      include TransactionResponse
+
+      delegate :paid_at, to: :data
+
+      def transaction_completed_at
+        paid_at || super
+      end
+    end
+
+    # Raised when an error occurs while calling /transactions/verify/:reference
+    class VerifyTransactionError < ApiError
+      def transaction_not_found?
+        return false if !response_body
+
+        response_body[:status] == false && response_body[:message].match?(/transaction reference not found/i)
+      end
+    end
+
+    api_method def self.verify_transaction(reference:)
+      raise VerifyTransactionError, :invalid_reference if reference.blank?
+
+      use_connection do |connection|
+        connection.get("/transaction/verify/#{reference}")
+      end
+    end
+
+    # Response from POST /transaction/charge_authorization endpoint.
+    class ChargeAuthorizationResponse < PaystackGateway::Response
+      include TransactionResponse
+    end
+
+    api_method def self.charge_authorization(**transaction_data)
+      raise ApiError.new(:invalid_amount, cancellable: true) if transaction_data[:amount].blank?
+      raise ApiError.new(:invalid_reference, cancellable: true) if transaction_data[:reference].blank?
+      raise ApiError.new(:invalid_authorization_code, cancellable: true) if transaction_data[:authorization_code].blank?
+      raise ApiError.new(:invalid_email, cancellable: true) if transaction_data[:email].blank?
+
+      transaction_data[:amount] = (transaction_data[:amount] * 100).to_i
+
+      use_connection do |connection|
+        connection.post('/transaction/charge_authorization', transaction_data.compact)
+      end
+    end
+  end
+end

data/lib/paystack_gateway/transfer_recipients.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Create and manage beneficiaries that you send money to
+  # https://paystack.com/docs/api/#transfer-recipient
+  module TransferRecipients
+    include PaystackGateway::RequestModule
+
+    # Response from POST /transferrecipient endpoint.
+    class CreateTransferRecipientResponse < PaystackGateway::Response
+      delegate :id, :recipient_code, to: :data
+    end
+
+    api_method def self.create_transfer_recipient(name:, account_number:, bank_code:)
+      use_connection do |connection|
+        connection.post(
+          '/transferrecipient',
+          { type: :nuban, name: name, account_number: account_number, bank_code: bank_code, currency: :NGN },
+        )
+      end
+    end
+  end
+end