paystack-gateway 0.1.1 → 0.2.0

data/lib/paystack_gateway/payment_request.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/paymentrequest
+  #
+  # Payment Requests
+  # A collection of endpoints for managing invoices for the payment of goods and services
+  module PaymentRequest
+    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/payment-request/#list
+    # List Payment Request: GET /paymentrequest
+    # List all previously created payment requests to your customers
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The section to retrieve
+    # @param customer [String]
+    #        Customer ID
+    # @param status ["draft", "pending", "success", "failed"]
+    #        Invoice status to filter
+    # @param currency [String]
+    #        If your integration supports more than one currency, choose the one to filter
+    # @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,
+      customer: nil,
+      status: nil,
+      currency: nil,
+      from: nil,
+      to: nil
+    )
+      use_connection do |connection|
+        connection.get(
+          '/paymentrequest',
+          {
+            perPage: per_page,
+            page:,
+            customer:,
+            status:,
+            currency:,
+            from:,
+            to:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :id,
+               :integration,
+               :domain,
+               :amount,
+               :currency,
+               :due_date,
+               :has_invoice,
+               :invoice_number,
+               :description,
+               :line_items,
+               :tax,
+               :request_code,
+               :paid,
+               :metadata,
+               :notifications,
+               :offline_reference,
+               :customer,
+               :created_at,
+               :discount,
+               :split_code, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#create
+    # Create Payment Request: POST /paymentrequest
+    # Create a new payment request by issuing an invoice to a customer
+    #
+    # @param customer [String] (required)
+    #        Customer id or code
+    # @param amount [Integer] (required)
+    #        Payment request amount. Only useful if line items and tax values are ignored. The
+    #        endpoint will throw a friendly warning if neither is available.
+    # @param currency [String]
+    #        Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults
+    #        to NGN
+    # @param due_date [Time]
+    #        ISO 8601 representation of request due date
+    # @param description [String]
+    #        A short description of the payment request
+    # @param line_items [Array<Hash>]
+    #        Array of line items
+    # @param tax [Array<Hash>]
+    #        Array of taxes
+    # @param send_notification [Boolean]
+    #        Indicates whether Paystack sends an email notification to customer. Defaults to
+    #        true
+    # @param draft [Boolean]
+    #        Indicate if request should be saved as draft. Defaults to false and overrides send_notification
+    # @param has_invoice [Boolean]
+    #        Set to true to create a draft invoice (adds an auto incrementing invoice number
+    #        if none is provided) even if there are no line_items or tax passed
+    # @param invoice_number [Integer]
+    #        Numeric value of invoice. Invoice will start from 1 and auto increment from there.
+    #        This field is to help override whatever value Paystack decides. Auto increment for
+    #        subsequent invoices continue from this point.
+    # @param split_code [String]
+    #        The split code of the transaction split.
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(
+      customer:,
+      amount:,
+      currency: nil,
+      due_date: nil,
+      description: nil,
+      line_items: nil,
+      tax: nil,
+      send_notification: nil,
+      draft: nil,
+      has_invoice: nil,
+      invoice_number: nil,
+      split_code: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/paymentrequest',
+          {
+            customer:,
+            amount:,
+            currency:,
+            due_date:,
+            description:,
+            line_items:,
+            tax:,
+            send_notification:,
+            draft:,
+            has_invoice:,
+            invoice_number:,
+            split_code:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response; end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#fetch
+    # Fetch Payment Request: GET /paymentrequest/{id}
+    # Fetch a previously created payment request
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a previously created payment request
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(id:)
+      use_connection do |connection|
+        connection.get(
+          "/paymentrequest/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response
+      delegate :id,
+               :integration,
+               :domain,
+               :amount,
+               :currency,
+               :due_date,
+               :has_invoice,
+               :invoice_number,
+               :description,
+               :pdf_url,
+               :line_items,
+               :tax,
+               :request_code,
+               :paid,
+               :paid_at,
+               :metadata,
+               :notifications,
+               :offline_reference,
+               :customer,
+               :created_at,
+               :discount,
+               :split_code, to: :data
+    end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#update
+    # Update Payment Request: PUT /paymentrequest/{id}
+    # Update a previously created payment request
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a previously created payment request
+    # @param customer [String]
+    #        Customer id or code
+    # @param amount [Integer]
+    #        Payment request amount. Only useful if line items and tax values are ignored. The
+    #        endpoint will throw a friendly warning if neither is available.
+    # @param currency [String]
+    #        Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults
+    #        to NGN
+    # @param due_date [Time]
+    #        ISO 8601 representation of request due date
+    # @param description [String]
+    #        A short description of the payment request
+    # @param line_items [Array<Hash>]
+    #        Array of line items
+    # @param tax [Array<Hash>]
+    #        Array of taxes
+    # @param send_notification [Boolean]
+    #        Indicates whether Paystack sends an email notification to customer. Defaults to
+    #        true
+    # @param draft [Boolean]
+    #        Indicate if request should be saved as draft. Defaults to false and overrides send_notification
+    # @param has_invoice [Boolean]
+    #        Set to true to create a draft invoice (adds an auto incrementing invoice number
+    #        if none is provided) even if there are no line_items or tax passed
+    # @param invoice_number [Integer]
+    #        Numeric value of invoice. Invoice will start from 1 and auto increment from there.
+    #        This field is to help override whatever value Paystack decides. Auto increment for
+    #        subsequent invoices continue from this point.
+    # @param split_code [String]
+    #        The split code of the transaction split.
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(
+      id:,
+      customer: nil,
+      amount: nil,
+      currency: nil,
+      due_date: nil,
+      description: nil,
+      line_items: nil,
+      tax: nil,
+      send_notification: nil,
+      draft: nil,
+      has_invoice: nil,
+      invoice_number: nil,
+      split_code: nil
+    )
+      use_connection do |connection|
+        connection.put(
+          "/paymentrequest/#{id}",
+          {
+            customer:,
+            amount:,
+            currency:,
+            due_date:,
+            description:,
+            line_items:,
+            tax:,
+            send_notification:,
+            draft:,
+            has_invoice:,
+            invoice_number:,
+            split_code:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #verify.
+    class VerifyResponse < PaystackGateway::Response
+      delegate :id,
+               :integration,
+               :domain,
+               :amount,
+               :currency,
+               :due_date,
+               :has_invoice,
+               :invoice_number,
+               :description,
+               :pdf_url,
+               :line_items,
+               :tax,
+               :request_code,
+               :paid,
+               :paid_at,
+               :metadata,
+               :notifications,
+               :offline_reference,
+               :customer,
+               :created_at,
+               :discount,
+               :split_code,
+               :pending_amount, to: :data
+    end
+
+    # Error response from #verify.
+    class VerifyError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#verify
+    # Verify Payment Request: GET /paymentrequest/verify/{id}
+    # Verify the status of a previously created payment request
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a previously created payment request
+    #
+    # @return [VerifyResponse] successful response
+    # @raise [VerifyError] if the request fails
+    api_method def self.verify(id:)
+      use_connection do |connection|
+        connection.get(
+          "/paymentrequest/verify/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #notify.
+    class NotifyResponse < PaystackGateway::Response; end
+
+    # Error response from #notify.
+    class NotifyError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#notify
+    # Send Notification: POST /paymentrequest/notify/{id}
+    # Trigger an email reminder to a customer for a previously created payment request
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a previously created payment request
+    #
+    # @return [NotifyResponse] successful response
+    # @raise [NotifyError] if the request fails
+    api_method def self.notify(id:)
+      use_connection do |connection|
+        connection.post(
+          "/paymentrequest/notify/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #totals.
+    class TotalsResponse < PaystackGateway::Response
+      delegate :pending, :successful, :total, to: :data
+    end
+
+    # Error response from #totals.
+    class TotalsError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#totals
+    # Payment Request Total: GET /paymentrequest/totals
+    # Get the metric of all pending and successful payment requests
+    #
+    #
+    # @return [TotalsResponse] successful response
+    # @raise [TotalsError] if the request fails
+    api_method def self.totals
+      use_connection do |connection|
+        connection.get(
+          '/paymentrequest/totals',
+        )
+      end
+    end
+
+    # Successful response from calling #finalize.
+    class FinalizeResponse < PaystackGateway::Response
+      delegate :id,
+               :integration,
+               :domain,
+               :amount,
+               :currency,
+               :due_date,
+               :has_invoice,
+               :invoice_number,
+               :description,
+               :pdf_url,
+               :line_items,
+               :tax,
+               :request_code,
+               :paid,
+               :paid_at,
+               :metadata,
+               :notifications,
+               :offline_reference,
+               :customer,
+               :created_at,
+               :discount,
+               :split_code,
+               :pending_amount, to: :data
+    end
+
+    # Error response from #finalize.
+    class FinalizeError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#finalize
+    # Finalize Payment Request: POST /paymentrequest/finalize/{id}
+    # Finalise the creation of a draft payment request for a customer
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a draft payment request
+    #
+    # @return [FinalizeResponse] successful response
+    # @raise [FinalizeError] if the request fails
+    api_method def self.finalize(id:)
+      use_connection do |connection|
+        connection.post(
+          "/paymentrequest/finalize/#{id}",
+        )
+      end
+    end
+
+    # Successful response from calling #archive.
+    class ArchiveResponse < PaystackGateway::Response; end
+
+    # Error response from #archive.
+    class ArchiveError < ApiError; end
+
+    # https://paystack.com/docs/api/payment-request/#archive
+    # Archive Payment Request: POST /paymentrequest/archive/{id}
+    # Archive a payment request to clean up your records. An archived payment request
+    # cannot be verified and will not be returned when listing all previously created
+    # payment requests.
+    #
+    # @param id [Integer] (required)
+    #        The unique identifier of a previously created payment request
+    #
+    # @return [ArchiveResponse] successful response
+    # @raise [ArchiveError] if the request fails
+    api_method def self.archive(id:)
+      use_connection do |connection|
+        connection.post(
+          "/paymentrequest/archive/#{id}",
+        )
+      end
+    end
+  end
+end

data/lib/paystack_gateway/plan.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module PaystackGateway
+  # https://paystack.com/docs/api/plan
+  #
+  # Plans
+  # A collection of endpoints for creating and managing recurring payment configuration
+  module Plan
+    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/plan/#list
+    # List Plans: GET /plan
+    # List all recurring payment plans
+    #
+    # @param per_page [Integer]
+    #        Number of records to fetch per page
+    # @param page [Integer]
+    #        The section to retrieve
+    # @param interval ["daily", "weekly", "monthly", "biannually", "annually"]
+    #        Specify interval of the plan
+    # @param amount [Integer]
+    #        The amount on the plans 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,
+      interval: nil,
+      amount: nil,
+      from: nil,
+      to: nil
+    )
+      use_connection do |connection|
+        connection.get(
+          '/plan',
+          {
+            perPage: per_page,
+            page:,
+            interval:,
+            amount:,
+            from:,
+            to:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #create.
+    class CreateResponse < PaystackGateway::Response
+      delegate :currency,
+               :name,
+               :amount,
+               :interval,
+               :integration,
+               :domain,
+               :plan_code,
+               :invoice_limit,
+               :send_invoices,
+               :send_sms,
+               :hosted_page,
+               :migrate,
+               :is_archived,
+               :id,
+               :createdAt,
+               :updatedAt, to: :data
+    end
+
+    # Error response from #create.
+    class CreateError < ApiError; end
+
+    # https://paystack.com/docs/api/plan/#create
+    # Create Plan: POST /plan
+    # Create a plan for recurring payments
+    #
+    # @param name [String] (required)
+    #        Name of plan
+    # @param amount [Integer] (required)
+    #        Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents,
+    #        if currency is ZAR
+    # @param interval ["daily", "weekly", "monthly", "biannually", "annually"] (required)
+    #        Payment interval
+    # @param description [String]
+    #        A description for this plan
+    # @param send_invoices [Boolean]
+    #        Set to false if you don't want invoices to be sent to your customers
+    # @param send_sms [Boolean]
+    #        Set to false if you don't want text messages to be sent to your customers
+    # @param currency [String]
+    #        Currency in which amount is set. Allowed values are NGN, GHS, ZAR or USD
+    # @param invoice_limit [Integer]
+    #        Number of invoices to raise during subscription to this plan. Can be overridden
+    #        by specifying an invoice_limit while subscribing.
+    #
+    # @return [CreateResponse] successful response
+    # @raise [CreateError] if the request fails
+    api_method def self.create(
+      name:,
+      amount:,
+      interval:,
+      description: nil,
+      send_invoices: nil,
+      send_sms: nil,
+      currency: nil,
+      invoice_limit: nil
+    )
+      use_connection do |connection|
+        connection.post(
+          '/plan',
+          {
+            name:,
+            amount:,
+            interval:,
+            description:,
+            send_invoices:,
+            send_sms:,
+            currency:,
+            invoice_limit:,
+          }.compact,
+        )
+      end
+    end
+
+    # Successful response from calling #fetch.
+    class FetchResponse < PaystackGateway::Response
+      delegate :subscriptions,
+               :pages,
+               :domain,
+               :name,
+               :plan_code,
+               :description,
+               :amount,
+               :interval,
+               :invoice_limit,
+               :send_invoices,
+               :send_sms,
+               :hosted_page,
+               :hosted_page_url,
+               :hosted_page_summary,
+               :currency,
+               :migrate,
+               :is_deleted,
+               :is_archived,
+               :id,
+               :integration,
+               :createdAt,
+               :updatedAt,
+               :pages_count,
+               :subscribers_count,
+               :subscriptions_count,
+               :active_subscriptions_count,
+               :total_revenue,
+               :subscribers, to: :data
+    end
+
+    # Error response from #fetch.
+    class FetchError < ApiError; end
+
+    # https://paystack.com/docs/api/plan/#fetch
+    # Fetch Plan: GET /plan/{code}
+    # Get the details of a payment plan
+    #
+    # @param code [String] (required)
+    #        The plan code you want to fetch
+    #
+    # @return [FetchResponse] successful response
+    # @raise [FetchError] if the request fails
+    api_method def self.fetch(code:)
+      use_connection do |connection|
+        connection.get(
+          "/plan/#{code}",
+        )
+      end
+    end
+
+    # Successful response from calling #update.
+    class UpdateResponse < PaystackGateway::Response; end
+
+    # Error response from #update.
+    class UpdateError < ApiError; end
+
+    # https://paystack.com/docs/api/plan/#update
+    # Update Plan: PUT /plan/{code}
+    # Update a plan details on your integration
+    #
+    # @param code [String] (required)
+    #        The plan code you want to fetch
+    # @param name [String]
+    #        Name of plan
+    # @param amount [Integer]
+    #        Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents,
+    #        if currency is ZAR
+    # @param interval ["daily", "weekly", "monthly", "biannually", "annually"]
+    #        Payment interval
+    # @param description [Boolean]
+    #        A description for this plan
+    # @param send_invoices [Boolean]
+    #        Set to false if you don't want invoices to be sent to your customers
+    # @param send_sms [Boolean]
+    #        Set to false if you don't want text messages to be sent to your customers
+    # @param currency [String]
+    #        Currency in which amount is set. Allowed values are NGN, GHS, ZAR or USD
+    # @param invoice_limit [Integer]
+    #        Number of invoices to raise during subscription to this plan. Can be overridden
+    #        by specifying an invoice_limit while subscribing.
+    #
+    # @return [UpdateResponse] successful response
+    # @raise [UpdateError] if the request fails
+    api_method def self.update(
+      code:,
+      name: nil,
+      amount: nil,
+      interval: nil,
+      description: nil,
+      send_invoices: nil,
+      send_sms: nil,
+      currency: nil,
+      invoice_limit: nil
+    )
+      use_connection do |connection|
+        connection.put(
+          "/plan/#{code}",
+          {
+            name:,
+            amount:,
+            interval:,
+            description:,
+            send_invoices:,
+            send_sms:,
+            currency:,
+            invoice_limit:,
+          }.compact,
+        )
+      end
+    end
+  end
+end