paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/order.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/order
+  #
+  # Orders
+  # A collection of endpoints for creating and managing orders
+  module Order
+    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/order/#list
+    # List Orders: GET /order
+    # 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 [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(per_page: nil, page: nil, from: nil, to: nil)
+      use_connection do |connection|
+        connection.get(
+          '/order',
+          { perPage: per_page, page:, from:, to: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :discounts,
+               :currency,
+               :shipping_address,
+               :integration,
+               :domain,
+               :email,
+               :customer,
+               :amount,
+               :pay_for_me,
+               :shipping,
+               :shipping_fees,
+               :metadata,
+               :order_code,
+               :refunded,
+               :is_viewed,
+               :expiration_date,
+               :id,
+               :createdAt,
+               :updatedAt,
+               :items,
+               :pay_for_me_code,
+               :discount_amount, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/order/#create
+    # Create Order: POST /order
+    # Create an order for selected items
+    #
+    # @param email [String] (required)
+    #        The email of the customer placing the order
+    # @param first_name [String] (required)
+    #        The customer's first name
+    # @param last_name [String] (required)
+    #        The customer's last name
+    # @param phone [String] (required)
+    #        The customer's mobile number
+    # @param currency ["GHS", "KES", "NGN", "USD", "ZAR"] (required)
+    #        Currency in which amount is set
+    # @param items [Array<Hash>] (required)
+    #        The collection of items that make up the order
+    # @param shipping [Hash] (required)
+    #        The shipping details of the order
+    #   @option shipping [String] :street_line
+    #           The address of for the delivery
+    #   @option shipping [String] :city
+    #           The city of the delivery address
+    #   @option shipping [String] :state
+    #           The state of the delivery address
+    #   @option shipping [String] :country
+    #           The country of the delivery address
+    #   @option shipping [Integer] :shipping_fee
+    #           The cost of delivery
+    #   @option shipping [String] :delivery_note
+    #           Extra details to be aware of for the delivery
+    # @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 [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(
+      email:,
+      first_name:,
+      last_name:,
+      phone:,
+      currency:,
+      items:,
+      shipping:,
+      is_gift: nil,
+      pay_for_me: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/order',
+          {
+            email:,
+            first_name:,
+            last_name:,
+            phone:,
+            currency:,
+            items:,
+            shipping:,
+            is_gift:,
+            pay_for_me:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :discounts,
+               :order_code,
+               :domain,
+               :currency,
+               :amount,
+               :email,
+               :refunded,
+               :paid_at,
+               :shipping_address,
+               :metadata,
+               :shipping_fees,
+               :shipping_method,
+               :is_viewed,
+               :expiration_date,
+               :pay_for_me,
+               :id,
+               :integration,
+               :page,
+               :customer,
+               :shipping,
+               :createdAt,
+               :updatedAt,
+               :transaction,
+               :is_gift,
+               :payer,
+               :fully_refunded,
+               :refunded_amount,
+               :items,
+               :discount_amount, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/order/#fetch
+    # Fetch Order: GET /order/{id}
+    # Fetch the details of a previously created order
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the order
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(id:)
+      use_connection do |connection|
+        connection.get(
+          "/order/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #product.
+    class ProductResponse < PaystackGateway::Response; end
+
+    # Error response from #product.
+    class ProductError < ApiError; end
+
+    # https://paystack.com/docs/api/order/#product
+    # Fetch Product Orders: GET /order/product/{id}
+    # Fetch all orders for a particular product
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of the order
+    #
+    # @return [ProductResponse] successful response
+    # @raise [ProductError] if the request fails
+    api_method def self.product(id:)
+      use_connection do |connection|
+        connection.get(
+          "/order/product/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #validate.
+    class ValidateResponse < PaystackGateway::Response
+      delegate :order_code,
+               :domain,
+               :currency,
+               :amount,
+               :email,
+               :refunded,
+               :paid_at,
+               :shipping_address,
+               :metadata,
+               :shipping_fees,
+               :shipping_method,
+               :is_viewed,
+               :expiration_date,
+               :pay_for_me,
+               :id,
+               :integration,
+               :transaction,
+               :page,
+               :customer,
+               :shipping,
+               :createdAt,
+               :updatedAt,
+               :payer, to: :data
+    end
+
+    # Error response from #validate.
+    class ValidateError < ApiError; end
+
+    # https://paystack.com/docs/api/order/#validate
+    # Validate Order: GET /order/{code}/validate
+    # Validate a pay for me order
+    #
+    # @param code [String] (required)
+    #        The unique code of a previously created order
+    #
+    # @return [ValidateResponse] successful response
+    # @raise [ValidateError] if the request fails
+    api_method def self.validate(code:)
+      use_connection do |connection|
+        connection.get(
+          "/order/#{code}/validate",
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/page.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/page
+  #
+  # Payment Pages
+  # A collection of endpoints for creating and managing links for the collection of payment for products
+  module Page
+    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/page/#list
+    # List Pages: GET /page
+    # 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 [Time]
+    #        The start date
+    # @param to [Time]
+    #        The end date
+    #
+    # @return [ListResponse] successful response
+    # @raise [ListError] if the request fails
+    api_method def self.list(per_page: nil, page: nil, from: nil, to: nil)
+      use_connection do |connection|
+        connection.get(
+          '/page',
+          { perPage: per_page, page:, from:, to: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :name,
+               :integration,
+               :domain,
+               :slug,
+               :currency,
+               :type,
+               :collect_phone,
+               :active,
+               :published,
+               :migrate,
+               :id,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/page/#create
+    # Create Page: POST /page
+    # Create a webpage to receive payments
+    #
+    # @param name [String] (required)
+    #        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 ["NGN", "GHS", "ZAR", "KES", "USD"]
+    #        The transaction currency. Defaults to your integration currency.
+    # @param slug [String]
+    #        URL slug you would like to be associated with this page. Page will be accessible
+    #        at `https://paystack.com/pay/[slug]`
+    # @param type ["payment", "subscription", "product", "plan"]
+    #        The type of payment page to create. Defaults to `payment` if no type is specified.
+    # @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. If true, `amount`
+    #        must be passed.
+    # @param split_code [String]
+    #        The split code of the transaction split. e.g. `SPL_98WF13Eb3w`
+    # @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<Hash>]
+    #        If you would like to accept custom fields, specify them here.
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.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
+    )
+      use_connection do |connection|
+        connection.post(
+          '/page',
+          {
+            name:,
+            description:,
+            amount:,
+            currency:,
+            slug:,
+            type:,
+            plan:,
+            fixed_amount:,
+            split_code:,
+            metadata:,
+            redirect_url:,
+            success_message:,
+            notification_email:,
+            collect_phone:,
+            custom_fields:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :integration,
+               :domain,
+               :name,
+               :description,
+               :amount,
+               :currency,
+               :slug,
+               :custom_fields,
+               :type,
+               :redirect_url,
+               :success_message,
+               :collect_phone,
+               :active,
+               :published,
+               :migrate,
+               :notification_email,
+               :metadata,
+               :split_code,
+               :id,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/page/#fetch
+    # Fetch Page: GET /page/{id}
+    # Get a previously created payment page
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a payment page
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(id:)
+      use_connection do |connection|
+        connection.get(
+          "/page/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response
+      delegate :domain,
+               :name,
+               :description,
+               :amount,
+               :currency,
+               :slug,
+               :custom_fields,
+               :type,
+               :redirect_url,
+               :success_message,
+               :collect_phone,
+               :active,
+               :published,
+               :migrate,
+               :notification_email,
+               :metadata,
+               :split_code,
+               :id,
+               :integration,
+               :plan,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/page/#update
+    # Update Page: PUT /page/{id}
+    # Update a previously created payment page
+    #
+    # @param id [Integer] (required)
+    #        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 [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(id:, name: nil, description: nil, amount: nil, active: nil)
+      use_connection do |connection|
+        connection.put(
+          "/page/#{id}",
+          { name:, description:, amount:, active: }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #check_slug_availability.
+    class CheckSlugAvailabilityResponse < PaystackGateway::Response; end
+
+    # Error response from #check_slug_availability.
+    class CheckSlugAvailabilityError < ApiError; end
+
+    # https://paystack.com/docs/api/page/#check_slug_availability
+    # Check Slug Availability: GET /page/check_slug_availability/{slug}
+    # Check if a custom slug is available for use when creating a payment page
+    #
+    # @param slug [String] (required)
+    #        The custom slug to check
+    #
+    # @return [CheckSlugAvailabilityResponse] successful response
+    # @raise [CheckSlugAvailabilityError] if the request fails
+    api_method def self.check_slug_availability(slug:)
+      use_connection do |connection|
+        connection.get(
+          "/page/check_slug_availability/#{slug}",
+        )
+      end
+    end
+
+    # Successful response from calling #add_products.
+    class AddProductsResponse < PaystackGateway::Response
+      delegate :integration,
+               :plan,
+               :domain,
+               :name,
+               :description,
+               :amount,
+               :currency,
+               :slug,
+               :custom_fields,
+               :type,
+               :redirect_url,
+               :success_message,
+               :collect_phone,
+               :active,
+               :published,
+               :migrate,
+               :notification_email,
+               :metadata,
+               :split_code,
+               :id,
+               :createdAt,
+               :updatedAt,
+               :products, to: :data
+    end
+
+    # Error response from #add_products.
+    class AddProductsError < ApiError; end
+
+    # https://paystack.com/docs/api/page/#add_products
+    # Add Products: POST /page/{id}/product
+    # Add products to a previously created payment page. You can only add products to
+    # pages that was created with a `product` type.
+    #
+    # @param id [String] (required)
+    # @param products [Array<Integer>] (required)
+    #        A list of IDs of products to add to a page.
+    #
+    # @return [AddProductsResponse] successful response
+    # @raise [AddProductsError] if the request fails
+    api_method def self.add_products(id:, products:)
+      use_connection do |connection|
+        connection.post(
+          "/page/#{id}/product",
+          { products: }.compact,
+        )
+      end
+    end
+  end
+end