zai_payment 2.4.0 → 2.6.0

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.6.0
 platform: ruby
 authors:
 - Eddy Jaga
@@ -68,6 +68,8 @@ files:
 - contributing.md
 - docs/architecture.md
 - docs/authentication.md
+- docs/bank_accounts.md
+- docs/bpay_accounts.md
 - docs/items.md
 - docs/readme.md
 - docs/token_auths.md
@@ -77,13 +79,13 @@ files:
 - docs/webhook_security_quickstart.md
 - docs/webhook_signature.md
 - docs/webhooks.md
+- examples/bank_accounts.md
+- examples/bpay_accounts.md
 - examples/items.md
 - examples/rails_card_payment.md
 - examples/token_auths.md
 - examples/users.md
 - examples/webhooks.md
-- implementation.md
-- implementation_summary.md
 - lib/zai_payment.rb
 - lib/zai_payment/auth/token_provider.rb
 - lib/zai_payment/auth/token_store.rb
@@ -91,6 +93,8 @@ 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/bpay_account.rb
 - lib/zai_payment/resources/item.rb
 - lib/zai_payment/resources/token_auth.rb
 - lib/zai_payment/resources/user.rb

data/implementation.md

@@ -1,304 +0,0 @@
-# User Management Implementation Summary
-
-## Overview
-
-This document summarizes the implementation of the User Management feature for the Zai Payment Ruby library.
-
-## Implementation Date
-
-October 23, 2025
-
-## What Was Implemented
-
-### 1. User Resource Class (`lib/zai_payment/resources/user.rb`)
-
-A comprehensive User resource that provides CRUD operations for managing both payin (buyer) and payout (seller/merchant) users.
-
-**Key Features:**
-- ✅ List users with pagination
-- ✅ Show user details by ID
-- ✅ Create payin users (buyers)
-- ✅ Create payout users (sellers/merchants)
-- ✅ Update user information
-- ✅ Comprehensive validation for all user types
-- ✅ Support for all Zai API user fields
-
-**Supported Fields:**
-- Email, first name, last name (required)
-- Country (ISO 3166-1 alpha-3 code, required)
-- Address details (line1, line2, city, state, zip)
-- Contact information (mobile, phone)
-- Date of birth (DD/MM/YYYY format)
-- Government ID number
-- Device ID and IP address (for fraud prevention)
-- User type designation (payin/payout)
-
-**Validation:**
-- Required field validation
-- Email format validation
-- Country code validation (3-letter ISO codes)
-- Date of birth format validation (DD/MM/YYYY)
-- User type validation (payin/payout)
-
-### 2. Client Updates (`lib/zai_payment/client.rb`)
-
-**Changes:**
-- Added `base_endpoint` parameter to constructor
-- Updated `base_url` method to support multiple API endpoints
-- Users API uses `core_base` endpoint
-- Webhooks API uses `va_base` endpoint
-
-### 3. Response Updates (`lib/zai_payment/response.rb`)
-
-**Changes:**
-- Updated `data` method to handle both `webhooks` and `users` response formats
-- Maintains backward compatibility with existing webhook code
-
-### 4. Main Module Integration (`lib/zai_payment.rb`)
-
-**Changes:**
-- Added `require` for User resource
-- Added `users` accessor method
-- Properly configured User resource to use `core_base` endpoint
-
-### 5. Comprehensive Test Suite (`spec/zai_payment/resources/user_spec.rb`)
-
-**Test Coverage:**
-- List users with pagination
-- Show user details
-- Create payin users with various configurations
-- Create payout users with required fields
-- Validation error handling
-- API error handling
-- Update operations
-- User type validation
-- Integration with main module
-
-**Test Statistics:**
-- 40+ test cases
-- Covers all CRUD operations
-- Tests both success and error scenarios
-- Validates all field types
-- Tests integration points
-
-### 6. Documentation
-
-#### User Guide (`docs/users.md`)
-Comprehensive guide covering:
-- Overview of payin vs payout users
-- Required fields for each user type
-- Complete API reference
-- Field reference table
-- Error handling patterns
-- Best practices
-- Response structures
-- Complete examples
-
-#### Usage Examples (`examples/users.md`)
-Practical examples including:
-- Basic payin user creation
-- Complete payin user profiles
-- Progressive profile building
-- Individual payout users
-- International users (AU, UK, US)
-- List and pagination
-- Update operations
-- Error handling patterns
-- Rails integration example
-- Batch operations
-- User profile validation helper
-- RSpec integration tests
-- Common patterns with retry logic
-
-#### readme Updates (`readme.md`)
-- Added Users section with quick examples
-- Updated roadmap to mark Users as "Done"
-- Added documentation links
-- Updated Getting Started section
-
-## API Endpoints
-
-The implementation works with the following Zai API endpoints:
-
-- `GET /users` - List users
-- `GET /users/:id` - Show user
-- `POST /users` - Create user
-- `PATCH /users/:id` - Update user
-
-## Usage Examples
-
-### Create a Payin User (Buyer)
-
-```ruby
-response = ZaiPayment.users.create(
-  email: 'buyer@example.com',
-  first_name: 'John',
-  last_name: 'Doe',
-  country: 'USA',
-  mobile: '+1234567890'
-)
-
-user_id = response.data['id']
-```
-
-### Create a Payout User (Seller/Merchant)
-
-```ruby
-response = ZaiPayment.users.create(
-  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',
-  mobile: '+61412345678'
-)
-
-seller_id = response.data['id']
-```
-
-### List Users
-
-```ruby
-response = ZaiPayment.users.list(limit: 10, offset: 0)
-users = response.data
-```
-
-### Show User
-
-```ruby
-response = ZaiPayment.users.show('user_id')
-user = response.data
-```
-
-### Update User
-
-```ruby
-response = ZaiPayment.users.update(
-  'user_id',
-  mobile: '+9876543210',
-  address_line1: '789 New St'
-)
-```
-
-## Key Differences: Payin vs Payout Users
-
-### Payin User (Buyer) Requirements
-**Required:**
-- Email, first name, last name, country
-- Device ID and IP address (when charging)
-
-**Recommended:**
-- Address, city, state, zip
-- Mobile, DOB
-
-### Payout User (Seller/Merchant) Requirements
-**Required:**
-- Email, first name, last name, country
-- Address, city, state, zip
-- Date of birth (DD/MM/YYYY format)
-
-**Recommended:**
-- Mobile, government number
-
-## Validation Rules
-
-1. **Email**: Must be valid email format
-2. **Country**: Must be 3-letter ISO 3166-1 alpha-3 code (e.g., USA, AUS, GBR)
-3. **Date of Birth**: Must be DD/MM/YYYY format (e.g., 01/01/1990)
-4. **User Type**: Must be 'payin' or 'payout' (optional field)
-
-## Error Handling
-
-The implementation provides proper error handling for:
-- `ValidationError` - Missing or invalid fields
-- `UnauthorizedError` - Authentication failures
-- `NotFoundError` - User not found
-- `ApiError` - General API errors
-- `ConnectionError` - Network issues
-- `TimeoutError` - Request timeouts
-
-## Best Practices Implemented
-
-1. **Progressive Profile Building**: Create users with minimal info, update later
-2. **Proper Validation**: Validate data before API calls
-3. **Error Recovery**: Handle errors gracefully with proper error classes
-4. **Type Safety**: Validate user types and field formats
-5. **Documentation**: Comprehensive guides and examples
-6. **Testing**: Extensive test coverage for all scenarios
-
-## Files Created/Modified
-
-### Created Files:
-1. `/lib/zai_payment/resources/user.rb` - User resource class
-2. `/spec/zai_payment/resources/user_spec.rb` - Test suite
-3. `/docs/users.md` - User management guide
-4. `/examples/users.md` - Usage examples
-
-### Modified Files:
-1. `/lib/zai_payment/client.rb` - Added endpoint support
-2. `/lib/zai_payment/response.rb` - Added users data handling
-3. `/lib/zai_payment.rb` - Integrated User resource
-4. `/readme.md` - Added Users section and updated roadmap
-
-## Code Quality
-
-- ✅ No linter errors
-- ✅ Follows existing code patterns
-- ✅ Comprehensive test coverage
-- ✅ Well-documented with YARD comments
-- ✅ Follows Ruby best practices
-- ✅ Consistent with webhook implementation
-
-## Architecture Decisions
-
-1. **Endpoint Routing**: Users use `core_base`, webhooks use `va_base`
-2. **Validation Strategy**: Client-side validation before API calls
-3. **Field Mapping**: Direct 1:1 mapping with Zai API fields
-4. **Error Handling**: Leverage existing error class hierarchy
-5. **Testing Approach**: Match webhook test patterns
-
-## Integration Points
-
-The User resource integrates seamlessly with:
-- Authentication system (OAuth2 tokens)
-- Error handling framework
-- Response wrapper
-- Configuration management
-- Testing infrastructure
-
-## Next Steps
-
-The implementation is complete and ready for use. Recommended next steps:
-
-1. ✅ Run the full test suite
-2. ✅ Review documentation
-3. ✅ Try examples in development environment
-4. Consider adding:
-   - Company user support (for payout users)
-   - User verification status checking
-   - Bank account associations
-   - Payment method attachments
-
-## References
-
-- [Zai: Onboarding a Payin User](https://developer.hellozai.com/docs/onboarding-a-pay-in-user)
-- [Zai: Onboarding a Payout User](https://developer.hellozai.com/docs/onboarding-a-pay-out-user)
-- [Zai API Reference](https://developer.hellozai.com/reference)
-
-## Support
-
-For questions or issues:
-1. Check the documentation in `/docs/users.md`
-2. Review examples in `/examples/users.md`
-3. Run tests: `bundle exec rspec spec/zai_payment/resources/user_spec.rb`
-4. Refer to Zai Developer Portal: https://developer.hellozai.com/
-
----
-
-**Implementation completed successfully! 🎉**
-
-All CRUD operations for User management are now available in the ZaiPayment gem, following best practices and maintaining consistency with the existing codebase.