zai_payment 2.4.0 → 2.6.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/bpay_account.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # BpayAccount resource for managing Zai BPay accounts
+    #
+    # @see https://developer.hellozai.com/reference/createbpayaccount
+    class BpayAccount
+      attr_reader :client
+
+      # Map of attribute keys to API field names
+      FIELD_MAPPING = {
+        user_id: :user_id,
+        account_name: :account_name,
+        biller_code: :biller_code,
+        bpay_crn: :bpay_crn
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new
+      end
+
+      # Get a specific BPay account by ID
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response containing BPay account details
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.show("bpay_account_id")
+      #   response.data # => {"id" => "bpay_account_id", "active" => true, ...}
+      #
+      # @see https://developer.hellozai.com/reference/showbpayaccount
+      def show(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.get("/bpay_accounts/#{bpay_account_id}")
+      end
+
+      # Redact a BPay account
+      #
+      # Redacts a BPay account using the given bpay_account_id. Redacted BPay accounts
+      # can no longer be used as a disbursement destination.
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.redact("bpay_account_id")
+      #
+      # @see https://developer.hellozai.com/reference/redactbpayaccount
+      def redact(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.delete("/bpay_accounts/#{bpay_account_id}")
+      end
+
+      # Get the user associated with a BPay account
+      #
+      # Show the User the BPay Account is associated with using a given bpay_account_id.
+      #
+      # @param bpay_account_id [String] the BPay account ID
+      # @return [Response] the API response containing user details
+      #
+      # @example
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.show_user("bpay_account_id")
+      #   response.data # => {"id" => "user_id", "full_name" => "Samuel Seller", ...}
+      #
+      # @see https://developer.hellozai.com/reference/showbpayaccountuser
+      def show_user(bpay_account_id)
+        validate_id!(bpay_account_id, 'bpay_account_id')
+        client.get("/bpay_accounts/#{bpay_account_id}/users")
+      end
+
+      # Create a new BPay account
+      #
+      # Create a BPay Account to be used as a Disbursement destination.
+      #
+      # @param attributes [Hash] BPay account attributes
+      # @option attributes [String] :user_id (Required) User ID
+      # @option attributes [String] :account_name (Required) Name assigned by the platform/marketplace
+      #   to identify the account (similar to a nickname). Defaults to "My Water Bill Company"
+      # @option attributes [Integer] :biller_code (Required) The Biller Code for the biller that will
+      #   receive the payment. The Biller Code must be a numeric value with 3 to 10 digits.
+      # @option attributes [String] :bpay_crn (Required) Customer reference number (crn) to be used for
+      #   this bpay account. The CRN must contain between 2 and 20 digits. Defaults to "987654321"
+      # @return [Response] the API response containing created BPay account
+      #
+      # @example Create a BPay account
+      #   bpay_accounts = ZaiPayment::Resources::BpayAccount.new
+      #   response = bpay_accounts.create(
+      #     user_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      #     account_name: 'My Water Bill Company',
+      #     biller_code: 123456,
+      #     bpay_crn: '987654321'
+      #   )
+      #
+      # @see https://developer.hellozai.com/reference/createbpayaccount
+      def create(**attributes)
+        validate_create_attributes!(attributes)
+
+        body = build_bpay_account_body(attributes)
+        client.post('/bpay_accounts', body: body)
+      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_create_attributes!(attributes)
+        validate_required_attributes!(attributes)
+        validate_biller_code!(attributes[:biller_code]) if attributes[:biller_code]
+        validate_bpay_crn!(attributes[:bpay_crn]) if attributes[:bpay_crn]
+      end
+
+      def validate_required_attributes!(attributes)
+        required_fields = %i[user_id account_name biller_code bpay_crn]
+
+        missing_fields = required_fields.select do |field|
+          attributes[field].nil? || (attributes[field].respond_to?(:to_s) && attributes[field].to_s.strip.empty?)
+        end
+
+        return if missing_fields.empty?
+
+        raise Errors::ValidationError,
+              "Missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      def validate_biller_code!(biller_code)
+        # Biller code must be a numeric value with 3 to 10 digits
+        biller_code_str = biller_code.to_s
+
+        return if biller_code_str.match?(/\A\d{3,10}\z/)
+
+        raise Errors::ValidationError,
+              'biller_code must be a numeric value with 3 to 10 digits'
+      end
+
+      def validate_bpay_crn!(bpay_crn)
+        # CRN must contain between 2 and 20 digits
+        bpay_crn_str = bpay_crn.to_s
+
+        return if bpay_crn_str.match?(/\A\d{2,20}\z/)
+
+        raise Errors::ValidationError,
+              'bpay_crn must contain between 2 and 20 digits'
+      end
+
+      def build_bpay_account_body(attributes)
+        body = {}
+
+        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/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.4.0'
+  VERSION = '2.6.0'
 end

data/lib/zai_payment.rb

@@ -14,6 +14,8 @@ 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'
+require_relative 'zai_payment/resources/bpay_account'
 
 module ZaiPayment
   class << self
@@ -57,5 +59,15 @@ 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
+
+    # @return [ZaiPayment::Resources::BpayAccount] bpay_account resource instance
+    def bpay_accounts
+      @bpay_accounts ||= Resources::BpayAccount.new(client: Client.new(base_endpoint: :core_base))
+    end
   end
 end