paystack_sdk 0.1.1 → 0.2.0

data/lib/paystack_sdk/resources/customers.rb

@@ -1,187 +1,308 @@
 # frozen_string_literal: true
 
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
+# Do not edit by hand: regenerate it with `bin/paystack-scaffold Customer`. Hand-written extras go in lib/paystack_sdk/resources/extensions/customers.rb.
+# scaffold-digest: a6f9d22c6371a27b341370a5137dda91fe7a082cd0a60f49cdfadd3789cc924d
+
 require_relative "base"
 
 module PaystackSdk
   module Resources
-    # The `Customers` class provides methods for interacting with the Paystack Customers API.
-    # It allows you to create, list, fetch, update, and manage customers on your integration.
-    #
-    # Example usage:
-    # ```ruby
-    #   customers = PaystackSdk::Resources::Customers.new(secret_key:)
-    #
-    #   # Create a customer
-    #   payload = { email: "customer@email.com", first_name: "Zero", last_name: "Sum" }
-    #   response = customers.create(payload)
-    #   if response.success?
-    #     puts "Customer created successfully."
-    #     puts "Customer code: #{response.customer_code}"
-    #   else
-    #     puts "Error creating customer: #{response.error_message}"
-    #   end
-    #
-    #   # List customers
-    #   response = customers.list(per_page: 50, page: 1)
-    #
-    #   # Fetch a customer
-    #   response = customers.fetch("CUS_xxxxx")
-    #
-    #   # Update a customer
-    #   response = customers.update("CUS_xxxxx", { first_name: "John" })
-    # ```
+    # Customer operations.
     class Customers < PaystackSdk::Resources::Base
