paystack_sdk 0.1.1 → 0.2.0

data/lib/paystack_sdk/resources/refunds.rb

@@ -0,0 +1,116 @@
+# 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 Refund`. Hand-written extras go in lib/paystack_sdk/resources/extensions/refunds.rb.
+# scaffold-digest: c3b04aa2ea57cc443996cfdf4b3432aa4839b01df431c881aa247d2c97514a1b
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Refund operations.
+    class Refunds < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {per_page: "perPage", transaction_id: "transaction"}.freeze
+
+      # List Refunds.
+      #
+      # List previously created refunds
+      #
+      # @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
+      # @param transaction_id [Integer] The ID of the refunded 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/refund/#list
+      def list(per_page: nil, page: nil, from: nil, to: nil, transaction_id: 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"),
+            transaction_id:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/refund", wire_query))
+      end
+
+      # Create Refund.
+      #
+      # Initiate a refund for a previously completed transaction
+      #
+      # @param transaction [String] The reference or ID of a previously completed transaction.
+      # @param amount [Integer] Amount to be refunded to the customer.
+      # @param currency [String] Three-letter ISO currency One of: GHS, KES, NGN, USD, ZAR.
+      # @param customer_note [String] Customer reason
+      # @param merchant_note [String] Merchant reason
+      # @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/refund/#create
+      def create(transaction:, amount: nil, currency: nil, customer_note: nil, merchant_note: nil)
+        validate_presence!(value: transaction, name: "transaction")
+        validate_positive_integer!(value: amount, name: "amount")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[GHS KES NGN USD ZAR],
+          name: "currency"
+        )
+
+        wire_body = to_wire(
+          {
+            transaction:,
+            amount:,
+            currency:,
+            customer_note:,
+            merchant_note:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/refund", wire_body))
+      end
+
+      # Retry Refund.
+      #
+      # Retry a refund with a `needs-attention` status by providing the bank account details of a customer.
+      #
+      # @param id [Integer] The identifier of the refund
+      # @param refund_account_details [Hash] An object that contains the customer’s account details for refund
+      # @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/refund/#retry
+      def retry_with_customer_details(id:, refund_account_details:)
+        validate_presence!(value: id, name: "id")
+        validate_presence!(value: refund_account_details, name: "refund_account_details")
+
+        wire_body = to_wire({refund_account_details:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.post("/refund/retry_with_customer_details/#{escape_path(id, name: "id")}", wire_body)
+        )
+      end
+
+      # Fetch Refund.
+      #
+      # Get a previously created refund
+      #
+      # @param id [Integer] The identifier of the refund
+      # @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/refund/#fetch
+      def fetch(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(@connection.get("/refund/#{escape_path(id, name: "id")}"))
+      end
+    end
+  end
+end