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

data/readme.md

@@ -21,12 +21,13 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 - 🧠 **Smart Token Caching** - Auto-refresh before expiration, thread-safe storage  
 - 👥 **User Management** - Create and manage payin (buyers) & payout (sellers) users  
 - 📦 **Item Management** - Full CRUD for transactions/payments between buyers and sellers  
+- 🏦 **Bank Account Management** - Complete CRUD + validation for AU/UK bank accounts  
 - 🎫 **Token Auth** - Generate secure tokens for bank and card account data collection  
 - 🪝 **Webhooks** - Full CRUD + secure signature verification (HMAC SHA256)  
 - ⚙️ **Environment-Aware** - Seamless Pre-live / Production switching  
 - 🧱 **Modular & Extensible** - Clean resource-based architecture  
 - 🧰 **Zero Heavy Dependencies** - Lightweight, fast, and reliable  
-- 📦 **Production Ready** - 88%+ test coverage, RuboCop compliant  
+- 📦 **Production Ready** - 97%+ test coverage, RuboCop compliant  
 
 ---
 
@@ -88,82 +89,7 @@ The gem handles OAuth2 Client Credentials flow automatically - tokens are cached
 
 ### Users
 
-Manage payin (buyer) and payout (seller/merchant) users:
-
-```ruby
-# Create a payin user (buyer)
-response = ZaiPayment.users.create(
-  user_type: 'payin',
-  email: 'buyer@example.com',
-  first_name: 'John',
-  last_name: 'Doe',
-  country: 'USA',
-  mobile: '+1234567890'
-)
-
-# Create a payout user (seller/merchant)
-response = ZaiPayment.users.create(
-  user_type: 'payout',
-  email: 'seller@example.com',
-  first_name: 'Jane',
-  last_name: 'Smith',
-  country: 'AUS',
-  dob: '01/01/1990',
-  address_line1: '456 Market St',
-  city: 'Sydney',
-  state: 'NSW',
-  zip: '2000'
-)
-
-# Create a business user with company details
-response = ZaiPayment.users.create(
-  user_type: 'payout',
-  email: 'director@company.com',
-  first_name: 'John',
-  last_name: 'Director',
-  country: 'AUS',
-  mobile: '+61412345678',
-  authorized_signer_title: 'Director',
-  company: {
-    name: 'My Company',
-    legal_name: 'My Company Pty Ltd',
-    tax_number: '123456789',
-    business_email: 'admin@company.com',
-    country: 'AUS',
-    charge_tax: true
-  }
-)
-
-# List users
-response = ZaiPayment.users.list(limit: 10, offset: 0)
-
-# Get user details
-response = ZaiPayment.users.show('user_id')
-
-# Update user
-response = ZaiPayment.users.update('user_id', mobile: '+9876543210')
-
-# Show user wallet account
-response = ZaiPayment.users.wallet_account('user_id')
-
-# List user items with pagination
-response = ZaiPayment.users.items('user_id', limit: 50, offset: 10)
-
-# Set user disbursement account
-response = ZaiPayment.users.set_disbursement_account('user_id', 'bank_account_id')
-
-# Show user bank account
-response = ZaiPayment.users.bank_account('user_id')
-
-# Verify user (prelive only)
-response = ZaiPayment.users.verify('user_id')
-
-# Show user card account
-response = ZaiPayment.users.card_account('user_id')
-
-# List user's BPay accounts
-response = ZaiPayment.users.bpay_accounts('user_id')
-```
+Manage payin (buyer) and payout (seller/merchant) users.
 
 **📚 Documentation:**
 - 📖 [User Management Guide](docs/users.md) - Complete guide for payin and payout users
@@ -173,69 +99,25 @@ response = ZaiPayment.users.bpay_accounts('user_id')
 
 ### Items
 
