zai_payment 2.7.0 → 2.8.0

data/lib/zai_payment/resources/pay_id.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # PayID resource for managing Zai PayID registrations
+    #
+    # @see https://developer.hellozai.com/reference/registerpayid
+    class PayId
+      attr_reader :client
+
+      # Map of attribute keys to API field names for create
+      CREATE_FIELD_MAPPING = {
+        pay_id: :pay_id,
+        type: :type,
+        details: :details
+      }.freeze
+
+      # Valid PayID types
+      VALID_TYPES = %w[EMAIL].freeze
+
+      # Valid PayID statuses for update
+      VALID_STATUSES = %w[deregistered].freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new(base_endpoint: :va_base)
+      end
+
+      # Register a PayID for a given Virtual Account
+      #
+      # @param virtual_account_id [String] the virtual account ID
+      # @param attributes [Hash] PayID attributes
+      # @option attributes [String] :pay_id (Required) The PayID being registered (max 256 chars)
+      # @option attributes [String] :type (Required) The type of PayID ('EMAIL')
+      # @option attributes [Hash] :details (Required) Additional details
+      # @option details [String] :pay_id_name Name to identify the entity (1-140 chars)
+      # @option details [String] :owner_legal_name Full legal account name (1-140 chars)
+      # @return [Response] the API response containing PayID details
+      #
+      # @example Register an EMAIL PayID
+      #   pay_ids = ZaiPayment::Resources::PayId.new
+      #   response = pay_ids.create(
+      #     '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
+      #     pay_id: 'jsmith@mydomain.com',
+      #     type: 'EMAIL',
+      #     details: {
+      #       pay_id_name: 'J Smith',
+      #       owner_legal_name: 'Mr John Smith'
+      #     }
+      #   )
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", ...}
+      #
+      # @see https://developer.hellozai.com/reference/registerpayid
+      def create(virtual_account_id, **attributes)
+        validate_id!(virtual_account_id, 'virtual_account_id')
+        validate_create_attributes!(attributes)
+
+        body = build_create_body(attributes)
+        client.post("/virtual_accounts/#{virtual_account_id}/pay_ids", body: body)
+      end
+
+      # Show a specific PayID
+      #
+      # @param pay_id_id [String] the PayID ID
+      # @return [Response] the API response containing PayID details
+      #
+      # @example Get PayID details
+      #   pay_ids = ZaiPayment::Resources::PayId.new
+      #   response = pay_ids.show('46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", ...}
+      #
+      # @see https://developer.hellozai.com/reference/retrieveapayid
+      def show(pay_id_id)
+        validate_id!(pay_id_id, 'pay_id_id')
+        client.get("/pay_ids/#{pay_id_id}")
+      end
+
+      # Update Status for a PayID
+      #
+      # Update the status of a PayID. Currently, this endpoint only supports deregistering
+      # PayIDs by setting the status to 'deregistered'. This is an asynchronous operation
+      # that returns a 202 Accepted response.
+      #
+      # @param pay_id_id [String] the PayID ID
+      # @param status [String] the new status (must be 'deregistered')
+      # @return [Response] the API response containing the operation status
+      #
+      # @example Deregister a PayID
+      #   pay_ids = ZaiPayment::Resources::PayId.new
+      #   response = pay_ids.update_status(
+      #     '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
+      #     'deregistered'
+      #   )
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", "message" => "...", ...}
+      #
+      # @see https://developer.hellozai.com/reference/updatepayidstatus
+      def update_status(pay_id_id, status)
+        validate_id!(pay_id_id, 'pay_id_id')
+        validate_status!(status)
+
+        body = { status: status }
+        client.patch("/pay_ids/#{pay_id_id}/status", 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_pay_id!(attributes[:pay_id])
+        validate_type!(attributes[:type])
+        validate_details!(attributes[:details])
+      end
+
+      def validate_pay_id!(pay_id)
+        if pay_id.nil? || pay_id.to_s.strip.empty?
+          raise Errors::ValidationError, 'pay_id is required and cannot be blank'
+        end
+
+        return unless pay_id.to_s.length > 256
+
+        raise Errors::ValidationError, 'pay_id must be 256 characters or less'
+      end
+
+      def validate_type!(type)
+        raise Errors::ValidationError, 'type is required and cannot be blank' if type.nil? || type.to_s.strip.empty?
+
+        return if VALID_TYPES.include?(type.to_s.upcase)
+
+        raise Errors::ValidationError,
+              "type must be one of: #{VALID_TYPES.join(', ')}, got '#{type}'"
+      end
+
+      def validate_details!(details)
+        raise Errors::ValidationError, 'details is required and must be a hash' if details.nil? || !details.is_a?(Hash)
+
+        validate_pay_id_name!(details[:pay_id_name])
+        validate_owner_legal_name!(details[:owner_legal_name])
+      end
+
+      def validate_pay_id_name!(pay_id_name)
+        return unless pay_id_name
+
+        raise Errors::ValidationError, 'pay_id_name cannot be empty when provided' if pay_id_name.to_s.empty?
+
+        return unless pay_id_name.to_s.length > 140
+
+        raise Errors::ValidationError, 'pay_id_name must be between 1 and 140 characters'
+      end
+
+      def validate_owner_legal_name!(owner_legal_name)
+        return unless owner_legal_name
+
+        raise Errors::ValidationError, 'owner_legal_name cannot be empty when provided' if owner_legal_name.to_s.empty?
+
+        return unless owner_legal_name.to_s.length > 140
+
+        raise Errors::ValidationError, 'owner_legal_name must be between 1 and 140 characters'
+      end
+
+      def validate_status!(status)
+        raise Errors::ValidationError, 'status cannot be blank' if status.nil? || status.to_s.strip.empty?
+
+        return if VALID_STATUSES.include?(status.to_s)
+
+        raise Errors::ValidationError,
+              "status must be 'deregistered', got '#{status}'"
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def build_create_body(attributes)
+        body = {}
+
+        # Add pay_id
+        body[:pay_id] = attributes[:pay_id] if attributes[:pay_id]
+
+        # Add type (convert to uppercase to match API expectations)
+        body[:type] = attributes[:type].to_s.upcase if attributes[:type]
+
+        # Add details
+        if attributes[:details].is_a?(Hash)
+          body[:details] = {}
+          details = attributes[:details]
+
+          body[:details][:pay_id_name] = details[:pay_id_name] if details[:pay_id_name]
+          body[:details][:owner_legal_name] = details[:owner_legal_name] if details[:owner_legal_name]
+        end
+
+        body
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/zai_payment/resources/virtual_account.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module ZaiPayment
+  module Resources
+    # VirtualAccount resource for managing Zai virtual accounts
+    #
+    # @see https://developer.hellozai.com/reference/createvirtualaccount
+    class VirtualAccount
+      attr_reader :client
+
+      # Map of attribute keys to API field names for create
+      CREATE_FIELD_MAPPING = {
+        account_name: :account_name,
+        aka_names: :aka_names
+      }.freeze
+
+      def initialize(client: nil)
+        @client = client || Client.new(base_endpoint: :va_base)
+      end
+
+      # List Virtual Accounts for a given Wallet Account
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @return [Response] the API response containing array of virtual accounts
+      #
+      # @example List virtual accounts
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.list('ae07556e-22ef-11eb-adc1-0242ac120002')
+      #   response.data # => [{"id" => "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", ...}, ...]
+      #   response.meta # => {"total" => 2}
+      #
+      # @see https://developer.hellozai.com/reference
+      def list(wallet_account_id)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        client.get("/wallet_accounts/#{wallet_account_id}/virtual_accounts")
+      end
+
+      # Show a specific Virtual Account
+      #
+      # @param virtual_account_id [String] the virtual account ID
+      # @return [Response] the API response containing virtual account details
+      #
+      # @example Get virtual account details
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.show('46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", ...}
+      #
+      # @see https://developer.hellozai.com/reference/showvirtualaccount
+      def show(virtual_account_id)
+        validate_id!(virtual_account_id, 'virtual_account_id')
+        client.get("/virtual_accounts/#{virtual_account_id}")
+      end
+
+      # Create a Virtual Account for a given Wallet Account
+      #
+      # @param wallet_account_id [String] the wallet account ID
+      # @param attributes [Hash] virtual account attributes
+      # @option attributes [String] :account_name A name given for the Virtual Account (max 140 chars)
+      # @option attributes [Array<String>] :aka_names A list of AKA Names (0 to 3 items)
+      # @return [Response] the API response containing virtual account details
+      #
+      # @example Create a virtual account
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.create(
+      #     'ae07556e-22ef-11eb-adc1-0242ac120002',
+      #     account_name: 'Real Estate Agency X',
+      #     aka_names: ['Realestate agency X']
+      #   )
+      #   response.data # => {"id" => "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", ...}
+      #
+      # @see https://developer.hellozai.com/reference/listvirtualaccountbywalletaccount
+      def create(wallet_account_id, **attributes)
+        validate_id!(wallet_account_id, 'wallet_account_id')
+        validate_create_attributes!(attributes)
+
+        body = build_create_body(attributes)
+        client.post("/wallet_accounts/#{wallet_account_id}/virtual_accounts", body: body)
+      end
+
+      # Update AKA Names for a Virtual Account
+      #
+      # Replace the list of AKA Names for a Virtual Account. This completely replaces
+      # the existing AKA names with the new list provided.
+      #
+      # @param virtual_account_id [String] the virtual account ID
+      # @param aka_names [Array<String>] array of AKA names (0 to 3 items)
+      # @return [Response] the API response containing updated virtual account details
+      #
+      # @example Update AKA names
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.update_aka_names(
+      #     '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
+      #     ['New Name 1', 'New Name 2']
+      #   )
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", ...}
+      #
+      # @see https://developer.hellozai.com/reference/updatevirtualaccountakaname
+      def update_aka_names(virtual_account_id, aka_names)
+        validate_id!(virtual_account_id, 'virtual_account_id')
+        validate_aka_names!(aka_names)
+
+        body = { aka_names: aka_names }
+        client.patch("/virtual_accounts/#{virtual_account_id}/aka_names", body: body)
+      end
+
+      # Update Account Name for a Virtual Account
+      #
+      # Change the name of a Virtual Account. This is used in CoP lookups.
+      #
+      # @param virtual_account_id [String] the virtual account ID
+      # @param account_name [String] the new account name (max 140 characters)
+      # @return [Response] the API response containing updated virtual account details
+      #
+      # @example Update account name
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.update_account_name(
+      #     '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
+      #     'New Real Estate Agency Name'
+      #   )
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", ...}
+      #
+      # @see https://developer.hellozai.com/reference/updatevirtualaccountaccountname
+      def update_account_name(virtual_account_id, account_name)
+        validate_id!(virtual_account_id, 'virtual_account_id')
+        validate_account_name!(account_name)
+
+        body = { account_name: account_name }
+        client.patch("/virtual_accounts/#{virtual_account_id}/account_name", body: body)
+      end
+
+      # Update Status for a Virtual Account
+      #
+      # Close a Virtual Account. Once closed, the account cannot be reopened and will
+      # no longer be able to receive payments. This operation is asynchronous and returns
+      # a 202 Accepted response.
+      #
+      # @param virtual_account_id [String] the virtual account ID
+      # @param status [String] the new status (must be 'closed')
+      # @return [Response] the API response containing the operation status
+      #
+      # @example Close a virtual account
+      #   virtual_accounts = ZaiPayment::Resources::VirtualAccount.new
+      #   response = virtual_accounts.update_status(
+      #     '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
+      #     'closed'
+      #   )
+      #   response.data # => {"id" => "46deb476-c1a6-41eb-8eb7-26a695bbe5bc", "message" => "...", ...}
+      #
+      # @see https://developer.hellozai.com/reference/updatevirtualaccount
+      def update_status(virtual_account_id, status)
+        validate_id!(virtual_account_id, 'virtual_account_id')
+        validate_status!(status)
+
+        body = { status: status }
+        client.patch("/virtual_accounts/#{virtual_account_id}/status", 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)
+        # Only validate if attributes are actually provided (not nil)
+        validate_account_name!(attributes[:account_name]) if attributes.key?(:account_name)
+        validate_aka_names!(attributes[:aka_names]) if attributes.key?(:aka_names)
+      end
+
+      def validate_account_name!(account_name)
+        if account_name.nil? || account_name.to_s.strip.empty?
+          raise Errors::ValidationError, 'account_name cannot be blank'
+        end
+
+        return unless account_name.to_s.length > 140
+
+        raise Errors::ValidationError, 'account_name must be 140 characters or less'
+      end
+
+      def validate_aka_names!(aka_names)
+        raise Errors::ValidationError, 'aka_names must be an array' unless aka_names.is_a?(Array)
+
+        return unless aka_names.length > 3
+
+        raise Errors::ValidationError, 'aka_names must contain between 0 and 3 items'
+      end
+
+      def validate_status!(status)
+        raise Errors::ValidationError, 'status cannot be blank' if status.nil? || status.to_s.strip.empty?
+
+        return if status.to_s == 'closed'
+
+        raise Errors::ValidationError, "status must be 'closed', got '#{status}'"
+      end
+
+      def build_create_body(attributes)
+        body = {}
+
+        attributes.each do |key, value|
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          api_field = CREATE_FIELD_MAPPING[key]
+          body[api_field] = value if api_field
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/zai_payment/response.rb

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

data/lib/zai_payment/version.rb

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

data/lib/zai_payment.rb

@@ -18,6 +18,8 @@ require_relative 'zai_payment/resources/bank_account'
 require_relative 'zai_payment/resources/bpay_account'
 require_relative 'zai_payment/resources/batch_transaction'
 require_relative 'zai_payment/resources/wallet_account'
+require_relative 'zai_payment/resources/virtual_account'
+require_relative 'zai_payment/resources/pay_id'
 
 module ZaiPayment
   class << self
@@ -81,5 +83,15 @@ module ZaiPayment
     def wallet_accounts
       @wallet_accounts ||= Resources::WalletAccount.new(client: Client.new(base_endpoint: :core_base))
     end
+
+    # @return [ZaiPayment::Resources::VirtualAccount] virtual_account resource instance
+    def virtual_accounts
+      @virtual_accounts ||= Resources::VirtualAccount.new
+    end
+
+    # @return [ZaiPayment::Resources::PayId] pay_id resource instance
+    def pay_ids
+      @pay_ids ||= Resources::PayId.new
+    end
   end
 end

data/readme.md

@@ -24,6 +24,8 @@ A lightweight and extensible Ruby client for the **Zai (AssemblyPay)** API — s
 - 🏦 **Bank Account Management** - Complete CRUD + validation for AU/UK bank accounts  
 - 💳 **BPay Account Management** - Manage BPay accounts for Australian bill payments  
 - 💼 **Wallet Account Management** - Show wallet accounts, check balances, and pay bills via BPay  
+- 🏦 **Virtual Accounts** - Complete virtual account management with PayTo and BPay support  
+- 💳 **PayID Management** - Create and manage PayIDs for Australian NPP payments  
 - 🎫 **Token Auth** - Generate secure tokens for bank and card account data collection  
 - 🪝 **Webhooks** - Full CRUD + secure signature verification (HMAC SHA256)  
 - 🧪 **Batch Transactions** - Prelive-only endpoints for testing batch transaction flows  
@@ -160,6 +162,23 @@ if payment_response.success?
 end
 ```
 
+### Virtual Accounts
+
+Manage virtual accounts with support for AKA names and Confirmation of Payee (CoP) lookups.
+
+**📚 Documentation:**
+- 📖 [Virtual Account Management Guide](docs/virtual_accounts.md) - Complete guide for virtual accounts
+- 💡 [Virtual Account Examples](examples/virtual_accounts.md) - Real-world patterns and workflows
+- 🔗 [Zai: Virtual Accounts API Reference](https://developer.hellozai.com/reference/overview-va)
+
+### PayID
+
+Register and manage PayIDs (EMAIL type) for Australian NPP (New Payments Platform) payments.
+
+**📚 Documentation:**
+- 📖 [PayID Management Guide](docs/pay_ids.md) - Complete guide for PayID registration
+- 💡 [PayID Examples](examples/pay_ids.md) - Real-world patterns and workflows
+
 ### Token Auth
 
 Generate secure tokens for collecting bank and card account information.
@@ -246,7 +265,8 @@ end
 | ✅ Token Auth                   | Generate bank/card tokens         | Done           |
 | ✅ Batch Transactions (Prelive) | Simulate batch processing flows   | Done           |
 | ✅ Payments                     | Single and recurring payments     | Done           |
-| 🏦 Virtual Accounts (VA / PIPU) | Manage virtual accounts & PayTo   | ⏳ Planned      |
+| ✅ Virtual Accounts             | Manage virtual accounts & PayTo   | Done           |
+| ✅ PayID                        | Create and manage PayIDs          | Done           |
 
 ## 🧪 Development
 
@@ -305,6 +325,8 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 - [**Bank Account Guide**](docs/bank_accounts.md) - Managing bank accounts for AU/UK users
 - [**BPay Account Guide**](docs/bpay_accounts.md) - Managing BPay accounts for Australian bill payments
 - [**Wallet Account Guide**](docs/wallet_accounts.md) - Managing wallet accounts, checking balances, and paying bills
+- [**Virtual Account Guide**](docs/virtual_accounts.md) - Managing virtual accounts with PayTo and BPay support
+- [**PayID Guide**](docs/pay_ids.md) - Creating and managing PayIDs for Australian NPP payments
 - [**Webhook Examples**](examples/webhooks.md) - Complete webhook usage guide
 - [**Documentation Index**](docs/readme.md) - Full documentation navigation
 
@@ -314,6 +336,8 @@ Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat
 - [Bank Account Examples](examples/bank_accounts.md) - Bank account integration patterns
 - [BPay Account Examples](examples/bpay_accounts.md) - BPay account integration patterns
 - [Wallet Account Examples](examples/wallet_accounts.md) - Wallet account and bill payment workflows
+- [Virtual Account Examples](examples/virtual_accounts.md) - Virtual account management and PayTo workflows
+- [PayID Examples](examples/pay_ids.md) - PayID creation and management workflows
 - [Token Auth Examples](examples/token_auths.md) - Secure token generation and integration
 - [Webhook Examples](examples/webhooks.md) - Webhook integration patterns
 - [Batch Transaction Examples](examples/batch_transactions.md) - Testing batch transaction flows (prelive only)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zai_payment
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -75,11 +75,13 @@ files:
 - docs/bpay_accounts.md
 - docs/direct_api_usage.md
 - docs/items.md
+- docs/pay_ids.md
 - docs/readme.md
 - docs/token_auths.md
 - docs/user_id_field.md
 - docs/user_quick_reference.md
 - docs/users.md
+- docs/virtual_accounts.md
 - docs/wallet_accounts.md
 - docs/webhook_security_quickstart.md
 - docs/webhook_signature.md
@@ -88,9 +90,11 @@ files:
 - examples/batch_transactions.md
 - examples/bpay_accounts.md
 - examples/items.md
+- examples/pay_ids.md
 - examples/rails_card_payment.md
 - examples/token_auths.md
 - examples/users.md
+- examples/virtual_accounts.md
 - examples/wallet_accounts.md
 - examples/webhooks.md
 - lib/zai_payment.rb
@@ -104,8 +108,10 @@ files:
 - lib/zai_payment/resources/batch_transaction.rb
 - lib/zai_payment/resources/bpay_account.rb
 - lib/zai_payment/resources/item.rb
+- lib/zai_payment/resources/pay_id.rb
 - lib/zai_payment/resources/token_auth.rb
 - lib/zai_payment/resources/user.rb
+- lib/zai_payment/resources/virtual_account.rb
 - lib/zai_payment/resources/wallet_account.rb
 - lib/zai_payment/resources/webhook.rb
 - lib/zai_payment/response.rb