paystack-gateway 0.1.0 → 0.2.0

data/lib/paystack_gateway/transfer_recipient.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/transferrecipient
+  #
+  # Transfer Recipients
+  # A collection of endpoints for creating and managing beneficiaries that you send money to
+  module TransferRecipient
+    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/transfer-recipient/#list
+    # List Transfer Recipients: GET /transferrecipient
+    # List transfer recipients available on your integration
+    #
+    # @param use_cursor [Boolean]
+    #        A flag to indicate if cursor based pagination should be used
+    # @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 per_page [Integer]
+    #        The number of records to fetch per request
+    # @param page [Integer]
+    #        The offset to retrieve data from
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(use_cursor: nil, next: nil, previous: nil, per_page: nil, page: nil)
+      use_connection do |connection|
+        connection.get(
+          '/transferrecipient',
+          { use_cursor:, next:, previous:, per_page:, page: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :active,
+               :createdAt,
+               :currency,
+               :description,
+               :domain,
+               :email,
+               :id,
+               :integration,
+               :name,
+               :recipient_code,
+               :type,
+               :updatedAt,
+               :is_deleted,
+               :isDeleted,
+               :details, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer-recipient/#create
+    # Create Transfer Recipient: POST /transferrecipient
+    # Creates a new recipient. A duplicate account number will lead to the retrieval of
+    # the existing record.
+    #
+    # @param type ["nuban", "ghipss", "mobile_money", "basa", "authorization"] (required)
+    #        Recipient Type
+    # @param name [String] (required)
+    #        The recipient's name according to their account registration.
+    # @param account_number [String] (required)
+    #        Recipient's bank account number
+    # @param bank_code [String] (required)
+    #        Recipient's bank code. You can get the list of Bank Codes by calling the List Banks
+    #        endpoint
+    # @param description [String]
+    #        A description for this recipient
+    # @param currency [String]
+    #        Currency for the account receiving the transfer
+    # @param authorization_code [String]
+    #        An authorization code from a previous transaction
+    # @param metadata [Hash]
+    #        JSON object of custom data
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(
+      type:,
+      name:,
+      account_number:,
+      bank_code:,
+      description: nil,
+      currency: nil,
+      authorization_code: nil,
+      metadata: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/transferrecipient',
+          {
+            type:,
+            name:,
+            account_number:,
+            bank_code:,
+            description:,
+            currency:,
+            authorization_code:,
+            metadata:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #bulk.
+    class BulkResponse < PaystackGateway::Response
+      delegate :success, :errors, to: :data
+    end
+
+    # Error response from #bulk.
+    class BulkError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer-recipient/#bulk
+    # Bulk Create Transfer Recipient: POST /transferrecipient/bulk
+    # Create multiple transfer recipients in batches. A duplicate account number will
+    # lead to the retrieval of the existing record.
+    #
+    # @param batch [Array<Hash>] (required)
+    #        A list of transfer recipient object.
+    #
+    # @return [BulkResponse] successful response
+    # @raise [BulkError] if the request fails
+    api_method def self.bulk(batch:)
+      use_connection do |connection|
+        connection.post(
+          '/transferrecipient/bulk',
+          { batch: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :integration,
+               :domain,
+               :type,
+               :currency,
+               :name,
+               :details,
+               :description,
+               :recipient_code,
+               :active,
+               :recipient_account,
+               :institution_code,
+               :email,
+               :id,
+               :isDeleted,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer-recipient/#fetch
+    # Fetch Transfer recipient: GET /transferrecipient/{code}
+    # Fetch the details of a transfer recipient
+    #
+    # @param code [String] (required)
+    #        Transfer recipient code
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/transferrecipient/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response; end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer-recipient/#update
+    # Update Transfer Recipient: PUT /transferrecipient/{code}
+    # Update the details of a transfer recipient
+    #
+    # @param code [String] (required)
+    #        Transfer recipient code
+    # @param name [String]
+    #        Recipient's name
+    # @param email [String]
+    #        Recipient's email address
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(code:, name: nil, email: nil)
+      use_connection do |connection|
+        connection.put(
+          "/transferrecipient/#{code}",
+          { name:, email: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #delete.
+    class DeleteResponse < PaystackGateway::Response; end
+
+    # Error response from #delete.
+    class DeleteError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer-recipient/#delete
+    # Delete Transfer Recipient: DELETE /transferrecipient/{code}
+    # Delete a transfer recipient (sets the transfer recipient to inactive)
+    #
+    # @param code [String] (required)
+    #        Transfer recipient code
+    #
+    # @return [DeleteResponse] successful response
+    # @raise [DeleteError] if the request fails
+    api_method def self.delete(code:)
+      use_connection do |connection|
+        connection.delete(
+          "/transferrecipient/#{code}",
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/transfer_recipients.rb

@@ -1,23 +1,3 @@
 # 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
+require 'paystack_gateway/legacy/transfer_recipients'

data/lib/paystack_gateway/transfers.rb

@@ -1,59 +1,3 @@
 # frozen_string_literal: true
 
-module PaystackGateway
-  # Automate sending money https://paystack.com/docs/api/#transfer
-  module Transfers
-    include PaystackGateway::RequestModule
-
-    # Response from POST /transfer endpoint.
-    class InitiateTransferResponse < PaystackGateway::Response
-      include TransactionResponse
-
-      delegate :transfer_code, :id, :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?
-        response_body[:status] == false && http_code == 400
-      end
-
-      def failure_reason
-        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?
-        response_body[:status] == false && 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
+require 'paystack_gateway/legacy/transfers'

data/lib/paystack_gateway/verification.rb

@@ -1,33 +1,3 @@
 # frozen_string_literal: true
 
-module PaystackGateway
-  # Perform KYC processes https://paystack.com/docs/api/#verification
-  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 && 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
+require 'paystack_gateway/legacy/verification'

data/lib/paystack_gateway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaystackGateway
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/paystack_gateway/virtual_terminal.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/virtualterminal
+  #
+  # Virtual Terminal
+  # A collection of endpoints for building in-person payments without a physical terminal
+  module VirtualTerminal
+    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/virtual-terminal/#list
+    # List Virtual Terminals: GET /virtual_terminal
+    # List Virtual Terminals on your integration
+    #
+    # @param per_page [Integer]
+    #        The number of records to fetch per request
+    # @param page [Integer]
+    #        The offset to retrieve data from
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(per_page: nil, page: nil)
+      use_connection do |connection|
+        connection.get(
+          '/virtual_terminal',
+          { perPage: per_page, page: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :id,
+               :name,
+               :integration,
+               :domain,
+               :code,
+               :paymentMethods,
+               :active,
+               :metadata,
+               :destinations,
+               :currency, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#create
+    # Create Virtual Terminal: POST /virtual_terminal
+    # Create a Virtual Terminal on your integration
+    #
+    # @param name [String] (required)
+    #        The name of the virtual terminal
+    # @param destinations [Array<Hash>] (required)
+    #        Array of objects containing recipients for payment notifications for the Virtual
+    #        Terminal.
+    # @param split_code [String]
+    #        Split code to associate with the virtual terminal
+    # @param metadata [Hash]
+    #        Additional custom data as key-value pairs
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(name:, destinations:, split_code: nil, metadata: nil)
+      use_connection do |connection|
+        connection.post(
+          '/virtual_terminal',
+          { name:, destinations:, split_code:, metadata: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :id,
+               :code,
+               :name,
+               :integration,
+               :domain,
+               :paymentMethods,
+               :active,
+               :created_at,
+               :connect_account_id,
+               :destinations,
+               :currency, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#fetch
+    # Fetch Virtual Terminal: GET /virtual_terminal/{code}
+    # Fetch a Virtual Terminal on your integration
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/virtual_terminal/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response
+      delegate :id,
+               :code,
+               :name,
+               :integration,
+               :domain,
+               :paymentMethods,
+               :active,
+               :created_at,
+               :connect_account_id,
+               :destinations,
+               :currency, to: :data
+    end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#update
+    # Update Virtual Terminal: PUT /virtual_terminal/{code}
+    # Update a Virtual Terminal on your integration
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    # @param name [String] (required)
+    #        Name of the virtual terminal
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(code:, name:)
+      use_connection do |connection|
+        connection.put(
+          "/virtual_terminal/#{code}",
+          { name: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #deactivate.
+    class DeactivateResponse < PaystackGateway::Response; end
+
+    # Error response from #deactivate.
+    class DeactivateError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#deactivate
+    # Deactivate Virtual Terminal: PUT /virtual_terminal/{code}/deactivate
+    # Deactivate a Virtual Terminal on your integration
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    #
+    # @return [DeactivateResponse] successful response
+    # @raise [DeactivateError] if the request fails
+    api_method def self.deactivate(code:)
+      use_connection do |connection|
+        connection.put(
+          "/virtual_terminal/#{code}/deactivate",
+        )
+      end
+    end
+
+    # Successful response from calling #destination_assign.
+    class DestinationAssignResponse < PaystackGateway::Response; end
+
+    # Error response from #destination_assign.
+    class DestinationAssignError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#destination_assign
+    # Assign Destination to Virtual Terminal: POST /virtual_terminal/{code}/destination/assign
+    # Add a destination (WhatsApp number) to a Virtual Terminal on your integration
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    # @param destinations [Array<Hash>] (required)
+    #        Array of objects containing recipients for payment notifications for the Virtual
+    #        Terminal.
+    #
+    # @return [DestinationAssignResponse] successful response
+    # @raise [DestinationAssignError] if the request fails
+    api_method def self.destination_assign(code:, destinations:)
+      use_connection do |connection|
+        connection.post(
+          "/virtual_terminal/#{code}/destination/assign",
+          { destinations: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #destination_unassign.
+    class DestinationUnassignResponse < PaystackGateway::Response; end
+
+    # Error response from #destination_unassign.
+    class DestinationUnassignError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#destination_unassign
+    # Unassign Destination from Virtual Terminal: POST /virtual_terminal/{code}/destination/unassign
+    # Unassign a destination (WhatsApp Number) from a Virtual Terminal on your integration
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    # @param targets [Array<String>] (required)
+    #        Array of destination targets to unassign
+    #
+    # @return [DestinationUnassignResponse] successful response
+    # @raise [DestinationUnassignError] if the request fails
+    api_method def self.destination_unassign(code:, targets:)
+      use_connection do |connection|
+        connection.post(
+          "/virtual_terminal/#{code}/destination/unassign",
+          { targets: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #add_split_code.
+    class AddSplitCodeResponse < PaystackGateway::Response
+      delegate :id,
+               :name,
+               :type,
+               :currency,
+               :integration,
+               :domain,
+               :split_code,
+               :active,
+               :bearer_type,
+               :bearer_subaccount,
+               :createdAt,
+               :updatedAt,
+               :is_dynamic,
+               :subaccounts,
+               :total_subaccounts, to: :data
+    end
+
+    # Error response from #add_split_code.
+    class AddSplitCodeError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#add_split_code
+    # Add Split Code to Virtual Terminal: PUT /virtual_terminal/{code}/split_code
+    # Add Split Code to Virtual Terminal
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    # @param split_code [String] (required)
+    #        The split code to assign to the virtual terminal
+    #
+    # @return [AddSplitCodeResponse] successful response
+    # @raise [AddSplitCodeError] if the request fails
+    api_method def self.add_split_code(code:, split_code:)
+      use_connection do |connection|
+        connection.put(
+          "/virtual_terminal/#{code}/split_code",
+          { split_code: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #delete_split_code.
+    class DeleteSplitCodeResponse < PaystackGateway::Response; end
+
+    # Error response from #delete_split_code.
+    class DeleteSplitCodeError < ApiError; end
+
+    # https://paystack.com/docs/api/virtual-terminal/#delete_split_code
+    # Remove Split Code from Virtual Terminal: DELETE /virtual_terminal/{code}/split_code
+    # Remove Split Code from Virtual Terminal
+    #
+    # @param code [String] (required)
+    #        Code of the Virtual Terminal
+    # @param split_code [String] (required)
+    #        The split code to assign to the virtual terminal
+    #
+    # @return [DeleteSplitCodeResponse] successful response
+    # @raise [DeleteSplitCodeError] if the request fails
+    api_method def self.delete_split_code(code:, split_code:)
+      use_connection do |connection|
+        connection.delete(
+          "/virtual_terminal/#{code}/split_code",
+        ) do |request|
+          request.body = { split_code: }.compact
+        end
+      end
+    end
+  end
+end