paystack_sdk 0.3.0 → 0.4.0

data/lib/paystack_sdk/resources/bulk_charges.rb

@@ -0,0 +1,131 @@
+# 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 Bulk Charge`. Hand-written extras go in lib/paystack_sdk/resources/extensions/bulk_charges.rb.
+# scaffold-digest: 37ac5fa2bfe1cd33e4f7ea6bb85671348dea9151f67bf30475dc69262c2ffbb9
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Bulk Charge operations.
+    class BulkCharges < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {per_page: "perPage"}.freeze
+
+      # List Bulk Charge Batches.
+      #
+      # 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 [String] Filter by the status of the charges One of: active, paused, complete.
+      # @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/bulk-charge/#list
+      def list_batches(per_page: nil, page: nil, status: nil)
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[active paused complete],
+          name: "status"
+        )
+
+        wire_query = to_wire({per_page:, page:, status:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/bulkcharge", wire_query))
+      end
+
+      # Initiate Bulk Charge.
+      #
+      # Charge multiple customers in batches
+      #
+      # @param charges [Array] The request body: an array of hashes, each with authorization, amount, and optionally reference, attempt_partial_debit, at_least, metadata
+      # @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/bulk-charge/#initiate
+      def initiate(charges:)
+        validate_presence!(value: charges, name: "charges")
+
+        handle_response(@connection.post("/bulkcharge", charges))
+      end
+
+      # Fetch Bulk Charge Batch.
+      #
+      # This endpoint retrieves a specific batch code.
+      #
+      # @param id_or_code [String] The code for the charge whose batches you want to retrieve
+      # @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/bulk-charge/#fetch-batch
+      def fetch_batch(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(
+          @connection.get("/bulkcharge/#{escape_path(id_or_code, name: "id_or_code")}")
+        )
+      end
+
+      # List Charges in a Batch.
+      #
+      # This endpoint retrieves the charges associated with a specified batch code
+      #
+      # @param id_or_code [String] 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 [String] Filter by the status of the charges One of: success, failed, pending, error, inactive_authorization.
+      # @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/bulk-charge/#fetch-charge
+      def fetch_charges(id_or_code:, per_page: nil, page: nil, status: nil)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[success failed pending error inactive_authorization],
+          name: "status"
+        )
+
+        wire_query = to_wire({per_page:, page:, status:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.get("/bulkcharge/#{escape_path(id_or_code, name: "id_or_code")}/charges", wire_query)
+        )
+      end
+
+      # Pause Bulk Charge Batch.
+      #
+      # Pause the processing of a charge batch
+      #
+      # @param batch_code [String] The batch code for the bulk charge you want to pause
+      # @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/bulk-charge/#pause
+      def pause_batch(batch_code:)
+        validate_presence!(value: batch_code, name: "batch_code")
+
+        handle_response(
+          @connection.get("/bulkcharge/pause/#{escape_path(batch_code, name: "batch_code")}")
+        )
+      end
+
+      # Resume Bulk Charge Batch.
+      #
+      # Resume the processing of a previously paused charge batch
+      #
+      # @param batch_code [String] The batch code for the bulk charge you want to pause
+      # @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/bulk-charge/#resume
+      def resume_batch(batch_code:)
+        validate_presence!(value: batch_code, name: "batch_code")
+
+        handle_response(
+          @connection.get("/bulkcharge/resume/#{escape_path(batch_code, name: "batch_code")}")
+        )
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/direct_debits.rb

@@ -0,0 +1,61 @@
+# 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 Direct Debit`. Hand-written extras go in lib/paystack_sdk/resources/extensions/direct_debits.rb.
+# scaffold-digest: 481405483446315741944cfcc9fecdadc3da399105e39d724083c79c03e6a510
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Direct Debit operations.
+    class DirectDebits < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {}.freeze
+
+      # Trigger Activation Charge.
+      #
+      # Trigger activation charge for specified customers
+      #
+      # @param customer_ids [Array] Array of customer IDs to trigger activation charge for
+      # @note Charges the bank accounts behind the given customers' pending mandates to activate
+      #   them; in live mode this moves real money. It was not called against the test API while
+      #   this method was built, so its behaviour is documented, not verified. For one customer's
+      #   inactive mandate, `customers.direct_debit_activation_charge` takes an `authorization_id`
+      #   instead.
+      # @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/directdebit/#activation-charge
+      def trigger_activation_charge(customer_ids:)
+        validate_presence!(value: customer_ids, name: "customer_ids")
+
+        wire_body = to_wire({customer_ids:}, WIRE_NAMES)
+
+        handle_response(@connection.put("/directdebit/activation-charge", wire_body))
+      end
+
+      # List Mandate Authorizations.
+      #
+      # Get a list of all the direct debit mandates on your integration
+      #
+      # @param cursor [String] The cursor value of the next set of authorizations to fetch.
+      # @param status [String] Filter by the authorization status One of: pending, active, revoked.
+      # @param per_page [Integer] The number of authorizations to fetch per request
+      # @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/directdebit/#mandate-authorizations
+      def list_mandate_authorizations(cursor: nil, status: nil, per_page: nil)
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[pending active revoked],
+          name: "status"
+        )
+        validate_positive_integer!(value: per_page, name: "per_page")
+
+        wire_query = to_wire({cursor:, status:, per_page:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/directdebit/mandate-authorizations", wire_query))
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/integrations.rb

@@ -0,0 +1,48 @@
+# 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 Integration`. Hand-written extras go in lib/paystack_sdk/resources/extensions/integrations.rb.
+# scaffold-digest: c66a97cf4f3ad0acac37d43be91b77b75dbe9756c9a950a6ade38570bcff1155
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Integration operations.
+    class Integrations < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {}.freeze
+
+      # Fetch Payment Session Timeout.
+      #
+      # Fetch the session timeout of a transaction
+      #
+      # @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/integration/#fetch-timeout
+      def fetch_payment_session_timeout
+        handle_response(@connection.get("/integration/payment_session_timeout"))
+      end
+
+      # Update Payment Session Timeout.
+      #
+      # Update the session timeout of a transaction
+      #
+      # @param timeout [Integer] Time in seconds before a transaction becomes invalid
+      # @note Changes the payment session timeout of the whole integration (account-wide), and the
+      #   setting may be shared with LIVE mode even when you call it with a test key (sk_test_). It
+      #   has not been verified against the live API. Read the current value with
+      #   `fetch_payment_session_timeout` first, and do not call this to try the API out.
+      # @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/integration/#update-timeout
+      def update_payment_session_timeout(timeout:)
+        validate_presence!(value: timeout, name: "timeout")
+
+        wire_body = to_wire({timeout:}, WIRE_NAMES)
+
+        handle_response(@connection.put("/integration/payment_session_timeout", wire_body))
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/orders.rb

@@ -0,0 +1,146 @@
+# 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 Order`. Hand-written extras go in lib/paystack_sdk/resources/extensions/orders.rb.
+# scaffold-digest: 5f9842687d96069840a503e158175f928f772920f8a52ddf21c682e186ede2fb
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Order operations.
+    class Orders < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {per_page: "perPage"}.freeze
+
+      # List Orders.
+      #
+      # List the previously created orders
+      #
+      # @param per_page [Integer] Number of records to fetch per page
+      # @param page [Integer] The section to retrieve
+      # @param from [String] The start date
+      # @param to [String] The end date
+      # @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/order/#list
+      def list(per_page: nil, page: nil, from: nil, to: nil)
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+
+        wire_query = to_wire(
+          {
+            per_page:,
+            page:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to")
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/order", wire_query))
+      end
+
+      # Create Order.
+      #
+      # Create an order for selected items
+      #
+      # @param email [String] The email of the customer placing the order
+      # @param first_name [String] The customer's first name
+      # @param last_name [String] The customer's last name
+      # @param phone [String] The customer's mobile number
+      # @param currency [String] Currency in which amount is set One of: GHS, KES, NGN, USD, ZAR.
+      # @param items [Array]
+      # @param shipping [Hash] The shipping details of the order
+      # @param is_gift [Boolean] A flag to indicate if the order is for someone else
+      # @param pay_for_me [Boolean] A flag to indicate if the someone else should pay for the order
+      # @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/order/#create
+      def create(
+        email:,
+        first_name:,
+        last_name:,
+        phone:,
+        currency:,
+        items:,
+        shipping:,
+        is_gift: nil,
+        pay_for_me: nil
+      )
+        validate_presence!(value: email, name: "email")
+        validate_email!(email: email, name: "email")
+        validate_presence!(value: first_name, name: "first_name")
+        validate_presence!(value: last_name, name: "last_name")
+        validate_presence!(value: phone, name: "phone")
+        validate_presence!(value: currency, name: "currency")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[GHS KES NGN USD ZAR],
+          name: "currency"
+        )
+        validate_presence!(value: items, name: "items")
+        validate_presence!(value: shipping, name: "shipping")
+
+        wire_body = to_wire(
+          {
+            email:,
+            first_name:,
+            last_name:,
+            phone:,
+            currency:,
+            items:,
+            shipping:,
+            is_gift:,
+            pay_for_me:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/order", wire_body))
+      end
+
+      # Fetch Order.
+      #
+      # Fetch the details of a previously created order
+      #
+      # @param id [Integer] The unique identifier of the order
+      # @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/order/#fetch
+      def fetch(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(@connection.get("/order/#{escape_path(id, name: "id")}"))
+      end
+
+      # Fetch Product Orders.
+      #
+      # Fetch all orders for a particular product
+      #
+      # @param id [Integer] The unique identifier of the order
+      # @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/order/#fetch-product-orders
+      def fetch_product_orders(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(@connection.get("/order/product/#{escape_path(id, name: "id")}"))
+      end
+
+      # Validate Order.
+      #
+      # Validate a pay for me order
+      #
+      # @param code [String] The unique code of a previously created order
+      # @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/order/#validate
+      def validate(code:)
+        validate_presence!(value: code, name: "code")
+
+        handle_response(@connection.get("/order/#{escape_path(code, name: "code")}/validate"))
+      end
+    end
+  end
+end

data/lib/paystack_sdk/resources/pages.rb

@@ -0,0 +1,192 @@
+# 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 Page`. Hand-written extras go in lib/paystack_sdk/resources/extensions/pages.rb.
+# scaffold-digest: f15b7bfc076c2ac6bb204df7507b0749dc9129df3b73b6317943835374ffb891
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Page operations.
+    class Pages < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {per_page: "perPage"}.freeze
+
+      # List Pages.
+      #
+      # List all previously created payment pages
+      #
+      # @param per_page [Integer] Number of records to fetch per page
+      # @param page [Integer] The section to retrieve
+      # @param from [String] The start date
+      # @param to [String] The end date
+      # @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/page/#list
+      def list(per_page: nil, page: nil, from: nil, to: nil)
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+
+        wire_query = to_wire(
+          {
+            per_page:,
+            page:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to")
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/page", wire_query))
+      end
+
+      # Create Page.
+      #
+      # Create a webpage to receive payments
+      #
+      # @param name [String] Name of page
+      # @param description [String] The description of the page
+      # @param amount [Integer] Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
+      # @param currency [String] The transaction currency. One of: NGN, GHS, ZAR, KES, USD.
+      # @param slug [String] URL slug you would like to be associated with this page.
+      # @param type [String] The type of payment page to create. One of: payment, subscription, product, plan.
+      # @param plan [String] The ID of the plan to subscribe customers on this payment page to when `type` is set to `subscription`.
+      # @param fixed_amount [Boolean] Specifies whether to collect a fixed amount on the payment page.
+      # @param split_code [String] The split code of the transaction split.
+      # @param metadata [Hash] JSON object of custom data
+      # @param redirect_url [String] If you would like Paystack to redirect to a URL upon successful payment, specify the URL here.
+      # @param success_message [String] A success message to display to the customer after a successful transaction
+      # @param notification_email [String] An email address that will receive transaction notifications for this payment page
+      # @param collect_phone [Boolean] Specify whether to collect phone numbers on the payment page
+      # @param custom_fields [Array] If you would like to accept custom fields, specify them here.
+      # @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/page/#create
+      def create(
+        name:,
+        description: nil,
+        amount: nil,
+        currency: nil,
+        slug: nil,
+        type: nil,
+        plan: nil,
+        fixed_amount: nil,
+        split_code: nil,
+        metadata: nil,
+        redirect_url: nil,
+        success_message: nil,
+        notification_email: nil,
+        collect_phone: nil,
+        custom_fields: nil
+      )
+        validate_presence!(value: name, name: "name")
+        validate_positive_integer!(value: amount, name: "amount")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[NGN GHS ZAR KES USD],
+          name: "currency"
+        )
+        validate_allowed_values!(
+          value: type,
+          allowed_values: %w[payment subscription product plan],
+          name: "type"
+        )
+
+        wire_body = to_wire(
+          {
+            name:,
+            description:,
+            amount:,
+            currency:,
+            slug:,
+            type:,
+            plan:,
+            fixed_amount:,
+            split_code:,
+            metadata:,
+            redirect_url:,
+            success_message:,
+            notification_email:,
+            collect_phone:,
+            custom_fields:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/page", wire_body))
+      end
+
+      # Fetch Page.
+      #
+      # Get a previously created payment page
+      #
+      # @param id_or_slug [String] The unique identifier of a payment page
+      # @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/page/#fetch
+      def fetch(id_or_slug:)
+        validate_presence!(value: id_or_slug, name: "id_or_slug")
+
+        handle_response(@connection.get("/page/#{escape_path(id_or_slug, name: "id_or_slug")}"))
+      end
+
+      # Update Page.
+      #
+      # Update a previously created payment page
+      #
+      # @param id_or_slug [String] The unique identifier of a payment page
+      # @param name [String] Name of page
+      # @param description [String] The description of the page
+      # @param amount [Integer] Amount should be in the subunit of the currency
+      # @param active [Boolean] Set to false to deactivate page url
+      # @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/page/#update
+      def update(id_or_slug:, name: nil, description: nil, amount: nil, active: nil)
+        validate_presence!(value: id_or_slug, name: "id_or_slug")
+        validate_positive_integer!(value: amount, name: "amount")
+
+        wire_body = to_wire({name:, description:, amount:, active:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.put("/page/#{escape_path(id_or_slug, name: "id_or_slug")}", wire_body)
+        )
+      end
+
+      # Check Slug Availability.
+      #
+      # Check if a custom slug is available for use when creating a payment page
+      #
+      # @param slug [String] The custom slug to check
+      # @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/page/#check-slug
+      def check_slug_availability(slug:)
+        validate_presence!(value: slug, name: "slug")
+
+        handle_response(
+          @connection.get("/page/check_slug_availability/#{escape_path(slug, name: "slug")}")
+        )
+      end
+
+      # Add Products.
+      #
+      # Add products to a previously created payment page.
+      #
+      # @param id [Integer]
+      # @param products [Array] A list of IDs of products to add to a page.
+      # @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/page/#add-products
+      def add_products(id:, products:)
+        validate_presence!(value: id, name: "id")
+        validate_presence!(value: products, name: "products")
+
+        wire_body = to_wire({products:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/page/#{escape_path(id, name: "id")}/product", wire_body))
+      end
+    end
+  end
+end