paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/legacy/dedicated_virtual_accounts.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+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
+  #
+  # @deprecated Use PaystackGateway::DedicatedVirtualAccount instead.
+  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/requery/:account_number endpoint
+    class RequeryDedicatedAccountResponse < PaystackGateway::Response; end
+
+    api_method def self.requery_dedicated_account(account_number:, bank:)
+      use_connection do |connection|
+        connection.get('/dedicated_account/requery', { account_number:, provider_slug: bank })
+      end
+    end
+  end
+end

data/lib/paystack_gateway/legacy/miscellaneous.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # Backwards-compatible API methods retained from releases before 0.2.0.
+  module Miscellaneous
+    include PaystackGateway::RequestModule
+
+    # Successful response from GET /bank.
+    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
+
+    # Error response from GET /bank.
+    class ListBanksError < ApiError; end
+
+    # https://paystack.com/docs/api/miscellaneous/#bank
+    # @deprecated Use PaystackGateway::Bank.list instead.
+    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/legacy/plans.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage installment payment options
+  # https://paystack.com/docs/api/plan/#create
+  #
+  # @deprecated Use PaystackGateway::Plan instead.
+  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/legacy/refunds.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage transaction refunds.
+  # https://paystack.com/docs/api/refund
+  #
+  # @deprecated Use PaystackGateway::Refund instead.
+  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/legacy/subaccounts.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage subaccounts https://paystack.com/docs/api/subaccount/
+  #
+  # @deprecated Use PaystackGateway::Subaccount instead.
+  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/legacy/transaction_response.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+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/legacy/transactions.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage payments https://paystack.com/docs/api/#transaction
+  #
+  # @deprecated Use PaystackGateway::Transaction instead.
+  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?
+        parsed_response_body[:status] == false &&
+          parsed_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/legacy/transfer_recipients.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Create and manage beneficiaries that you send money to
+  # https://paystack.com/docs/api/#transfer-recipient
+  #
+  # @deprecated Use PaystackGateway::TransferRecipient instead.
+  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

data/lib/paystack_gateway/legacy/transfers.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Automate sending money https://paystack.com/docs/api/#transfer
+  #
+  # @deprecated Use PaystackGateway::Transfer instead.
+  module Transfers
+    include PaystackGateway::RequestModule
+
+    # Response from POST /transfer endpoint.
+    class InitiateTransferResponse < PaystackGateway::Response
+      include TransactionResponse
+
+      delegate :transfer_code, :transferred_at, to: :data
+
+      def transaction_completed_at
+        transferred_at || super
+      end
+    end
+
+    # Raised when an error occurs while calling POST /transfer
+    class InitiateTransferError < ApiError
+      def transaction_failed?
+        parsed_response_body[:status] == false && http_code == 400
+      end
+
+      def failure_reason
+        parsed_response_body[:message]
+      end
+    end
+
+    api_method def self.initiate_transfer(amount:, recipient_code:, reference:, reason: nil)
+      response = use_connection do |connection|
+        connection.post(
+          '/transfer',
+          {
+            source: :balance, amount: (amount * 100).to_i, recipient: recipient_code,
+            reference: reference, reason: reason,
+          }.compact,
+        )
+      end
+      response.tap { |r| r.completed_at = Time.current }
+    end
+
+    # Response from GET /transfer/verify/:reference endpoint.
+    class VerifyTransferResponse < InitiateTransferResponse; end
+
+    # Raised when an error occurs while calling GET /transfer/verify/:reference
+    class VerifyTransferError < ApiError
+      def transaction_not_found?
+        parsed_response_body[:status] == false && parsed_response_body[:message]&.match?(/transfer not found/i)
+      end
+    end
+
+    api_method def self.verify_transfer(reference:)
+      use_connection do |connection|
+        connection.get("/transfer/verify/#{reference}")
+      end
+    end
+  end
+end

data/lib/paystack_gateway/legacy/verification.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Legacy implementation retained for backwards compatibility.
+
+module PaystackGateway
+  # Perform KYC processes https://paystack.com/docs/api/#verification
+  #
+  # @deprecated Use PaystackGateway::Bank instead.
+  module Verification
+    include PaystackGateway::RequestModule
+
+    # Response from GET /bank/resolve endpoint.
+    class ResolveAccountNumberResponse < PaystackGateway::Response
+      delegate :account_name, :bank_id, to: :data
+
+      def account_valid?
+        status && account_name.present?
+      end
+    end
+
+    # Raised when an error occurs while calling /bank/resolve
+    class ResolveAccountNumberError < ApiError
+      def invalid_account?
+        http_code == 422 && parsed_response_body[:status] == false
+      end
+    end
+
+    api_method def self.resolve_account_number(account_number:, bank_code:)
+      use_connection(cache_options: {}) do |connection|
+        connection.get(
+          '/bank/resolve',
+          { account_number: account_number, bank_code: bank_code },
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/miscellaneous.rb

@@ -1,26 +1,88 @@
 # 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
+  # https://paystack.com/docs/api/miscellaneous
+  #
+  # Miscellaneous
+  # A collection of endpoints that provides utility functions
   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)
+    # Successful response from calling #resolve_card_bin.
+    class ResolveCardBinResponse < PaystackGateway::Response
+      delegate :bin,
+               :brand,
+               :sub_brand,
+               :country_code,
+               :country_name,
+               :card_type,
+               :bank,
+               :currency,
+               :linked_bank_id, to: :data
+    end
 
-      def bank_details(*attributes) = data.map { _1.slice(*attributes) }
+    # Error response from #resolve_card_bin.
+    class ResolveCardBinError < ApiError; end
 
-      def by_bank_names = data.index_by(&:name)
-      def by_bank_codes = data.index_by(&:code)
+    # https://paystack.com/docs/api/miscellaneous/#resolve_card_bin
+    # Resolve Card BIN: GET /decision/bin/{bin}
+    # Get the details of a card BIN
+    #
+    # @param bin [Integer] (required)
+    #        The card bank identification number
+    #
+    # @return [ResolveCardBinResponse] successful response
+    # @raise [ResolveCardBinError] if the request fails
+    api_method def self.resolve_card_bin(bin:)
+      use_connection do |connection|
+        connection.get(
+          "/decision/bin/#{bin}",
+        )
+      end
     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: } : {})
+    # Successful response from calling #list_countries.
+    class ListCountriesResponse < PaystackGateway::Response; end
+
+    # Error response from #list_countries.
+    class ListCountriesError < ApiError; end
+
+    # https://paystack.com/docs/api/miscellaneous/#list_countries
+    # List Countries: GET /country
+    # List all supported countries on Paystack
+    #
+    #
+    # @return [ListCountriesResponse] successful response
+    # @raise [ListCountriesError] if the request fails
+    api_method def self.list_countries
+      use_connection do |connection|
+        connection.get(
+          '/country',
+        )
+      end
+    end
+
+    # Successful response from calling #avs.
+    class AvsResponse < PaystackGateway::Response; end
+
+    # Error response from #avs.
+    class AvsError < ApiError; end
+
+    # https://paystack.com/docs/api/miscellaneous/#avs
+    # List States (AVS): GET /address_verification/states
+    # Get a list of states for a country for address verification
+    #
+    # @param country [String]
+    #        The country code of the states to list. It is gotten after the charge request
+    #
+    # @return [AvsResponse] successful response
+    # @raise [AvsError] if the request fails
+    api_method def self.avs(country: nil)
+      use_connection do |connection|
+        connection.get(
+          '/address_verification/states',
+          { country: }.compact,
+        )
       end
     end
   end