-      # Creates a new customer.
-      #
-      # @param payload [Hash] The payload containing customer details.
-      # @option payload [String] :email (required) Customer's email address
-      # @option payload [String] :first_name Customer's first name
-      # @option payload [String] :last_name Customer's last name
-      # @option payload [String] :phone Customer's phone number
-      # @option payload [Hash] :metadata Additional customer information
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", per_page: "perPage"}.freeze
+
+      # List Customers.
+      #
+      # List customers on your integration
+      #
+      # @param use_cursor [Boolean] A flag to indicate if cursor based pagination should be used
+      # @param next_cursor [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 [String] The start date
+      # @param to [String] The end date
+      # @param per_page [Integer] The number of records to fetch per request
+      # @param page [Integer] The offset to retrieve data from
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the payload is invalid or the API request fails.
-      def create(payload)
-        validate_fields!(
-          payload: payload,
-          validations: {
-            email: {type: :email, required: true},
-            first_name: {type: :string, required: false},
-            last_name: {type: :string, required: false},
-            phone: {type: :string, required: false}
-          }
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#list
+      def list(
+        use_cursor: nil,
+        next_cursor: nil,
+        previous: nil,
+        from: nil,
+        to: nil,
+        per_page: nil,
+        page: nil
+      )
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+
+        wire_query = to_wire(
+          {
+            use_cursor:,
+            next_cursor:,
+            previous:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to"),
+            per_page:,
+            page:
+          },
+          WIRE_NAMES
         )
 
-        response = @connection.post("customer", payload)
-        handle_response(response)
+        handle_response(@connection.get("/customer", wire_query))
       end
 
-      # Lists all customers.
+      # Create Customer.
+      #
+      # Create a customer on your integration
       #
-      # @param per_page [Integer] Number of records per page (default: 50)
-      # @param page [Integer] Page number to retrieve (default: 1)
-      # @param from [String] Start date for filtering
-      # @param to [String] End date for filtering
+      # @param email [String] 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 [Hash] A set of key/value pairs that you can attach to the customer.
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the API request fails.
-      def list(per_page: 50, page: 1, **params)
-        validate_positive_integer!(value: per_page, name: "per_page", allow_nil: true)
-        validate_positive_integer!(value: page, name: "page", allow_nil: true)
-
-        validate_date_format!(date_str: params[:from], name: "from") if params[:from]
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#create
+      def create(email:, first_name: nil, last_name: nil, phone: nil, metadata: nil)
+        validate_presence!(value: email, name: "email")
+        validate_email!(email: email, name: "email")
 
-        validate_date_format!(date_str: params[:to], name: "to") if params[:to]
+        wire_body = to_wire({email:, first_name:, last_name:, phone:, metadata:}, WIRE_NAMES)
 
-        query_params = {perPage: per_page, page: page}.merge(params)
-        response = @connection.get("customer", query_params)
-        handle_response(response)
+        handle_response(@connection.post("/customer", wire_body))
       end
 
-      # Fetches details of a single customer by email or code.
+      # Fetch Customer.
       #
-      # @param email_or_code [String] Email or customer code
+      # Get details of a customer on your integration.
+      #
+      # @param email_or_code [String] The code for the customer gotten from the response of the customer creation
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the parameter is invalid or the API request fails.
-      def fetch(email_or_code)
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#fetch
+      def fetch(email_or_code:)
         validate_presence!(value: email_or_code, name: "email_or_code")
-        response = @connection.get("customer/#{email_or_code}")
-        handle_response(response)
+
+        handle_response(
+          @connection.get("/customer/#{escape_path(email_or_code, name: "email_or_code")}")
+        )
       end
 
-      # Updates a customer's details.
+      # Update Customer.
+      #
+      # Update a customer's details on your integration
       #
-      # @param code [String] Customer's code
-      # @param payload [Hash] The payload containing customer details to update
-      # @option payload [String] :first_name Customer's first name
-      # @option payload [String] :last_name Customer's last name
-      # @option payload [String] :phone Customer's phone number
-      # @option payload [Hash] :metadata Additional customer information
+      # @param code [String] 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 [Hash] A set of key/value pairs that you can attach to the customer.
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
-      def update(code, payload)
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#update
+      def update(code:, first_name: nil, last_name: nil, phone: nil, metadata: nil)
         validate_presence!(value: code, name: "code")
-        validate_hash!(input: payload, name: "payload")
 
-        response = @connection.put("customer/#{code}", payload)
-        handle_response(response)
+        wire_body = to_wire({first_name:, last_name:, phone:, metadata:}, WIRE_NAMES)
+
+        handle_response(@connection.put("/customer/#{escape_path(code, name: "code")}", wire_body))
+      end
+
+      # Set Risk Action.
+      #
+      # Set customer's risk action by whitelisting or blacklisting the customer
+      #
+      # @param customer [String] The customer code from the response of the customer creation
+      # @param risk_action [String] This determines the fraud rules that should be applied to the customer One of: allow, deny, default.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#whitelist-blacklist
+      def set_risk_action(customer:, risk_action: nil)
+        validate_presence!(value: customer, name: "customer")
+        validate_allowed_values!(
+          value: risk_action,
+          allowed_values: %w[allow deny default],
+          name: "risk_action"
+        )
+
+        wire_body = to_wire({customer:, risk_action:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/customer/set_risk_action", wire_body))
       end
 
-      # Validates a customer's identity.
-      #
-      # @param code [String] Customer's code
-      # @param payload [Hash] The payload containing validation details
-      # @option payload [String] :country (required) 2 letter country code
-      # @option payload [String] :type (required) Type of identification
-      # @option payload [String] :account_number Bank account number (required for bank_account type)
-      # @option payload [String] :bvn Bank Verification Number
-      # @option payload [String] :bank_code Bank code
-      # @option payload [String] :first_name Customer's first name
-      # @option payload [String] :last_name Customer's last name
+      # Validate Customer.
+      #
+      # Validate a customer's identity
+      #
+      # @param code [String] 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 type [String] Predefined types of identification.
+      # @param country [String] Two-letter country code of identification issuer
+      # @param bvn [String] Customer's Bank Verification Number
+      # @param bank_code [String] You can get the list of bank codes by calling the List Banks endpoint (https://api.paystack.co/bank).
+      # @param account_number [String] Customer's bank account number.
+      # @param middle_name [String] Customer's middle name
+      # @param value [String] Customer's identification number.
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
-      def validate(code, payload)
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#validate
+      def validate(
+        code:,
+        first_name:,
+        last_name:,
+        type:,
+        country:,
+        bvn:,
+        bank_code:,
+        account_number:,
+        middle_name: nil,
+        value: nil
+      )
         validate_presence!(value: code, name: "code")
-        validate_fields!(
-          payload: payload,
-          validations: {
-            country: {type: :string, required: true},
-            type: {type: :string, required: true},
-            account_number: {type: :string, required: true},
-            bank_code: {type: :string, required: true}
-          }
+        validate_presence!(value: first_name, name: "first_name")
+        validate_presence!(value: last_name, name: "last_name")
+        validate_presence!(value: type, name: "type")
+        validate_presence!(value: country, name: "country")
+        validate_presence!(value: bvn, name: "bvn")
+        validate_presence!(value: bank_code, name: "bank_code")
+        validate_presence!(value: account_number, name: "account_number")
+
+        wire_body = to_wire(
+          {
+            first_name:,
+            last_name:,
+            type:,
+            country:,
+            bvn:,
+            bank_code:,
+            account_number:,
+            middle_name:,
+            value:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(
+          @connection.post("/customer/#{escape_path(code, name: "code")}/identification", wire_body)
         )
+      end
+
+      # Initialize Authorization.
+      #
+      # Initiate a request to create a reusable authorization code for recurring transactions
+      #
+      # @param email [String] Customer's email address
+      # @param channel [String] direct_debit is the only supported option for now One of: direct_debit.
+      # @param callback_url [String] Fully qualified url (e.g.
+      # @param account [Hash]
+      # @param address [Hash]
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#initialize-authorization
+      def initialize_authorization(email:, channel:, callback_url: nil, account: nil, address: nil)
+        validate_presence!(value: email, name: "email")
+        validate_email!(email: email, name: "email")
+        validate_presence!(value: channel, name: "channel")
+        validate_allowed_values!(value: channel, allowed_values: %w[direct_debit], name: "channel")
 
-        response = @connection.post("customer/#{code}/identification", payload)
-        handle_response(response)
+        wire_body = to_wire({email:, channel:, callback_url:, account:, address:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/customer/authorization/initialize", wire_body))
       end
 
-      # Sets the risk action for a customer.
+      # Verify Authorization.
+      #
+      # Check the status of an authorization request
       #
-      # @param payload [Hash] The payload containing risk action details
-      # @option payload [String] :customer (required) Customer's code or email address
-      # @option payload [String] :risk_action (required) Risk action to set ('default', 'allow', or 'deny')
+      # @param reference [String] The reference returned in the initialization response
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::MissingParamError] If required parameters are missing
-      # @raise [PaystackSdk::InvalidValueError] If risk_action is not one of the allowed values
-      # @raise [PaystackSdk::APIError] If the API request fails.
-      #
-      # @example
-      # ```ruby
-      #   payload = { customer: "CUS_xxxxx", risk_action: "allow" }
-      #   response = customers.set_risk_action(payload)
-      #   if response.success?
-      #     puts "Risk action updated successfully"
-      #   end
-      # ```
-      def set_risk_action(payload)
-        validate_fields!(
-          payload: payload,
-          validations: {
-            customer: {type: :string, required: true},
-            risk_action: {type: :inclusion, required: true, allowed_values: %w[default allow deny]}
-          }
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#verify-authorization
+      def verify_authorization(reference:)
+        validate_presence!(value: reference, name: "reference")
+
+        handle_response(
+          @connection.get("/customer/authorization/verify/#{escape_path(reference, name: "reference")}")
         )
+      end
+
+      # Deactivate Authorization.
+      #
+      # Deactivate an authorization for any payment channel.
+      #
+      # @param authorization_code [String] Authorization code to be deactivated
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#deactivate-authorization
+      def deactivate_authorization(authorization_code:)
+        validate_presence!(value: authorization_code, name: "authorization_code")
+
+        wire_body = to_wire({authorization_code:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/customer/authorization/deactivate", wire_body))
+      end
+
+      # Initialize Direct Debit.
+      #
+      # Initialize the process of linking an account to a customer for Direct Debit transactions
+      #
+      # @param id [Integer] The ID of the customer to initialize the direct debit for
+      # @param account [Hash]
+      # @param address [Hash]
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#initialize-direct-debit
+      def initialize_direct_debit(id:, account:, address:)
+        validate_presence!(value: id, name: "id")
+        validate_presence!(value: account, name: "account")
+        validate_presence!(value: address, name: "address")
+
+        wire_body = to_wire({account:, address:}, WIRE_NAMES)
 
-        response = @connection.post("customer/set_risk_action", payload)
-        handle_response(response)
+        handle_response(
+          @connection.post("/customer/#{escape_path(id, name: "id")}/initialize-direct-debit", wire_body)
+        )
       end
 
-      # Deactivates a customer's authorization.
+      # Direct Debit Activation Charge.
+      #
+      # Trigger an activation charge on an inactive mandate on behalf of your customer
       #
-      # @param payload [Hash] The payload containing authorization details
-      # @option payload [String] :authorization_code (required) Authorization code to deactivate
+      # @param id [Integer] The customer ID attached to the authorization
+      # @param authorization_id [Integer] The authorization ID gotten from the initiation response
       # @return [PaystackSdk::Response] The response from the Paystack API.
-      # @raise [PaystackSdk::Error] If the parameters are invalid or the API request fails.
-      def deactivate_authorization(payload)
-        validate_fields!(
-          payload: payload,
-          validations: {
-            authorization_code: {type: :string, required: true}
-          }
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#direct-debit-activation-charge
+      def direct_debit_activation_charge(id:, authorization_id:)
+        validate_presence!(value: id, name: "id")
+        validate_presence!(value: authorization_id, name: "authorization_id")
+
+        wire_body = to_wire({authorization_id:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.put("/customer/#{escape_path(id, name: "id")}/directdebit-activation-charge", wire_body)
         )
+      end
 
-        response = @connection.post("customer/deactivate_authorization", payload)
-        handle_response(response)
+      # Fetch Mandate Authorizations.
+      #
+      # Get the list of direct debit mandates associated with a customer
+      #
+      # @param id [Integer] The customer ID for the authorizations to fetch
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/customer/#directdebit-mandate-authorizations
+      def fetch_mandate_authorizations(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(
+          @connection.get("/customer/#{escape_path(id, name: "id")}/directdebit-mandate-authorizations")
+        )
       end
     end
   end

data/lib/paystack_sdk/resources/extensions/charges.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PaystackSdk
+  module Resources
+    module Extensions
+      # Hand-written additions to {PaystackSdk::Resources::Charges}, which bin/paystack-scaffold
+      # generates from Paystack's OpenAPI spec and includes this module into.
+      module Charges
+        # The provider codes Paystack documents for the `mobile_money` object.
+        #
+        # @see https://paystack.com/docs/api/charge/#create
+        # @see https://paystack.com/docs/payments/payment-channels/#mobile-money
+        MOBILE_MONEY_PROVIDERS = %w[mtn atl vod mpesa orange wave mpesa_offline mptill].freeze
+
+        # Charges a mobile money wallet: a {#create} call with a checked `mobile_money` object.
+        #
+        # Mobile money is available to businesses in Ghana, Kenya and Côte d'Ivoire. The charge usually
+        # comes back with status `pay_offline` (the customer approves it on their phone; show them
+        # `display_text` and wait for the `charge.success` webhook) or `send_otp` (collect the OTP and
+        # call {#submit_otp}).
+        #
+        # @param email [String] Customer's email address
+        # @param amount [Integer] Amount in the subunit of the currency (pesewas, cents)
+        # @param mobile_money [Hash] The wallet to charge, with symbol or string keys:
+        #   `phone` (the customer's number) or, for M-PESA Till (`mptill`), `account` (the till number),
+        #   and `provider`, one of {MOBILE_MONEY_PROVIDERS} in any case (sent in lowercase).
+        # @param currency [String, nil] 3-letter currency code, e.g. GHS or KES; Paystack uses your
+        #   integration's currency when it is left out.
+        # @param reference [String, nil] Unique transaction reference
+        # @param metadata [Hash, nil] Custom data for your post-payment processes
+        # @return [PaystackSdk::Response] The response from the Paystack API.
+        # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+        # @see https://paystack.com/docs/payments/payment-channels/#mobile-money
+        def mobile_money(email:, amount:, mobile_money:, currency: nil, reference: nil, metadata: nil)
+          wallet = checked_mobile_money(mobile_money)
+          validate_currency!(currency: currency, name: "currency")
+
+          create(email:, amount:, currency:, reference:, metadata:, mobile_money: wallet)
+        end
+
+        private
+
+        # Checks the `mobile_money` object and returns a copy with symbol keys and a lowercase provider.
+        # The caller's hash is never changed.
+        def checked_mobile_money(details)
+          validate_presence!(value: details, name: "mobile_money")
+          validate_hash!(input: details, name: "mobile_money")
+
+          wallet = details.transform_keys(&:to_sym)
+          validate_presence!(value: wallet[:phone] || wallet[:account], name: "mobile_money phone (or account)")
+
+          provider = wallet[:provider]&.to_s&.downcase
+          validate_allowed_values!(
+            value: provider,
+            allowed_values: MOBILE_MONEY_PROVIDERS,
+            name: "mobile_money provider",
+            allow_nil: false
+          )
+
+          wallet.merge(provider: provider)
+        end
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/miscellaneous.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
+# Do not edit by hand: regenerate it with `bin/paystack-scaffold Miscellaneous`. Hand-written extras go in lib/paystack_sdk/resources/extensions/miscellaneous.rb.
+# scaffold-digest: 8e7d4c28f7e3c3f3baf040728f045e40db76fde00fb4b14a38b64ea234035f27
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Miscellaneous operations.
+    class Miscellaneous < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {}.freeze
+
+      # Resolve Card BIN.
+      #
+      # Get the details of a card BIN
+      #
+      # @param bin [String] The card bank identification number
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/verification/#resolve-card
+      def resolve_card_bin(bin:)
+        validate_presence!(value: bin, name: "bin")
+
+        handle_response(@connection.get("/decision/bin/#{escape_path(bin, name: "bin")}"))
+      end
+
+      # List Countries.
+      #
+      # List all supported countries on Paystack
+      #
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/miscellaneous/#country
+      def list_countries
+        handle_response(@connection.get("/country"))
+      end
+
+      # List States (AVS).
+      #
+      # Get a list of states for a country for address verification
+      #
+      # @param country [String] The country code of the states to list.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/miscellaneous/#avs-states
+      def list_states(country:)
+        validate_presence!(value: country, name: "country")
+
+        wire_query = to_wire({country:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/address_verification/states", wire_query))
+      end
+    end
+  end
+end