paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/customer.rb

@@ -0,0 +1,498 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/customer
+  #
+  # Customers
+  # A collection of endpoints for creating and managing customers on an integration
+  module Customer
+    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/customer/#list
+    # List Customers: GET /customer
+    # List customers 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 from [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    # @param per_page [String]
+    #        The number of records to fetch per request
+    # @param page [String]
+    #        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,
+      from: nil,
+      to: nil,
+      per_page: nil,
+      page: nil
+    )
+      use_connection do |connection|
+        connection.get(
+          '/customer',
+          {
+            use_cursor:,
+            next:,
+            previous:,
+            from:,
+            to:,
+            perPage: per_page,
+            page:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :transactions,
+               :subscriptions,
+               :authorizations,
+               :email,
+               :first_name,
+               :last_name,
+               :phone,
+               :integration,
+               :domain,
+               :metadata,
+               :customer_code,
+               :risk_action,
+               :id,
+               :createdAt,
+               :updatedAt,
+               :identified,
+               :identifications, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#create
+    # Create Customer: POST /customer
+    # Create a customer on your integration
+    #
+    # @param email [String] (required)
+    #        Customer's email address
+    # @param first_name [String]
+    #        Customer's first name
+    # @param last_name [String]
+    #        Customer's last name
+    # @param phone [String]
+    #        Customer's phone number
+    # @param metadata [String]
+    #        Stringified JSON object of custom data
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(email:, first_name: nil, last_name: nil, phone: nil, metadata: nil)
+      use_connection do |connection|
+        connection.post(
+          '/customer',
+          { email:, first_name:, last_name:, phone:, metadata: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :transactions,
+               :subscriptions,
+               :authorizations,
+               :first_name,
+               :last_name,
+               :email,
+               :phone,
+               :metadata,
+               :domain,
+               :customer_code,
+               :risk_action,
+               :id,
+               :integration,
+               :createdAt,
+               :updatedAt,
+               :created_at,
+               :updated_at,
+               :total_transactions,
+               :total_transaction_value,
+               :dedicated_account,
+               :dedicated_accounts,
+               :identified,
+               :identifications, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#fetch
+    # Fetch Customer: GET /customer/{code}
+    # Get details of a customer on your integration.
+    #
+    # @param code [String] (required)
+    #        The code for the customer gotten from the response of the customer creation
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/customer/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response
+      delegate :first_name,
+               :last_name,
+               :email,
+               :phone,
+               :metadata,
+               :domain,
+               :customer_code,
+               :risk_action,
+               :id,
+               :integration,
+               :createdAt,
+               :updatedAt,
+               :identified,
+               :identifications, to: :data
+    end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#update
+    # Update Customer: PUT /customer/{code}
+    # Update a customer's details on your integration
+    #
+    # @param code [String] (required)
+    #        The code for the customer gotten from the response of the customer creation
+    # @param first_name [String]
+    #        Customer's first name
+    # @param last_name [String]
+    #        Customer's last name
+    # @param phone [String]
+    #        Customer's phone number
+    # @param metadata [String]
+    #        Stringified JSON object of custom data
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(code:, first_name: nil, last_name: nil, phone: nil, metadata: nil)
+      use_connection do |connection|
+        connection.put(
+          "/customer/#{code}",
+          { first_name:, last_name:, phone:, metadata: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #risk_action.
+    class RiskActionResponse < PaystackGateway::Response
+      delegate :transactions,
+               :subscriptions,
+               :authorizations,
+               :first_name,
+               :last_name,
+               :email,
+               :phone,
+               :metadata,
+               :domain,
+               :customer_code,
+               :risk_action,
+               :id,
+               :integration,
+               :createdAt,
+               :updatedAt,
+               :identified,
+               :identifications, to: :data
+    end
+
+    # Error response from #risk_action.
+    class RiskActionError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#risk_action
+    # Set Risk Action: POST /customer/set_risk_action
+    # Set customer's risk action by whitelisting or blacklisting the customer
+    #
+    # @param customer [String] (required)
+    #        The customer code from the response of the customer creation
+    # @param risk_action ["allow", "deny", "default"]
+    #        This determines the fraud rules that should be applied to the customer
+    #
+    # @return [RiskActionResponse] successful response
+    # @raise [RiskActionError] if the request fails
+    api_method def self.risk_action(customer:, risk_action: nil)
+      use_connection do |connection|
+        connection.post(
+          '/customer/set_risk_action',
+          { customer:, risk_action: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #validate.
+    class ValidateResponse < PaystackGateway::Response; end
+
+    # Error response from #validate.
+    class ValidateError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#validate
+    # Validate Customer: POST /customer/{code}/identification
+    # Validate a customer's identity
+    #
+    # @param code [String] (required)
+    #        The code for the customer gotten from the response of the customer creation
+    # @param first_name [String] (required)
+    #        Customer's first name
+    # @param last_name [String] (required)
+    #        Customer's last name
+    # @param type [String] (required)
+    #        Predefined types of identification.
+    # @param country [String] (required)
+    #        Two-letter country code of identification issuer
+    # @param bvn [String] (required)
+    #        Customer's Bank Verification Number
+    # @param bank_code [String] (required)
+    #        You can get the list of bank codes by calling the List Banks endpoint (https://api.paystack.co/bank).
+    # @param account_number [String] (required)
+    #        Customer's bank account number.
+    # @param middle_name [String]
+    #        Customer's middle name
+    # @param value [String]
+    #        Customer's identification number.
+    #
+    # @return [ValidateResponse] successful response
+    # @raise [ValidateError] if the request fails
+    api_method def self.validate(
+      code:,
+      first_name:,
+      last_name:,
+      type:,
+      country:,
+      bvn:,
+      bank_code:,
+      account_number:,
+      middle_name: nil,
+      value: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          "/customer/#{code}/identification",
+          {
+            first_name:,
+            last_name:,
+            type:,
+            country:,
+            bvn:,
+            bank_code:,
+            account_number:,
+            middle_name:,
+            value:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #initialize_authorization.
+    class InitializeAuthorizationResponse < PaystackGateway::Response
+      delegate :redirect_url, :access_code, :reference, to: :data
+    end
+
+    # Error response from #initialize_authorization.
+    class InitializeAuthorizationError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#initialize_authorization
+    # Initialize Authorization: POST /customer/authorization/initialize
+    # Initiate a request to create a reusable authorization code for recurring transactions
+    #
+    # @param email [String] (required)
+    #        Customer's email address
+    # @param channel ["direct_debit"] (required)
+    #        direct_debit is the only supported option for now
+    # @param callback_url [String]
+    #        Fully qualified url (e.g. https://example.com/) to redirect your customer to
+    # @param account [Hash]
+    #   @option account [String] :number
+    #           The customer's account number
+    #   @option account [String] :bank_code
+    #           The code representing the customer's bank
+    # @param address [Hash]
+    #   @option address [String] :street
+    #           The customer's street
+    #   @option address [String] :city
+    #           The customer's city
+    #   @option address [String] :state
+    #           The customer's state
+    #
+    # @return [InitializeAuthorizationResponse] successful response
+    # @raise [InitializeAuthorizationError] if the request fails
+    api_method def self.initialize_authorization(email:, channel:, callback_url: nil, account: nil, address: nil)
+      use_connection do |connection|
+        connection.post(
+          '/customer/authorization/initialize',
+          { email:, channel:, callback_url:, account:, address: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #verify_authorization.
+    class VerifyAuthorizationResponse < PaystackGateway::Response
+      delegate :authorization_code,
+               :channel,
+               :bank,
+               :active,
+               :customer, to: :data
+    end
+
+    # Error response from #verify_authorization.
+    class VerifyAuthorizationError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#verify_authorization
+    # Verify Authorization: GET /customer/authorization/verify/{reference}
+    # Check the status of an authorization request
+    #
+    # @param reference [String] (required)
+    #        The reference returned in the initialization response
+    #
+    # @return [VerifyAuthorizationResponse] successful response
+    # @raise [VerifyAuthorizationError] if the request fails
+    api_method def self.verify_authorization(reference:)
+      use_connection do |connection|
+        connection.get(
+          "/customer/authorization/verify/#{reference}",
+        )
+      end
+    end
+
+    # Successful response from calling #deactivate_authorization.
+    class DeactivateAuthorizationResponse < PaystackGateway::Response; end
+
+    # Error response from #deactivate_authorization.
+    class DeactivateAuthorizationError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#deactivate_authorization
+    # Deactivate Authorization: POST /customer/authorization/deactivate
+    # Deactivate an authorization for any payment channel.
+    #
+    # @param authorization_code [String] (required)
+    #        Authorization code to be deactivated
+    #
+    # @return [DeactivateAuthorizationResponse] successful response
+    # @raise [DeactivateAuthorizationError] if the request fails
+    api_method def self.deactivate_authorization(authorization_code:)
+      use_connection do |connection|
+        connection.post(
+          '/customer/authorization/deactivate',
+          { authorization_code: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #initialize_direct_debit.
+    class InitializeDirectDebitResponse < PaystackGateway::Response
+      delegate :redirect_url, :access_code, :reference, to: :data
+    end
+
+    # Error response from #initialize_direct_debit.
+    class InitializeDirectDebitError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#initialize_direct_debit
+    # Initialize Direct Debit: POST /customer/{id}/initialize-direct-debit
+    # Initialize the process of linking an account to a customer for Direct Debit transactions
+    #
+    # @param id [Integer] (required)
+    #        The ID of the customer to initialize the direct debit for
+    # @param account [Hash] (required)
+    #   @option account [String] :number
+    #           The customer's account number
+    #   @option account [String] :bank_code
+    #           The code representing the customer's bank
+    # @param address [Hash] (required)
+    #   @option address [String] :street
+    #           The customer's street
+    #   @option address [String] :city
+    #           The customer's city
+    #   @option address [String] :state
+    #           The customer's state
+    #
+    # @return [InitializeDirectDebitResponse] successful response
+    # @raise [InitializeDirectDebitError] if the request fails
+    api_method def self.initialize_direct_debit(id:, account:, address:)
+      use_connection do |connection|
+        connection.post(
+          "/customer/#{id}/initialize-direct-debit",
+          { account:, address: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #direct_debit_activation_charge.
+    class DirectDebitActivationChargeResponse < PaystackGateway::Response; end
+
+    # Error response from #direct_debit_activation_charge.
+    class DirectDebitActivationChargeError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#direct_debit_activation_charge
+    # Direct Debit Activation Charge: PUT /customer/{id}/directdebit-activation-charge
+    # Trigger an activation charge on an inactive mandate on behalf of your customer
+    #
+    # @param id [Integer] (required)
+    #        The customer ID attached to the authorization
+    # @param authorization_id [Integer] (required)
+    #        The authorization ID gotten from the initiation response
+    #
+    # @return [DirectDebitActivationChargeResponse] successful response
+    # @raise [DirectDebitActivationChargeError] if the request fails
+    api_method def self.direct_debit_activation_charge(id:, authorization_id:)
+      use_connection do |connection|
+        connection.put(
+          "/customer/#{id}/directdebit-activation-charge",
+          { authorization_id: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch_mandate_authorizations.
+    class FetchMandateAuthorizationsResponse < PaystackGateway::Response; end
+
+    # Error response from #fetch_mandate_authorizations.
+    class FetchMandateAuthorizationsError < ApiError; end
+
+    # https://paystack.com/docs/api/customer/#fetch_mandate_authorizations
+    # Fetch Mandate Authorizations: GET /customer/{id}/directdebit-mandate-authorizations
+    # Get the list of direct debit mandates associated with a customer
+    #
+    # @param id [Integer] (required)
+    #        The customer ID for the authorizations to fetch
+    #
+    # @return [FetchMandateAuthorizationsResponse] successful response
+    # @raise [FetchMandateAuthorizationsError] if the request fails
+    api_method def self.fetch_mandate_authorizations(id:)
+      use_connection do |connection|
+        connection.get(
+          "/customer/#{id}/directdebit-mandate-authorizations",
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/customers.rb

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