paystack_sdk 0.1.1 → 0.2.0

data/lib/paystack_sdk/resources/charges.rb

@@ -1,104 +1,218 @@
 # 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 Charge`. Hand-written extras go in lib/paystack_sdk/resources/extensions/charges.rb.
+# scaffold-digest: 8744e957871c8477379f6dc1389cc1e79df5884a4e594936b9ce64ffb6907ef2
+
 require_relative "base"
+require_relative "extensions/charges"
 
 module PaystackSdk
   module Resources
-    # The `Charges` resource exposes helpers for initiating and managing charges
-    # through alternative payment channels such as Mobile Money.
-    #
-    # At the moment the SDK focuses on supporting the Mobile Money channel which
-    # requires posting to the `/charge` endpoint with the customer's email,
-    # amount, currency, and the provider specific `mobile_money` payload.
+    # Charge operations.
     class Charges < PaystackSdk::Resources::Base
-      MOBILE_MONEY_PROVIDERS = %w[mtn atl vod mpesa orange wave].freeze
+      include Extensions::Charges
+
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {}.freeze
 
-      # Initiates a Mobile Money payment.
+      # Create Charge.
       #
-      # @param payload [Hash] The payload containing charge details.
-      # @option payload [String] :email Customer's email address (required)
-      # @option payload [Integer] :amount Amount in the lowest currency unit (required)
-      # @option payload [String] :currency ISO currency code (default: GHS)
-      # @option payload [String] :reference Optional reference supplied by the merchant
-      # @option payload [String] :callback_url Optional callback URL for Paystack to redirect to
-      # @option payload [Hash] :metadata Optional metadata to attach to the transaction
-      # @option payload [Hash] :mobile_money The mobile money details (required)
-      #   - :phone [String] Customer's mobile money phone number (required)
-      #   - :provider [String] Mobile money provider code (required)
+      # Initiate a payment by integrating the payment channel of your choice.
       #