-Manage transactions/payments between buyers and sellers:
-
-```ruby
-# Create an item
-response = ZaiPayment.items.create(
-  name: "Product Purchase",
-  amount: 10000, # Amount in cents ($100.00)
-  payment_type: 2, # Credit card
-  buyer_id: "buyer-123",
-  seller_id: "seller-456",
-  description: "Purchase of premium product",
-  currency: "AUD",
-  tax_invoice: true
-)
-
-# List items
-response = ZaiPayment.items.list(limit: 20, offset: 0)
-
-# Get item details
-response = ZaiPayment.items.show('item_id')
-
-# Update item
-response = ZaiPayment.items.update('item_id', name: 'Updated Name')
-
-# Get item status
-response = ZaiPayment.items.show_status('item_id')
-
-# Get buyer/seller details
-response = ZaiPayment.items.show_buyer('item_id')
-response = ZaiPayment.items.show_seller('item_id')
-
-# List transactions
-response = ZaiPayment.items.list_transactions('item_id')
-```
+Manage transactions/payments between buyers and sellers.
 
 **📚 Documentation:**
 - 📖 [Item Management Guide](docs/items.md) - Complete guide for creating and managing items
 - 💡 [Item Examples](examples/items.md) - Real-world usage patterns and complete workflows
 - 🔗 [Zai: Items API Reference](https://developer.hellozai.com/reference/listitems)
 
-### Token Auth
+### Bank Accounts
 
-Generate secure tokens for collecting bank and card account information:
+Manage bank accounts for Australian and UK users, with routing number validation.
 
-```ruby
-# Generate a bank token (for collecting bank account details)
-response = ZaiPayment.token_auths.generate(
-  user_id: "seller-68611249",
-  token_type: "bank"
-)
-
-token = response.data['token_auth']['token']
-# Use this token with PromisePay.js on the frontend
-
-# Generate a card token (for collecting credit card details)
-response = ZaiPayment.token_auths.generate(
-  user_id: "buyer-12345",
-  token_type: "card"
-)
-
-token = response.data['token_auth']['token']
-# Use this token with PromisePay.js on the frontend
-```
+**📚 Documentation:**
+- 📖 [Bank Account Management Guide](docs/bank_accounts.md) - Complete guide for bank accounts
+- 💡 [Bank Account Examples](examples/bank_accounts.md) - Real-world patterns and integration
+- 🔗 [Zai: Bank Accounts API Reference](https://developer.hellozai.com/reference/showbankaccount)
+
+### Token Auth
+
+Generate secure tokens for collecting bank and card account information.
 
 **📚 Documentation:**
 - 💡 [Token Auth Examples](examples/token_auths.md) - Complete integration guide with PromisePay.js
@@ -243,24 +125,7 @@ token = response.data['token_auth']['token']
 
 ### Webhooks
 
-Manage webhook endpoints:
-
-```ruby
-# List webhooks
-response = ZaiPayment.webhooks.list
-webhooks = response.data
-
-# Create a webhook
-response = ZaiPayment.webhooks.create(
-  url: 'https://example.com/webhooks/zai',
-  object_type: 'transactions',
-  enabled: true
-)
-
-# Secure your webhooks with signature verification
-secret_key = SecureRandom.alphanumeric(32)
-ZaiPayment.webhooks.create_secret_key(secret_key: secret_key)
-```
+Manage webhook endpoints with secure signature verification.
 
 **📚 Documentation:**
 - 📖 [Webhook Examples & Complete Guide](examples/webhooks.md) - Full CRUD operations and patterns
@@ -301,6 +166,7 @@ end
 | ✅ Webhooks                     | CRUD for webhook endpoints        | Done           |
 | ✅ Users                        | Manage PayIn / PayOut users       | Done           |
 | ✅ Items                        | Transactions/payments (CRUD)      | Done           |
+| ✅ Bank Accounts                | AU/UK bank accounts + validation  | Done           |
 | ✅ Token Auth                   | Generate bank/card tokens         | Done           |
 | 💳 Payments                     | Single and recurring payments     | 🚧 In progress |
 | 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
@@ -360,12 +226,14 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 - [**Authentication Guide**](docs/authentication.md) - Two approaches to getting tokens, automatic management
 - [**User Management Guide**](docs/users.md) - Managing payin and payout users
 - [**Item Management Guide**](docs/items.md) - Creating and managing transactions/payments
+- [**Bank Account Guide**](docs/bank_accounts.md) - Managing bank accounts for AU/UK users
 - [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
 - [**Documentation Index**](docs/readme.md) - Full documentation navigation
 
 ### Examples & Patterns
 - [User Examples](examples/users.md) - Real-world user management patterns
 - [Item Examples](examples/items.md) - Transaction and payment workflows
+- [Bank Account Examples](examples/bank_accounts.md) - Bank account integration patterns
 - [Token Auth Examples](examples/token_auths.md) - Secure token generation and integration
 - [Webhook Examples](examples/webhooks.md) - Webhook integration patterns
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -68,6 +68,7 @@ files:
 - contributing.md
 - docs/architecture.md
 - docs/authentication.md
+- docs/bank_accounts.md
 - docs/items.md
 - docs/readme.md
 - docs/token_auths.md
@@ -77,6 +78,7 @@ files:
 - docs/webhook_security_quickstart.md
 - docs/webhook_signature.md
 - docs/webhooks.md
+- examples/bank_accounts.md
 - examples/items.md
 - examples/rails_card_payment.md
 - examples/token_auths.md
@@ -91,6 +93,7 @@ files:
 - lib/zai_payment/client.rb
 - lib/zai_payment/config.rb
 - lib/zai_payment/errors.rb
+- lib/zai_payment/resources/bank_account.rb
 - lib/zai_payment/resources/item.rb
 - lib/zai_payment/resources/token_auth.rb
 - lib/zai_payment/resources/user.rb