zai_payment 2.3.2 → 2.5.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.3.2
+  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
@@ -99,7 +102,6 @@ files:
 - lib/zai_payment/version.rb
 - readme.md
 - sig/zai_payment.rbs
-- token_auth_implementation_summary.md
 homepage: https://github.com/Sentia/zai-payment
 licenses:
 - MIT

data/token_auth_implementation_summary.md

@@ -1,249 +0,0 @@
-# Token Auth API Implementation Summary
-
-## Overview
-
-Successfully implemented the **Generate Token** endpoint from the Zai API (https://developer.hellozai.com/reference/generatetoken) to enable secure bank and card account data collection.
-
-## What Was Implemented
-
-### 1. Core Resource Implementation
-
-**File:** `lib/zai_payment/resources/token_auth.rb`
-
-- Created `TokenAuth` resource class following the project's resource pattern
-- Implemented `generate(user_id:, token_type:)` method
-- Added token type validation (bank or card)
-- Added user ID validation
-- Support for case-insensitive token types
-- Default token type: 'bank'
-
-**Key Features:**
-```ruby
-# Generate a bank token (default)
-ZaiPayment.token_auths.generate(user_id: "seller-123")
-
-# Generate a card token
-ZaiPayment.token_auths.generate(user_id: "buyer-123", token_type: "card")
-```
-
-### 2. Module Integration
-
-**File:** `lib/zai_payment.rb`
-
-- Added `require_relative` for token_auth resource
-- Added `token_auths` accessor method
-- Configured to use `core_base` endpoint (https://test.api.promisepay.com)
-
-### 3. Test Suite
-
-**File:** `spec/zai_payment/resources/token_auth_spec.rb`
-
-- 15 comprehensive test cases covering:
-  - Bank token generation
-  - Card token generation
-  - Default token type behavior
-  - Validation errors (nil, empty, whitespace, invalid types)
-  - Case-insensitive token types
-  - Client initialization
-  - Constants verification
-- All tests passing with 95.22% line coverage
-- Follows project's testing pattern using Faraday test stubs
-- RuboCop compliant
-
-### 4. Documentation
-
-**File:** `examples/token_auths.md` (600+ lines)
-
-Comprehensive examples including:
-- Basic usage patterns
-- Bank token collection workflows
-- Card token collection workflows
-- Rails controller integration
-- Service object pattern
-- Frontend integration with PromisePay.js
-- Complete payment flow examples
-- Error handling strategies
-- Retry logic with exponential backoff
-- Security best practices:
-  - Token expiry management
-  - Audit logging
-  - Rate limiting protection
-
-**File:** `docs/token_auths.md` (500+ lines)
-
-Complete technical guide covering:
-- When to use Token Auth
-- How it works (flow diagram)
-- API methods reference
-- Token types (bank vs card) with use cases
-- Security considerations (PCI compliance, token lifecycle)
-- Integration guide (backend + frontend)
-- Error handling patterns
-- Best practices with code examples
-- Related resources and API references
-
-### 5. Version Updates
-
-**File:** `lib/zai_payment/version.rb`
-
-- Updated version from `2.0.2` to `2.1.0`
-- Follows semantic versioning (minor version bump for new feature)
-
-### 6. Changelog
-
-**File:** `changelog.md`
-
-Added comprehensive release notes for version 2.1.0:
-- Feature description
-- API methods
-- Documentation additions
-- Testing coverage
-- Link to full changelog
-
-### 7. README Updates
-
-**File:** `readme.md`
-
-- Added Token Auth to features list (🎫 emoji)
-- Added Token Auth section with quick examples
-- Updated roadmap (marked Token Auth as Done ✅)
-- Added documentation links in Examples & Patterns section
-
-### 8. Documentation Index
-
-**File:** `docs/readme.md`
-
-- Added token_auths.md to Architecture & Design section
-- Added Token Auth Examples to Examples section
-- Added Token Auth to Quick Links with guide, examples, and API reference
-- Updated documentation structure tree
-- Added tips for collecting payment data
-
-## API Endpoint
-
-**POST** `https://test.api.promisepay.com/token_auths`
-
-**Request Body:**
-```json
-{
-  "token_type": "bank",  // or "card"
-  "user_id": "seller-68611249"
-}
-```
-
-**Response:**
-```json
-{
-  "token_auth": {
-    "token": "tok_bank_abc123...",
-    "user_id": "seller-68611249",
-    "token_type": "bank",
-    "created_at": "2025-10-24T12:00:00Z",
-    "expires_at": "2025-10-24T13:00:00Z"
-  }
-}
-```
-
-## Usage Example
-
-```ruby
-# Configure the gem
-ZaiPayment.configure do |c|
-  c.environment   = :prelive
-  c.client_id     = ENV['ZAI_CLIENT_ID']
-  c.client_secret = ENV['ZAI_CLIENT_SECRET']
-  c.scope         = ENV['ZAI_OAUTH_SCOPE']
-end
-
-# Generate a card token for buyer
-response = ZaiPayment.token_auths.generate(
-  user_id: "buyer-12345",
-  token_type: "card"
-)
-
-token = response.data['token_auth']['token']
-# Send token to frontend for use with PromisePay.js
-```
-
-## Integration with PromisePay.js
-
-```javascript
-// Frontend (JavaScript)
-PromisePay.setToken(token_from_backend);
-
-PromisePay.createCardAccount({
-  card_number: '4111111111111111',
-  expiry_month: '12',
-  expiry_year: '2025',
-  cvv: '123'
-}, function(response) {
-  if (response.error) {
-    console.error('Error:', response.error);
-  } else {
-    const cardAccountId = response.card_accounts.id;
-    // Send cardAccountId back to backend
-  }
-});
-```
-
-## Test Results
-
-- **Total Tests:** 272 examples
-- **Failures:** 0
-- **Line Coverage:** 95.22% (518 / 544)
-- **Branch Coverage:** 80.79% (143 / 177)
-- **RuboCop:** No offenses detected
-
-## Files Created
-
-1. `lib/zai_payment/resources/token_auth.rb` - Core resource implementation
-2. `spec/zai_payment/resources/token_auth_spec.rb` - Test suite
-3. `examples/token_auths.md` - Comprehensive usage examples
-4. `docs/token_auths.md` - Technical documentation
-
-## Files Modified
-
-1. `lib/zai_payment.rb` - Added token_auths accessor
-2. `lib/zai_payment/version.rb` - Version bump to 2.1.0
-3. `changelog.md` - Added 2.1.0 release notes
-4. `readme.md` - Added Token Auth documentation
-5. `docs/readme.md` - Updated documentation index
-
-## Security Considerations
-
-- **PCI Compliance:** Tokens enable PCI-compliant card data collection without sensitive data touching your server
-- **Token Expiration:** Tokens have limited lifespan (typically 1 hour)
-- **Single-use:** Tokens should be generated fresh for each session
-- **User-specific:** Each token is tied to a specific user ID
-- **Type-specific:** Bank tokens only for bank accounts, card tokens only for cards
-- **HTTPS Required:** All communication over secure HTTPS
-
-## Next Steps
-
-The Token Auth implementation is complete and ready for use. Developers can now:
-
-1. Generate tokens for buyers to collect credit card information
-2. Generate tokens for sellers to collect bank account details
-3. Integrate with PromisePay.js for secure frontend data collection
-4. Process payments without handling sensitive payment data directly
-
-## Related APIs
-
-This implementation complements existing resources:
-- **Users API** - Create users before generating tokens
-- **Items API** - Use payment accounts to create transactions
-- **Webhooks API** - Receive notifications about payment events
-
-## Documentation Links
-
-- **API Reference:** https://developer.hellozai.com/reference/generatetoken
-- **Examples:** [examples/token_auths.md](examples/token_auths.md)
-- **Guide:** [docs/token_auths.md](docs/token_auths.md)
-- **PromisePay.js:** https://developer.hellozai.com/docs/promisepay-js
-
----
-
-**Implementation Date:** October 24, 2025  
-**Version:** 2.1.0  
-**Status:** ✅ Complete and tested
-