zai_payment 2.3.2 → 2.5.0

data/lib/zai_payment/resources/bank_account.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # BankAccount resource for managing Zai bank accounts
+    #
+    # @see https://developer.hellozai.com/reference/createbankaccount
+    class BankAccount
+      attr_reader :client
+
+      # Map of attribute keys to API field names
+      FIELD_MAPPING = {
+        user_id: :user_id,
+        bank_name: :bank_name,
+        account_name: :account_name,
+        routing_number: :routing_number,
+        account_number: :account_number,
+        account_type: :account_type,
+        holder_type: :holder_type,
+        country: :country,
+        payout_currency: :payout_currency,
+        currency: :currency
+      }.freeze
+
+      # Map of UK-specific attribute keys to API field names
+      UK_FIELD_MAPPING = {
+        user_id: :user_id,
+        bank_name: :bank_name,
+        account_name: :account_name,
+        routing_number: :routing_number,
+        account_number: :account_number,
+        account_type: :account_type,
+        holder_type: :holder_type,
+        country: :country,
+        payout_currency: :payout_currency,
+        currency: :currency,
+        iban: :iban,
+        swift_code: :swift_code
+      }.freeze
+
+      # Valid account types
+      VALID_ACCOUNT_TYPES = %w[savings checking].freeze
+
+      # Valid holder types
+      VALID_HOLDER_TYPES = %w[personal business].freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # Get a specific bank account by ID
+      #
+      # @param bank_account_id [String] the bank account ID
+      # @param include_decrypted_fields [Boolean] if true, the API will decrypt and return
+      #   sensitive bank account fields (for example, the full account number). Defaults to false
+      # @return [Response] the API response containing bank account details
+      #
+      # @example
+      #   bank_accounts = ZaiPayment::Resources::BankAccount.new
+      #   response = bank_accounts.show("bank_account_id")
+      #   response.data # => {"id" => "bank_account_id", "active" => true, ...}
+      #
+      # @example with decrypted fields
+      #   response = bank_accounts.show("bank_account_id", include_decrypted_fields: true)
+      #   # Returns full account number instead of masked version
+      #
+      # @see https://developer.hellozai.com/reference/showbankaccount
+      def show(bank_account_id, include_decrypted_fields: false)
+        validate_id!(bank_account_id, 'bank_account_id')
+
+        params = {}
+        params[:include_decrypted_fields] = include_decrypted_fields if include_decrypted_fields
+
+        client.get("/bank_accounts/#{bank_account_id}", params: params)
+      end
+
+      # Create a new bank account for Australia
+      #
+      # @param attributes [Hash] bank account attributes
+      # @option attributes [String] :user_id (Required) User ID
+      # @option attributes [String] :bank_name (Required) Bank name (defaults to Bank of Australia)
+      # @option attributes [String] :account_name (Required) Account name (defaults to Samuel Seller)
+      # @option attributes [String] :routing_number (Required) Routing number / BSB number
+      #   (defaults to 111123)
+      # @option attributes [String] :account_number (Required) Account number
+      #   (defaults to 111234)
+      # @option attributes [String] :account_type (Required) Account type
+      #   ('savings' or 'checking', defaults to checking)
+      # @option attributes [String] :holder_type (Required) Holder type ('personal' or 'business', defaults to personal)
+      # @option attributes [String] :country (Required) Country code (ISO 3166-1 alpha-3, max 3 chars, defaults to AUS)
+      # @option attributes [String] :payout_currency Optional currency code for payouts (ISO 4217 alpha-3)
+      # @option attributes [String] :currency Optional currency code (ISO 4217 alpha-3)
+      # @return [Response] the API response containing created bank account
+      #
+      # @example Create an Australian bank account
+      #   bank_accounts = ZaiPayment::Resources::BankAccount.new
+      #   response = bank_accounts.create_au(
+      #     user_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      #     bank_name: 'Bank of Australia',
+      #     account_name: 'Samuel Seller',
+      #     routing_number: '111123',
+      #     account_number: '111234',
+      #     account_type: 'checking',
+      #     holder_type: 'personal',
+      #     country: 'AUS',
+      #     payout_currency: 'AUD',
+      #     currency: 'AUD'
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createbankaccount
+      def create_au(**attributes)
+        validate_create_au_attributes!(attributes)
+
+        body = build_bank_account_body(attributes, :au)
+        client.post('/bank_accounts', body: body)
+      end
+
+      # Create a new bank account for UK
+      #
+      # @param attributes [Hash] bank account attributes
+      # @option attributes [String] :user_id (Required) User ID
+      # @option attributes [String] :bank_name (Required) Bank name (defaults to Bank of UK)
+      # @option attributes [String] :account_name (Required) Account name (defaults to Samuel Seller)
+      # @option attributes [String] :routing_number (Required) Routing number / Sort Code / BSB
+      #   number (defaults to 111123)
+      # @option attributes [String] :account_number (Required) Account number
+      #   (defaults to 111234)
+      # @option attributes [String] :account_type (Required) Account type
+      #   ('savings' or 'checking', defaults to checking)
+      # @option attributes [String] :holder_type (Required) Holder type ('personal' or 'business', defaults to personal)
+      # @option attributes [String] :country (Required) Country code (ISO 3166-1 alpha-3, max 3 chars, defaults to GBR)
+      # @option attributes [String] :payout_currency Optional currency code for payouts (ISO 4217 alpha-3)
+      # @option attributes [String] :currency Optional currency code (ISO 4217 alpha-3)
+      # @option attributes [String] :iban (Required for UK) IBAN number
+      # @option attributes [String] :swift_code (Required for UK) SWIFT Code / BIC
+      # @return [Response] the API response containing created bank account
+      #
+      # @example Create a UK bank account
+      #   bank_accounts = ZaiPayment::Resources::BankAccount.new
+      #   response = bank_accounts.create_uk(
+      #     user_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      #     bank_name: 'Bank of UK',
+      #     account_name: 'Samuel Seller',
+      #     routing_number: '111123',
+      #     account_number: '111234',
+      #     account_type: 'checking',
+      #     holder_type: 'personal',
+      #     country: 'GBR',
+      #     payout_currency: 'GBP',
+      #     currency: 'GBP',
+      #     iban: 'GB25QHWM02498765432109',
+      #     swift_code: 'BUKBGB22'
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createbankaccount
+      def create_uk(**attributes)
+        validate_create_uk_attributes!(attributes)
+
+        body = build_bank_account_body(attributes, :uk)
+        client.post('/bank_accounts', body: body)
+      end
+
+      # Redact a bank account
+      #
+      # Redacts a bank account using the given bank_account_id. Redacted bank accounts
+      # can no longer be used as a funding source or a disbursement destination.
+      #
+      # @param bank_account_id [String] the bank account ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   bank_accounts = ZaiPayment::Resources::BankAccount.new
+      #   response = bank_accounts.redact("bank_account_id")
+      #
+      # @see https://developer.hellozai.com/reference/redactbankaccount
+      def redact(bank_account_id)
+        validate_id!(bank_account_id, 'bank_account_id')
+        client.delete("/bank_accounts/#{bank_account_id}")
+      end
+
+      # Validate a US bank routing number
+      #
+      # Validates a US bank routing number before creating an account. This can be used to
+      # provide on-demand verification and further information of the bank information a user
+      # is providing.
+      #
+      # @param routing_number [String] the US bank routing number
+      # @return [Response] the API response containing routing number details
+      #
+      # @example
+      #   bank_accounts = ZaiPayment::Resources::BankAccount.new
+      #   response = bank_accounts.validate_routing_number("122235821")
+      #   response.data # => {"routing_number" => "122235821", "customer_name" => "US BANK NA", ...}
+      #
+      # @see https://developer.hellozai.com/reference/validateroutingnumber
+      def validate_routing_number(routing_number)
+        validate_presence!(routing_number, 'routing_number')
+
+        params = { routing_number: routing_number }
+        client.get('/tools/routing_number', params: params)
+      end
+
+      private
+
+      def validate_id!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_presence!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise Errors::ValidationError, "#{field_name} is required and cannot be blank"
+      end
+
+      def validate_create_au_attributes!(attributes)
+        validate_required_au_attributes!(attributes)
+        validate_account_type!(attributes[:account_type]) if attributes[:account_type]
+        validate_holder_type!(attributes[:holder_type]) if attributes[:holder_type]
+        validate_country!(attributes[:country]) if attributes[:country]
+      end
+
+      def validate_create_uk_attributes!(attributes)
+        validate_required_uk_attributes!(attributes)
+        validate_account_type!(attributes[:account_type]) if attributes[:account_type]
+        validate_holder_type!(attributes[:holder_type]) if attributes[:holder_type]
+        validate_country!(attributes[:country]) if attributes[:country]
+      end
+
+      def validate_required_au_attributes!(attributes)
+        required_fields = %i[user_id bank_name account_name routing_number account_number
+                             account_type holder_type country]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || attributes[field].to_s.strip.empty?
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_required_uk_attributes!(attributes)
+        required_fields = %i[user_id bank_name account_name routing_number account_number
+                             account_type holder_type country iban swift_code]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || attributes[field].to_s.strip.empty?
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_account_type!(account_type)
+        return if VALID_ACCOUNT_TYPES.include?(account_type.to_s.downcase)
+
+        raise Errors::ValidationError,
+              "account_type must be one of: #{VALID_ACCOUNT_TYPES.join(', ')}"
+      end
+
+      def validate_holder_type!(holder_type)
+        return if VALID_HOLDER_TYPES.include?(holder_type.to_s.downcase)
+
+        raise Errors::ValidationError,
+              "holder_type must be one of: #{VALID_HOLDER_TYPES.join(', ')}"
+      end
+
+      def validate_country!(country)
+        # Country should be ISO 3166-1 alpha-3 code (3 letters)
+        return if country.to_s.match?(/\A[A-Z]{3}\z/i)
+
+        raise Errors::ValidationError, 'country must be a valid ISO 3166-1 alpha-3 code (e.g., AUS, GBR)'
+      end
+
+      def build_bank_account_body(attributes, region)
+        body = {}
+        field_mapping = region == :uk ? UK_FIELD_MAPPING : FIELD_MAPPING
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = field_mapping[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/zai_payment/resources/item.rb

@@ -25,6 +25,22 @@ module ZaiPayment
         tax_invoice: :tax_invoice
       }.freeze
 
