paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/bank.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/bank
+  #
+  # Banks
+  # A collection of endpoints for managing bank details
+  module Bank
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #list.
+    class ListResponse < PaystackGateway::Response; end
+
+    # Error response from #list.
+    class ListError < ApiError; end
+
+    # https://paystack.com/docs/api/bank/#list
+    # List Banks: GET /bank
+    # List banks supported on Paystack
+    #
+    # @param country ["ghana", "kenya", "nigeria", "south africa"]
+    #        The country from which to obtain the list of supported banks
+    # @param currency ["GHS", "KES", "NGN", "ZAR"]
+    #        The country from which to obtain the list of supported banks
+    # @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 [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. You need to combine this with either the `currency` or `country` filter.
+    # @param gateway ["emandate", "digitalbankmandate"]
+    #        The type of gateway for a Nigerian bank
+    # @param type ["ghipps", "mobile_money", "nuban", "kepss", "basa"]
+    #        Type of financial channel
+    # @param include_nip_sort_code [Boolean]
+    #        A flag that returns Nigerian banks with their NIP institution code. The returned
+    #        value can be used in identifying institutions on NIP.
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(
+      country: nil,
+      currency: nil,
+      use_cursor: nil,
+      per_page: nil,
+      page: nil,
+      next: 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
+    )
+      use_connection do |connection|
+        connection.get(
+          '/bank',
+          {
+            country:,
+            currency:,
+            use_cursor:,
+            perPage: per_page,
+            page:,
+            next:,
+            previous:,
+            pay_with_bank_transfer:,
+            pay_with_bank:,
+            enabled_for_verification:,
+            gateway:,
+            type:,
+            include_nip_sort_code:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #resolve_account_number.
+    class ResolveAccountNumberResponse < PaystackGateway::Response
+      delegate :account_number, :account_name, :bank_id, to: :data
+    end
+
+    # Error response from #resolve_account_number.
+    class ResolveAccountNumberError < ApiError; end
+
+    # https://paystack.com/docs/api/bank/#resolve_account_number
+    # Resolve Account Number: GET /bank/resolve
+    # Resolve an account number to confirm the name associated with it
+    #
+    # @param account_number [Integer]
+    #        The account number of interest
+    # @param bank_code [Integer]
+    #        The bank code associated with the account number
+    #
+    # @return [ResolveAccountNumberResponse] successful response
+    # @raise [ResolveAccountNumberError] if the request fails
+    api_method def self.resolve_account_number(account_number: nil, bank_code: nil)
+      use_connection do |connection|
+        connection.get(
+          '/bank/resolve',
+          { account_number:, bank_code: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #validate_account_number.
+    class ValidateAccountNumberResponse < PaystackGateway::Response
+      delegate :verified,
+               :verificationMessage,
+               :accountAcceptsDebits,
+               :accountAcceptsCredits,
+               :accountOpenForMoreThanThreeMonths,
+               :accountHolderMatch,
+               :accountOpen, to: :data
+    end
+
+    # Error response from #validate_account_number.
+    class ValidateAccountNumberError < ApiError; end
+
+    # https://paystack.com/docs/api/bank/#validate_account_number
+    # Validate Bank Account: POST /bank/validate
+    # Confirm the authenticity of a customer's account number before sending money
+    #
+    # @param account_name [String] (required)
+    #        Customer's first and last name registered with their bank
+    # @param account_number [String] (required)
+    #        Customer's account number
+    # @param account_type ["personal", "business"] (required)
+    #        The type of the customer's account number
+    # @param bank_code [String] (required)
+    #        The bank code of the customer’s bank. You can fetch the bank codes by using our
+    #        List Banks endpoint
+    # @param country_code [String] (required)
+    #        The two digit ISO code of the customer’s bank
+    # @param document_type ["identityNumber", "passportNumber", "businessRegistrationNumber"] (required)
+    #        Customer’s mode of identity
+    # @param document_number [String]
+    #        Customer’s mode of identity number
+    #
+    # @return [ValidateAccountNumberResponse] successful response
+    # @raise [ValidateAccountNumberError] if the request fails
+    api_method def self.validate_account_number(
+      account_name:,
+      account_number:,
+      account_type:,
+      bank_code:,
+      country_code:,
+      document_type:,
+      document_number: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/bank/validate',
+          {
+            account_name:,
+            account_number:,
+            account_type:,
+            bank_code:,
+            country_code:,
+            document_type:,
+            document_number:,
+          }.compact,
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/bulk_charge.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/bulkcharge
+  #
+  # Bulk Charges
+  # A collection of endpoints for creating and managing multiple recurring payments
+  module BulkCharge
+    include PaystackGateway::RequestModule
+
+    # Successful response from calling #list.
+    class ListResponse < PaystackGateway::Response; end
+
+    # Error response from #list.
+    class ListError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#list
+    # List Bulk Charge Batches: GET /bulkcharge
+    # List all bulk charge batches.
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The offset to retrieve data from
+    # @param status ["active", "paused", "complete"]
+    #        Filter by the status of the charges
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(per_page: nil, page: nil, status: nil)
+      use_connection do |connection|
+        connection.get(
+          '/bulkcharge',
+          { perPage: per_page, page:, status: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #initiate.
+    class InitiateResponse < PaystackGateway::Response
+      delegate :batch_code,
+               :reference,
+               :id,
+               :integration,
+               :domain,
+               :total_charges,
+               :pending_charges,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #initiate.
+    class InitiateError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#initiate
+    # Initiate Bulk Charge: POST /bulkcharge
+    # Charge multiple customers in batches
+    #
+    # @param charges [Array<Hash>] (required)
+    #        A list of charge object
+    #   @option charges [String] :authorization
+    #           Customer's card authorization code
+    #   @option charges [Integer] :amount
+    #           Amount to charge on the authorization
+    #   @option charges [String] :reference
+    #           A unique identifier containing lowercase letters `(a-z)`, digits `(0-9)` and these
+    #           symbols: dash (`-`), underscore(`_`)
+    #   @option charges [Boolean] :attempt_partial_debit
+    #           A flag to indicate if you want us to try recouping lower amounts when the customer
+    #           has insufficient fund
+    #   @option charges [Integer] :at_least
+    #           Minimum amount to charge if the attempt_partial_debit flag is set
+    #   @option charges [Hash] :metadata
+    #           JSON object of custom data
+    #
+    # @return [InitiateResponse] successful response
+    # @raise [InitiateError] if the request fails
+    api_method def self.initiate(charges:)
+      use_connection do |connection|
+        connection.post(
+          '/bulkcharge',
+          charges,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :batch_code,
+               :reference,
+               :id,
+               :integration,
+               :domain,
+               :total_charges,
+               :pending_charges,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#fetch
+    # Fetch Bulk Charge Batch: GET /bulkcharge/{code}
+    # This endpoint retrieves a specific batch code. It also returns useful information
+    # on its progress by way of the `total_charges` and `pending_charges` attributes.
+    #
+    # @param code [String] (required)
+    #        The code for the charge whose batches you want to retrieve
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/bulkcharge/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #charges.
+    class ChargesResponse < PaystackGateway::Response; end
+
+    # Error response from #charges.
+    class ChargesError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#charges
+    # List Charges in a Batch: GET /bulkcharge/{code}/charges
+    # This endpoint retrieves the charges associated with a specified batch code
+    #
+    # @param code [String] (required)
+    #        An code for the batch whose charges you want to retrieve
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The offset to retrieve data from
+    # @param status ["success", "failed", "pending", "error", "inactive_authorization"]
+    #        Filter by the status of the charges
+    #
+    # @return [ChargesResponse] successful response
+    # @raise [ChargesError] if the request fails
+    api_method def self.charges(code:, per_page: nil, page: nil, status: nil)
+      use_connection do |connection|
+        connection.get(
+          "/bulkcharge/#{code}/charges",
+          { perPage: per_page, page:, status: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #pause.
+    class PauseResponse < PaystackGateway::Response; end
+
+    # Error response from #pause.
+    class PauseError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#pause
+    # Pause Bulk Charge Batch: GET /bulkcharge/pause/{code}
+    # Pause the processing of a charge batch
+    #
+    # @param code [String] (required)
+    #        The batch code for the bulk charge you want to pause
+    #
+    # @return [PauseResponse] successful response
+    # @raise [PauseError] if the request fails
+    api_method def self.pause(code:)
+      use_connection do |connection|
+        connection.get(
+          "/bulkcharge/pause/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #resume.
+    class ResumeResponse < PaystackGateway::Response; end
+
+    # Error response from #resume.
+    class ResumeError < ApiError; end
+
+    # https://paystack.com/docs/api/bulk-charge/#resume
+    # Resume Bulk Charge Batch: GET /bulkcharge/resume/{code}
+    # Resume the processing of a previously paused charge batch
+    #
+    # @param code [String] (required)
+    #        The batch code for the bulk charge you want to pause
+    #
+    # @return [ResumeResponse] successful response
+    # @raise [ResumeError] if the request fails
+    api_method def self.resume(code:)
+      use_connection do |connection|
+        connection.get(
+          "/bulkcharge/resume/#{code}",
+        )
+      end
+    end
+  end
+end