paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/transactions.rb

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

data/lib/paystack_gateway/transfer.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/transfer
+  #
+  # Transfers
+  # A collection of endpoints for automating sending money to beneficiaries
+  module Transfer
+    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/#list
+    # List Transfers: GET /transfer
+    # List the transfers made 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
+    # @param from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    # @param recipient [String]
+    #        Filter transfer by the recipient code
+    # @param status ["pending", "success", "failed", "otp", "abandoned", "reversed", "blocked", "rejected", "received"]
+    #        Filter transfer by status
+    #
+    # @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,
+      from: nil,
+      to: nil,
+      recipient: nil,
+      status: nil
+    )
+      use_connection do |connection|
+        connection.get(
+          '/transfer',
+          {
+            use_cursor:,
+            next:,
+            previous:,
+            per_page:,
+            page:,
+            from:,
+            to:,
+            recipient:,
+            status:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #initiate.
+    class InitiateResponse < PaystackGateway::Response
+      delegate :transfersessionid,
+               :transfertrials,
+               :domain,
+               :amount,
+               :currency,
+               :reference,
+               :source,
+               :source_details,
+               :reason,
+               :failures,
+               :transfer_code,
+               :titan_code,
+               :transferred_at,
+               :id,
+               :integration,
+               :request,
+               :recipient,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #initiate.
+    class InitiateError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#initiate
+    # Initiate Transfer: POST /transfer
+    # Send money to your customers
+    #
+    # @param amount [Integer] (required)
+    #        Amount to transfer in kobo if currency is NGN and pesewas if currency is GHS.
+    # @param recipient [String] (required)
+    #        The transfer recipient's code
+    # @param reference [String] (required)
+    #        To ensure idempotency, you need to provide e a unique identifier for the request.
+    #        The identifier should be a lowercase alphanumeric string with only -,_ symbols allowed.
+    # @param source [String] (required)
+    #        The source of funds to send from
+    # @param reason [String]
+    #        The reason or narration for the transfer.
+    # @param currency ["NGN", "ZAR", "KES", "GHS"]
+    #        Specify the currency of the transfer.
+    #
+    # @return [InitiateResponse] successful response
+    # @raise [InitiateError] if the request fails
+    api_method def self.initiate(
+      amount:,
+      recipient:,
+      reference:,
+      source:,
+      reason: nil,
+      currency: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/transfer',
+          {
+            amount:,
+            recipient:,
+            reference:,
+            source:,
+            reason:,
+            currency:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #finalize.
+    class FinalizeResponse < PaystackGateway::Response; end
+
+    # Error response from #finalize.
+    class FinalizeError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#finalize
+    # Finalize Transfer: POST /transfer/finalize_transfer
+    # Finalize an initiated transfer
+    #
+    # @param transfer_code [String] (required)
+    #        The transfer code you want to finalize
+    # @param otp [String] (required)
+    #        OTP sent to business phone to verify transfer
+    #
+    # @return [FinalizeResponse] successful response
+    # @raise [FinalizeError] if the request fails
+    api_method def self.finalize(transfer_code:, otp:)
+      use_connection do |connection|
+        connection.post(
+          '/transfer/finalize_transfer',
+          { transfer_code:, otp: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #bulk.
+    class BulkResponse < PaystackGateway::Response; end
+
+    # Error response from #bulk.
+    class BulkError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#bulk
+    # Initiate Bulk Transfer: POST /transfer/bulk
+    # Batch multiple transfers in a single request. You need to disable the Transfers
+    # OTP requirement to use this endpoint.
+    #
+    # @param source [String] (required)
+    #        The source of funds for the transfer.
+    # @param transfers [Array<Hash>] (required)
+    #        A list of transfer object
+    # @param currency ["NGN", "ZAR", "KES", "GHS"]
+    #        Specify the currency of the transfer.
+    #
+    # @return [BulkResponse] successful response
+    # @raise [BulkError] if the request fails
+    api_method def self.bulk(source:, transfers:, currency: nil)
+      use_connection do |connection|
+        connection.post(
+          '/transfer/bulk',
+          { source:, transfers:, currency: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :amount,
+               :createdAt,
+               :currency,
+               :domain,
+               :failures,
+               :id,
+               :integration,
+               :reason,
+               :reference,
+               :source,
+               :source_details,
+               :titan_code,
+               :transfer_code,
+               :request,
+               :transferred_at,
+               :updatedAt,
+               :recipient,
+               :session,
+               :fee_charged,
+               :fees_breakdown,
+               :gateway_response, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#fetch
+    # Fetch Transfer: GET /transfer/{code}
+    # Get details of a transfer on your integration
+    #
+    # @param code [String] (required)
+    #        Transfer code
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/transfer/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #verify.
+    class VerifyResponse < PaystackGateway::Response
+      delegate :amount,
+               :createdAt,
+               :currency,
+               :domain,
+               :failures,
+               :id,
+               :integration,
+               :reason,
+               :reference,
+               :source,
+               :source_details,
+               :titan_code,
+               :transfer_code,
+               :transferred_at,
+               :updatedAt,
+               :recipient,
+               :session,
+               :gateway_response, to: :data
+    end
+
+    # Error response from #verify.
+    class VerifyError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#verify
+    # Verify Transfer: GET /transfer/verify/{reference}
+    # Verify the status of a transfer on your integration
+    #
+    # @param reference [String] (required)
+    #        Transfer reference
+    #
+    # @return [VerifyResponse] successful response
+    # @raise [VerifyError] if the request fails
+    api_method def self.verify(reference:)
+      use_connection do |connection|
+        connection.get(
+          "/transfer/verify/#{reference}",
+        )
+      end
+    end
+
+    # Successful response from calling #export_transfer.
+    class ExportTransferResponse < PaystackGateway::Response; end
+
+    # Error response from #export_transfer.
+    class ExportTransferError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#export_transfer
+    # Export Transfers: GET /transfer/export
+    # Export a list of transfers carried out on your integration
+    #
+    # @param recipient [String]
+    #        Export transfer by the recipient code
+    # @param status ["pending", "success", "failed", "otp", "abandoned", "reversed", "blocked", "rejected", "received"]
+    #        Export transfer by status
+    # @param from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [ExportTransferResponse] successful response
+    # @raise [ExportTransferError] if the request fails
+    api_method def self.export_transfer(recipient: nil, status: nil, from: nil, to: nil)
+      use_connection do |connection|
+        connection.get(
+          '/transfer/export',
+          { recipient:, status:, from:, to: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #resend_otp.
+    class ResendOtpResponse < PaystackGateway::Response; end
+
+    # Error response from #resend_otp.
+    class ResendOtpError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#resend_otp
+    # Resend OTP for Transfer: POST /transfer/resend_otp
+    # Generates and send a new OTP to customer in the event they are having trouble receiving
+    # one.
+    #
+    # @param transfer_code [String] (required)
+    #        The transfer code that requires an OTP validation
+    # @param reason ["disable_otp", "resend_otp", "transfer"] (required)
+    #        Specify the flag to indicate the purpose of the OTP
+    #
+    # @return [ResendOtpResponse] successful response
+    # @raise [ResendOtpError] if the request fails
+    api_method def self.resend_otp(transfer_code:, reason:)
+      use_connection do |connection|
+        connection.post(
+          '/transfer/resend_otp',
+          { transfer_code:, reason: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #disable_otp.
+    class DisableOtpResponse < PaystackGateway::Response; end
+
+    # Error response from #disable_otp.
+    class DisableOtpError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#disable_otp
+    # Disable OTP for Transfers: POST /transfer/disable_otp
+    # This is used in the event that you want to be able to complete transfers programmatically
+    # without use of OTPs. No arguments required. You will get an OTP to complete the
+    # request.
+    #
+    #
+    # @return [DisableOtpResponse] successful response
+    # @raise [DisableOtpError] if the request fails
+    api_method def self.disable_otp
+      use_connection do |connection|
+        connection.post(
+          '/transfer/disable_otp',
+        )
+      end
+    end
+
+    # Successful response from calling #disable_otp_finalize.
+    class DisableOtpFinalizeResponse < PaystackGateway::Response; end
+
+    # Error response from #disable_otp_finalize.
+    class DisableOtpFinalizeError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#disable_otp_finalize
+    # Finalize Disabling OTP for Transfers: POST /transfer/disable_otp_finalize
+    # Finalize the request to disable OTP on your transfers
+    #
+    # @param otp [String] (required)
+    #        OTP sent to business phone to verify disabling OTP requirement
+    #
+    # @return [DisableOtpFinalizeResponse] successful response
+    # @raise [DisableOtpFinalizeError] if the request fails
+    api_method def self.disable_otp_finalize(otp:)
+      use_connection do |connection|
+        connection.post(
+          '/transfer/disable_otp_finalize',
+          { otp: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #enable_otp.
+    class EnableOtpResponse < PaystackGateway::Response; end
+
+    # Error response from #enable_otp.
+    class EnableOtpError < ApiError; end
+
+    # https://paystack.com/docs/api/transfer/#enable_otp
+    # Enable OTP requirement for Transfers: POST /transfer/enable_otp
+    # In the event that a customer wants to stop being able to complete transfers programmatically,
+    # this endpoint helps turn OTP requirement back on. No arguments required.
+    #
+    #
+    # @return [EnableOtpResponse] successful response
+    # @raise [EnableOtpError] if the request fails
+    api_method def self.enable_otp
+      use_connection do |connection|
+        connection.post(
+          '/transfer/enable_otp',
+        )
+      end
+    end
+  end
+end