+      ITEM_PAYMENT_ATTRIBUTES = {
+        account_id: :account_id,
+        device_id: :device_id,
+        ip_address: :ip_address,
+        cvv: :cvv,
+        merchant_phone: :merchant_phone
+      }.freeze
+
+      ITEM_ASYNC_PAYMENT_ATTRIBUTES = {
+        account_id: :account_id,
+        request_three_d_secure: :request_three_d_secure
+      }.freeze
+
+      # Valid values for request_three_d_secure parameter
+      REQUEST_THREE_D_SECURE_VALUES = %w[automatic challenge any].freeze
+
       def initialize(client: nil)
         @client = client || Client.new
       end
@@ -299,6 +315,197 @@ module ZaiPayment
         client.get("/items/#{item_id}/status")
       end
 
+      # Make a payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :account_id Required account ID
+      # @option attributes [String] :device_id Optional device ID
+      # @option attributes [String] :ip_address Optional IP address
+      # @option attributes [String] :cvv Optional CVV
+      # @option attributes [String] :merchant_phone Optional merchant phone number
+      # @return [Response] the API response containing payment details
+      #
+      # @example Make a payment with required parameters
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.make_payment("item_id", account_id: "account_id")
+      #   response.data # => {"items" => {"id" => "...", "amount" => "...", ...}}
+      #
+      # @example Make a payment with optional parameters
+      #   response = items.make_payment(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     device_id: "device_789",
+      #     ip_address: "192.168.1.1",
+      #     cvv: "123",
+      #     merchant_phone: "+1234567890"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/makepayment
+      def make_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = build_item_payment_body(attributes)
+
+        client.patch("/items/#{item_id}/make_payment", body: body)
+      end
+
+      # Cancel an item
+
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing cancellation details
+      #
+      # @example Cancel a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.cancel("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/cancelitem
+      def cancel(item_id)
+        validate_id!(item_id, 'item_id')
+        client.patch("/items/#{item_id}/cancel")
+      end
+
+      # Refund an item
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :refund_amount Optional refund amount
+      # @option attributes [String] :refund_message Optional refund message
+      # @option attributes [String] :account_id Optional account ID
+      # @return [Response] the API response containing refund details
+      #
+      # @example Refund an item
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.refund("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Refund an item with optional parameters
+      #   response = items.refund(
+      #     "item_id",
+      #     refund_amount: 10000,
+      #     refund_message: "Refund for product XYZ",
+      #     account_id: "account_789"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/refund
+      def refund(item_id, refund_amount: nil, refund_message: nil, account_id: nil)
+        validate_id!(item_id, 'item_id')
+
+        body = build_refund_body(
+          refund_amount: refund_amount,
+          refund_message: refund_message,
+          account_id: account_id
+        )
+
+        client.patch("/items/#{item_id}/refund", body: body)
+      end
+
+      # Authorize Payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :account_id Required account ID
+      # @option attributes [String] :cvv Optional CVV
+      # @option attributes [String] :merchant_phone Optional merchant phone number
+      # @return [Response] the API response containing authorization details
+      #
+      # @example Authorize a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.authorize_payment("item_id", account_id: "account_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Authorize a payment with optional parameters
+      #   response = items.authorize_payment(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     cvv: "123",
+      #     merchant_phone: "+1234567890"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/authorizepayment
+      def authorize_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        client.patch("/items/#{item_id}/authorize_payment", body: build_item_payment_body(attributes))
+      end
+
+      # Capture Payment
+      #
+      # @param item_id [String] the item ID
+      # @option attributes [String] :amount Optional amount to capture
+      # @return [Response] the API response containing capture details
+      #
+      # @example Capture a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.capture_payment("item_id", amount: 10000)
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @example Capture a payment with optional parameters
+      #   response = items.capture_payment(
+      #     "item_id",
+      #     amount: 10000
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/capturepayment
+      def capture_payment(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = {}
+        body[:amount] = attributes[:amount] if attributes[:amount]
+
+        client.patch("/items/#{item_id}/capture_payment", body: body)
+      end
+
+      # Void Payment
+      #
+      # @param item_id [String] the item ID
+      # @return [Response] the API response containing void details
+      #
+      # @example Void a payment
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.void_payment("item_id")
+      #   response.data # => {"items" => {"id" => "...", "state" => "...", ...}}
+      #
+      # @see https://developer.hellozai.com/reference/voidpayment
+      def void_payment(item_id)
+        validate_id!(item_id, 'item_id')
+        client.patch("/items/#{item_id}/void_payment")
+      end
+
+      # Make an async Payment
+      #
+      # Initiate a card payment with 3D Secure 2.0 authentication support. This endpoint
+      # initiates the payment process and returns a payment_token required for 3DS2
+      # component initialisation.
+      #
+      # @param item_id [String] the item ID
+      # @param account_id [String] Account id of the bank account/credit card, etc making payment (not user id)
+      # @option attributes [String] :request_three_d_secure Customise the 3DS (3D Secure) preference for this payment.
+      #   Allowed values: 'automatic', 'challenge', 'any'. Defaults to 'automatic'.
+      #   - 'automatic': 3DS preference is determined automatically by the system
+      #   - 'challenge': Request a 3DS challenge is presented to the user
+      #   - 'any': Request a 3DS challenge regardless of the challenge flow
+      # @return [Response] the API response containing payment details with payment_token
+      #
+      # @example Make an async payment with required parameters
+      #   items = ZaiPayment::Resources::Item.new
+      #   response = items.make_payment_async("item_id", account_id: "account_id")
+      #   response.data # => {"payment_id" => "...", "payment_token" => "...", "items" => {...}}
+      #
+      # @example Make an async payment with 3DS challenge
+      #   response = items.make_payment_async(
+      #     "item_id",
+      #     account_id: "account_id",
+      #     request_three_d_secure: "challenge"
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/makepaymentasync
+      def make_payment_async(item_id, **attributes)
+        validate_id!(item_id, 'item_id')
+
+        body = build_async_payment_body(attributes)
+
+        client.patch("/items/#{item_id}/make_payment_async", body: body)
+      end
+
       private
 
       def validate_id!(value, field_name)
@@ -346,6 +553,28 @@ module ZaiPayment
         raise Errors::ValidationError, 'payment_type must be between 1 and 7'
       end
 
+      def validate_request_three_d_secure!(value)
+        return if REQUEST_THREE_D_SECURE_VALUES.include?(value.to_s)
+
+        raise Errors::ValidationError,
+              "request_three_d_secure must be one of: #{REQUEST_THREE_D_SECURE_VALUES.join(', ')}"
+      end
+
+      def build_item_payment_body(attributes)
+        validate_presence!(attributes[:account_id], 'account_id')
+
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = ITEM_PAYMENT_ATTRIBUTES[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+
       def build_item_body(attributes)
         body = {}
 
@@ -358,6 +587,34 @@ module ZaiPayment
 
         body
       end
+
+      def build_refund_body(refund_amount: nil, refund_message: nil, account_id: nil)
+        body = {}
+
+        body[:refund_amount] = refund_amount if refund_amount
+        body[:refund_message] = refund_message if refund_message
+        body[:account_id] = account_id if account_id
+
+        body
+      end
+
+      def build_async_payment_body(attributes)
+        validate_presence!(attributes[:account_id], 'account_id')
+
+        # Validate request_three_d_secure if provided
+        validate_request_three_d_secure!(attributes[:request_three_d_secure]) if attributes[:request_three_d_secure]
+
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = ITEM_ASYNC_PAYMENT_ATTRIBUTES[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
     end
   end
 end

data/lib/zai_payment/response.rb

@@ -8,6 +8,7 @@ module ZaiPayment
     RESPONSE_DATA_KEYS = %w[
       webhooks users items fees transactions
       batch_transactions bpay_accounts bank_accounts card_accounts
+      routing_number
     ].freeze
 
     def initialize(faraday_response)

data/lib/zai_payment/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZaiPayment
-  VERSION = '2.3.2'
+  VERSION = '2.5.0'
 end

data/lib/zai_payment.rb

@@ -14,6 +14,7 @@ require_relative 'zai_payment/resources/webhook'
 require_relative 'zai_payment/resources/user'
 require_relative 'zai_payment/resources/item'
 require_relative 'zai_payment/resources/token_auth'
+require_relative 'zai_payment/resources/bank_account'
 
 module ZaiPayment
   class << self
@@ -57,5 +58,10 @@ module ZaiPayment
     def token_auths
       @token_auths ||= Resources::TokenAuth.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::BankAccount] bank_account resource instance
+    def bank_accounts
+      @bank_accounts ||= Resources::BankAccount.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end