-      # @return [PaystackSdk::Response] The wrapped API response.
-      # @raise [PaystackSdk::ValidationError] If the payload is invalid.
-      def mobile_money(payload)
-        validate_mobile_money_payload!(payload)
-
-        normalized_payload = normalize_mobile_money_provider(payload)
-        response = @connection.post("/charge", normalized_payload)
-        handle_response(response)
+      # @param email [String] Customer's email address
+      # @param amount [Integer] Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
+      # @param authorization_code [String] An authorization code to charge.
+      # @param pin [String] 4-digit PIN (send with a non-reusable authorization code)
+      # @param reference [String] Unique transaction reference.
+      # @param birthday [String] The customer's birthday in the format YYYY-MM-DD e.g 2017-05-16
+      # @param device_id [String] This is the unique identifier of the device a user uses in making payment.
+      # @param metadata [Hash] JSON object of custom data
+      # @param bank [Hash] The bank object if charging a bank account
+      # @param mobile_money [Hash] Details of the mobile service provider
+      # @param ussd [Hash] The USSD code for the provider to charge
+      # @param eft [Hash] Details of the EFT provider
+      # @param currency [String] The currency to charge in (GHS, KES and so on); Paystack uses your integration's currency when it is left out.
+      # @param split_code [String] The split code (SPL_...) of a previously created split.
+      # @param subaccount [String] The code (ACCT_...) of the subaccount that owns the payment.
+      # @param bank_transfer [Hash] Settings for the Pay with Transfer and Pesalink channel (account_expires_at, the expiry time of the account).
+      # @param qr [Hash] The QR provider details (provider, scan-to-pay being the only one); South Africa only.
+      # @param capitec_pay [Hash] The Capitec Pay account holder (identifier_key, one of CELLPHONE, IDNUMBER or ACCOUNTNUMBER, and identifier_value); South Africa only.
+      # @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/charge/#create
+      def create(
+        email:,
+        amount:,
+        authorization_code: nil,
+        pin: nil,
+        reference: nil,
+        birthday: nil,
+        device_id: nil,
+        metadata: nil,
+        bank: nil,
+        mobile_money: nil,
+        ussd: nil,
+        eft: nil,
+        currency: nil,
+        split_code: nil,
+        subaccount: nil,
+        bank_transfer: nil,
+        qr: nil,
+        capitec_pay: nil
+      )
+        validate_presence!(value: email, name: "email")
+        validate_email!(email: email, name: "email")
+        validate_presence!(value: amount, name: "amount")
+        validate_positive_integer!(value: amount, name: "amount")
+        validate_reference_format!(reference: reference, name: "reference") unless reference.nil?
+
+        wire_body = to_wire(
+          {
+            email:,
+            amount:,
+            authorization_code:,
+            pin:,
+            reference:,
+            birthday: format_date(birthday, name: "birthday"),
+            device_id:,
+            metadata:,
+            bank:,
+            mobile_money:,
+            ussd:,
+            eft:,
+            currency:,
+            split_code:,
+            subaccount:,
+            bank_transfer:,
+            qr:,
+            capitec_pay:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/charge", wire_body))
       end
 
-      # Submits an OTP for authorising a pending Mobile Money charge (e.g. Vodafone).
+      # Submit PIN.
       #
-      # @param payload [Hash] Payload containing the OTP and charge reference.
-      # @option payload [String] :otp The OTP supplied by the customer (required)
-      # @option payload [String] :reference The charge reference returned from initiation (required)
+      # Submit PIN to continue a charge
       #
-      # @return [PaystackSdk::Response] The wrapped API response.
-      # @raise [PaystackSdk::ValidationError] If the payload is invalid.
-      def submit_otp(payload)
-        validate_fields!(
-          payload: payload,
-          validations: {
-            otp: {type: :string, required: true},
-            reference: {type: :reference, required: true}
-          }
-        )
+      # @param pin [String] Customer's PIN for the ongoing transaction
+      # @param reference [String] Transaction reference that requires the PIN
+      # @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/charge/#submit-pin
+      def submit_pin(pin:, reference:)
+        validate_presence!(value: pin, name: "pin")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+
+        wire_body = to_wire({pin:, reference:}, WIRE_NAMES)
 
-        response = @connection.post("/charge/submit_otp", payload)
-        handle_response(response)
+        handle_response(@connection.post("/charge/submit_pin", wire_body))
       end
 
-      private
-
-      def validate_mobile_money_payload!(payload)
-        validate_fields!(
-          payload: payload,
-          validations: {
-            email: {type: :email, required: true},
-            amount: {type: :positive_integer, required: true},
-            currency: {type: :currency, required: false},
-            reference: {type: :reference, required: false},
-            callback_url: {required: false},
-            metadata: {required: false},
-            mobile_money: {required: true}
-          }
-        )
+      # Submit OTP.
+      #
+      # Submit OTP to complete a charge
+      #
+      # @param otp [String] Customer's OTP for ongoing transaction
+      # @param reference [String] The reference of the ongoing 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/charge/#submit-otp
+      def submit_otp(otp:, reference:)
+        validate_presence!(value: otp, name: "otp")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+
+        wire_body = to_wire({otp:, reference:}, WIRE_NAMES)
 
-        mobile_money = payload[:mobile_money] || payload["mobile_money"]
-        validate_hash!(input: mobile_money, name: "mobile_money")
+        handle_response(@connection.post("/charge/submit_otp", wire_body))
+      end
+
+      # Submit Phone.
+      #
+      # Submit phone number when requested
+      #
+      # @param phone [String] Customer's mobile number
+      # @param reference [String] The reference of the ongoing 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/charge/#submit-phone
+      def submit_phone(phone:, reference:)
+        validate_presence!(value: phone, name: "phone")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
 
-        phone = mobile_money[:phone] || mobile_money["phone"]
-        validate_presence!(value: phone, name: "mobile_money phone")
+        wire_body = to_wire({phone:, reference:}, WIRE_NAMES)
 
-        provider = mobile_money[:provider] || mobile_money["provider"]
-        validate_mobile_money_provider!(provider)
+        handle_response(@connection.post("/charge/submit_phone", wire_body))
       end
 
-      def validate_mobile_money_provider!(provider)
-        normalized = provider&.to_s&.downcase
-        validate_allowed_values!(
-          value: normalized,
-          allowed_values: MOBILE_MONEY_PROVIDERS,
-          name: "mobile_money provider",
-          allow_nil: false
+      # Submit Birthday.
+      #
+      # Submit the customer's birthday when requested
+      #
+      # @param birthday [String] Customer's birthday in the format YYYY-MM-DD e.g 2016-09-21
+      # @param reference [String] The reference of the ongoing 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/charge/#submit-birthday
+      def submit_birthday(birthday:, reference:)
+        validate_presence!(value: birthday, name: "birthday")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+
+        wire_body = to_wire(
+          {
+            birthday: format_date(birthday, name: "birthday"),
+            reference:
+          },
+          WIRE_NAMES
         )
+
+        handle_response(@connection.post("/charge/submit_birthday", wire_body))
+      end
+
+      # Submit Address.
+      #
+      # Send the details of the customer's address for address verification
+      #
+      # @param address [String] Customer's address
+      # @param city [String] Customer's city
+      # @param state [String] Customer's state
+      # @param zip_code [String] Customer's zipcode
+      # @param reference [String] The reference of the ongoing 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/charge/#submit-address
+      def submit_address(address:, city:, state:, zip_code:, reference:)
+        validate_presence!(value: address, name: "address")
+        validate_presence!(value: city, name: "city")
+        validate_presence!(value: state, name: "state")
+        validate_presence!(value: zip_code, name: "zip_code")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+
+        wire_body = to_wire({address:, city:, state:, zip_code:, reference:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/charge/submit_address", wire_body))
       end
 
-      def normalize_mobile_money_provider(payload)
-        mm = payload[:mobile_money] || payload["mobile_money"] || {}
-        provider = mm[:provider] || mm["provider"]
-        normalized_provider = provider&.to_s&.downcase
-        # Avoid mutating the caller's payload
-        payload.merge(mobile_money: mm.merge(provider: normalized_provider))
+      # Check pending charge.
+      #
+      # When you get `pending` as a charge status or if there was an exception when calling any of the `/charge` endpoints, wait 10 seconds or more, then make a check to see if its status has changed.
+      #
+      # @param reference [String] The reference of the ongoing 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/charge/#check
+      def check_pending(reference:)
+        validate_presence!(value: reference, name: "reference")
+
+        handle_response(@connection.get("/charge/#{escape_path(reference, name: "reference")}"))
       end
     end
   end