zai_payment 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b608e4fd66f94a5cad5ed8cab447031e67cd61523d5bffa36a858d9e868a244
-  data.tar.gz: 1565178be12a4c07bbac95b9e913b57e59fe446f5de956bb994f173b157ed4a4
+  metadata.gz: 5c0f57b605f7a885cb3fcbb0e8b4554d782fd298444d49b57732d0214b0a8a14
+  data.tar.gz: 014e39994a1d9051b28d90deaec6407cd638de2ed7995509c0196ec25da6805a
 SHA512:
-  metadata.gz: 69b6546e10a89af5eb203e4ed08af91ab1eaacc7e5564073c60a66f059ef2cc61b94fbd0f508abd1a97e4ff5de836df99299786e49da473d9f39d43e4c65efa8
-  data.tar.gz: 8303047008ad3e9af60a4a15eba7ee984bc0a45aac3b2ee25e0bb3b6d5a492394d966db230ac454f919f7ccac29cdf1f63c6892b183df7711d0f56e5275d9190
+  metadata.gz: 24b3058ec5ee8e06b06f9444175a6a86e455a3ba08b2a5f40df990f5ab7beae812d05225e62802b1fd2e69acc37f9364f33d1dc89f37fb045c150c52ae18fd04
+  data.tar.gz: a2e4715f2f8e8630fe4ea03d13ad83318acf4fd09737266de497ecc889af22af84fc7edd0b8d6846658ebc50d4c49ed8d36ae0144190a0d79aeae88d6e398bce

data/badges/coverage.json

@@ -1 +1 @@
-{"schemaVersion": 1, "label": "coverage", "message": "97.0%", "color": "brightgreen"}
+{"schemaVersion": 1, "label": "coverage", "message": "97.39%", "color": "brightgreen"}

data/changelog.md

@@ -1,4 +1,105 @@
 ## [Released]
+
+## [2.6.0] - 2025-11-03
+
+### Added
+- **BPay Account Resource**: Complete BPay account management for Australian bill payments 💰
+  - `ZaiPayment.bpay_accounts.show(bpay_account_id)` - Get BPay account details including biller information
+  - `ZaiPayment.bpay_accounts.create(user_id:, account_name:, biller_code:, bpay_crn:)` - Create BPay account for disbursement destinations
+  - `ZaiPayment.bpay_accounts.redact(bpay_account_id)` - Redact (deactivate) a BPay account
+  - `ZaiPayment.bpay_accounts.show_user(bpay_account_id)` - Get user associated with a BPay account
+  - Validation for biller code (3-10 digits)
+  - Validation for BPay CRN (Customer Reference Number, 2-20 digits)
+  - Support for Australian bill payment disbursements
+  - Full RSpec test suite with 12 test examples across 4 describe blocks
+  - Comprehensive documentation in `docs/bpay_accounts.md`
+  - Practical examples in `examples/bpay_accounts.md`
+
+### Documentation
+- **BPay Accounts Guide** (`docs/bpay_accounts.md`):
+  - Complete guide for showing, creating, redacting BPay accounts, and retrieving associated users
+  - Detailed API reference for all four endpoints
+  - Response structure documentation with example payloads
+  - Validation rules for biller codes and BPay CRN formats
+  - Error handling documentation (ValidationError, NotFoundError)
+  - Four comprehensive use cases:
+    - Disbursement account setup for bill payments
+    - User verification before disbursement
+    - Deactivating old BPay accounts
+    - Managing multiple utility BPay accounts
+  - Important notes about BPay account usage and restrictions
+- **BPay Accounts Examples** (`examples/bpay_accounts.md`):
+  - Show BPay account examples (3 examples):
+    - Basic account retrieval with full details
+    - Error handling and status verification
+    - Pre-disbursement verification workflow
+  - Show BPay account user examples (3 examples):
+    - User information retrieval
+    - User verification before disbursement
+    - Contact information extraction for notifications
+  - Redact BPay account examples (3 examples):
+    - Basic redaction with response handling
+    - Comprehensive error handling
+    - Verification before redacting workflow
+  - Create BPay account examples (3 examples):
+    - Basic account creation
+    - Error handling patterns
+    - Multiple utility account setup
+  - Four common patterns:
+    - Retrieve and verify before disbursement
+    - Complete onboarding workflow with user creation
+    - BPay account form handler for Rails applications
+    - BPay details validation helper
+
+### Features
+- BPay accounts work as disbursement destinations for Australian bill payments
+- Supports all major Australian billers (utilities, telecommunications, financial services, government)
+- Automatic biller name lookup based on biller code
+- Full lifecycle management (create, show, show_user, redact)
+- Secure validation of BPay-specific formats
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.5.0...v2.6.0
+
+## [2.5.0] - 2025-11-03
+
+### Added
+- **Bank Account Resource**: Complete CRUD operations plus validation for Australian and UK bank accounts 🏦
+  - `ZaiPayment.bank_accounts.show(bank_account_id, include_decrypted_fields:)` - Get bank account details with optional decrypted fields
+  - `ZaiPayment.bank_accounts.create_au(user_id:, bank_name:, account_name:, routing_number:, account_number:, account_type:, holder_type:, country:)` - Create Australian bank account
+  - `ZaiPayment.bank_accounts.create_uk(user_id:, bank_name:, account_name:, routing_number:, account_number:, account_type:, holder_type:, country:, iban:, swift_code:)` - Create UK bank account with IBAN and SWIFT code
+  - `ZaiPayment.bank_accounts.redact(bank_account_id)` - Redact (deactivate) a bank account
+  - `ZaiPayment.bank_accounts.validate_routing_number(routing_number)` - Validate US bank routing numbers and get bank information
+  - Support for retrieving decrypted sensitive fields (full account numbers)
+  - Support for savings and checking account types
+  - Support for personal and business holder types
+  - Comprehensive validation for required fields and formats
+  - Full RSpec test suite with 25 test examples
+  - Comprehensive documentation in `docs/bank_accounts.md`
+  - Practical examples in `examples/bank_accounts.md`
+
+### Documentation
+- **Bank Accounts Guide** (`docs/bank_accounts.md`):
+  - Complete guide for showing, creating, validating, and redacting bank accounts
+  - Documentation for decrypted fields parameter
+  - Validation endpoint documentation for US routing numbers
+  - Redaction endpoint documentation with warnings
+  - Validation rules for account types, holder types, and country codes
+  - Response structure documentation
+  - Error handling examples
+  - Use cases for disbursement accounts, multi-currency setups, and routing number validation
+- **Bank Accounts Examples** (`examples/bank_accounts.md`):
+  - Examples for retrieving bank account details (masked and decrypted)
+  - Examples for redacting bank accounts with error handling (Examples 9-10)
+  - Examples for validating US routing numbers (Examples 11-13)
+  - Real-world scenarios for Australian bank accounts
+  - UK bank account creation with IBAN/SWIFT
+  - Business account setup examples
+  - Multi-region account management patterns
+  - Routing number validation integration in forms
+  - Security best practices for handling decrypted data
+
+**Full Changelog**: https://github.com/Sentia/zai-payment/compare/v2.4.0...v2.5.0
+
 ## [2.4.0] - 2025-11-02
 ### Added
 - **Item Payment Actions API**: Advanced payment operations for managing item transactions 💳

data/docs/bank_accounts.md

@@ -0,0 +1,494 @@
+# Bank Account Management
+
+The BankAccount resource provides methods for managing Zai bank accounts for both Australian and UK regions.
+
+## Overview
+
+Bank accounts are used as either a funding source or a disbursement destination. Once created, store the returned `:id` and use it for a `make_payment` Item Action call. The `:id` is also referred to as a `:token` when invoking Bank Accounts.
+
+For platforms operating in the UK, `iban` and `swift_code` are extra required fields in addition to the standard Australian fields.
+
+## References
+
+- [Create Bank Account API](https://developer.hellozai.com/reference/createbankaccount)
+- [Bank Account Formats by Country](https://developer.hellozai.com/docs/bank-account-formats)
+
+## Usage
+
+### Initialize the BankAccount Resource
+
+```ruby
+# Using a new instance
+bank_accounts = ZaiPayment::Resources::BankAccount.new
+
+# Or use with custom client
+client = ZaiPayment::Client.new
+bank_accounts = ZaiPayment::Resources::BankAccount.new(client: client)
+```
+
+## Methods
+
+### Show Bank Account
+
+Get details of a specific bank account by ID.
+
+#### Parameters
+
+- `bank_account_id` (required) - The bank account ID
+- `include_decrypted_fields` (optional) - Boolean. If true, the API will decrypt and return sensitive bank account fields (for example, the full account number). Defaults to false.
+
+#### Example
+
+```ruby
+# Basic usage (returns masked account numbers)
+response = bank_accounts.show('bank_account_id')
+
+# Access bank account details
+bank_account = response.data
+puts bank_account['id']
+puts bank_account['active']
+puts bank_account['verification_status']
+puts bank_account['currency']
+
+# Access bank details (account numbers are masked)
+bank = bank_account['bank']
+puts bank['bank_name']
+puts bank['account_name']
+puts bank['account_type']
+puts bank['account_number']  # => "XXX234" (masked)
+```
+
+#### Example with Decrypted Fields
+
+```ruby
+# Request with decrypted fields
+response = bank_accounts.show('bank_account_id', include_decrypted_fields: true)
+
+# Access bank details (account numbers are decrypted)
+bank = response.data['bank']
+puts bank['account_number']  # => "12345678" (full number)
+puts bank['routing_number']  # => "111123" (full number)
+```
+
+### Redact Bank Account
+
+Redact 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.
+
+#### Parameters
+
+- `bank_account_id` (required) - The bank account ID
+
+#### Example
+
+```ruby
+response = bank_accounts.redact('bank_account_id')
+
+if response.success?
+  puts "Bank account successfully redacted"
+else
+  puts "Failed to redact bank account"
+end
+```
+
+#### Response
+
+```ruby
+{
+  "bank_account" => "Successfully redacted"
+}
+```
+
+**Important Notes:**
+- Once redacted, the bank account cannot be used for payments or disbursements
+- This action cannot be undone
+- Use with caution
+
+### Validate Routing Number
+
+Validate 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.
+
+#### Parameters
+
+- `routing_number` (required) - The US bank routing number (9 digits)
+
+#### Example
+
+```ruby
+response = bank_accounts.validate_routing_number('122235821')
+
+if response.success?
+  routing_info = response.data
+  puts "Routing Number: #{routing_info['routing_number']}"
+  puts "Bank Name: #{routing_info['customer_name']}"
+  puts "City: #{routing_info['city']}"
+  puts "State: #{routing_info['state_code']}"
+  puts "ZIP: #{routing_info['zip']}"
+  puts "Phone: #{routing_info['phone_area_code']}-#{routing_info['phone_prefix']}-#{routing_info['phone_suffix']}"
+else
+  puts "Invalid routing number"
+end
+```
+
+#### Response
+
+```ruby
+{
+  "routing_number" => "122235821",
+  "customer_name" => "US BANK NA",
+  "address" => "EP-MN-WN1A",
+  "city" => "ST. PAUL",
+  "state_code" => "MN",
+  "zip" => "55107",
+  "zip_extension" => "1419",
+  "phone_area_code" => "800",
+  "phone_prefix" => "937",
+  "phone_suffix" => "631"
+}
+```
+
+**Use Cases:**
+- Validate routing numbers before bank account creation
+- Display bank information to users for confirmation
+- Provide real-time feedback during form entry
+- Reduce errors in bank account setup
+
+### Create Australian Bank Account
+
+Create a new bank account for an Australian user.
+
+#### Required Fields
+
+- `user_id` - User ID (defaults to aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee)
+- `bank_name` - Bank name (defaults to Bank of Australia)
+- `account_name` - Account name (defaults to Samuel Seller)
+- `routing_number` - Routing number / BSB number (defaults to 111123). See [Bank account formats by country](https://developer.hellozai.com/docs/bank-account-formats).
+- `account_number` - Account number (defaults to 111234). See [Bank account formats by country](https://developer.hellozai.com/docs/bank-account-formats).
+- `account_type` - Bank account type ('savings' or 'checking', defaults to checking)
+- `holder_type` - Holder type ('personal' or 'business', defaults to personal)
+- `country` - ISO 3166-1 alpha-3 country code (length ≤ 3, defaults to AUS)
+
+#### Optional Fields
+
+- `payout_currency` - ISO 4217 alpha-3 currency code for payouts
+- `currency` - ISO 4217 alpha-3 currency code. This is an optional field and if not provided, the item will be created with the default currency of the marketplace.
+
+#### Example
+
+```ruby
+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'
+)
+
+if response.success?
+  bank_account = response.data
+  puts "Bank Account ID: #{bank_account['id']}"
+  puts "Active: #{bank_account['active']}"
+  puts "Verification Status: #{bank_account['verification_status']}"
+  puts "Currency: #{bank_account['currency']}"
+  
+  # Access bank details
+  bank = bank_account['bank']
+  puts "Bank Name: #{bank['bank_name']}"
+  puts "Account Name: #{bank['account_name']}"
+  puts "Account Type: #{bank['account_type']}"
+  puts "Holder Type: #{bank['holder_type']}"
+  puts "Routing Number: #{bank['routing_number']}"
+  puts "Direct Debit Status: #{bank['direct_debit_authority_status']}"
+  
+  # Access links
+  links = bank_account['links']
+  puts "Self Link: #{links['self']}"
+  puts "Users Link: #{links['users']}"
+end
+```
+
+### Create UK Bank Account
+
+Create a new bank account for a UK user. UK bank accounts require additional fields: `iban` and `swift_code`.
+
+#### Required Fields
+
+All fields from Australian bank accounts plus:
+
+- `iban` - International Bank Account Number (required for UK)
+- `swift_code` - SWIFT Code / BIC (required for UK)
+
+#### Example
+
+```ruby
+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',
+  iban: 'GB25QHWM02498765432109',
+  swift_code: 'BUKBGB22',
+  payout_currency: 'GBP',
+  currency: 'GBP'
+)
+
+if response.success?
+  bank_account = response.data
+  puts "Bank Account ID: #{bank_account['id']}"
+  
+  bank = bank_account['bank']
+  puts "IBAN: #{bank['iban']}"
+  puts "SWIFT Code: #{bank['swift_code']}"
+end
+```
+
+## Response Structure
+
+Both methods return a `ZaiPayment::Response` object with the following structure:
+
+```ruby
+{
+  "bank_accounts" => {
+    "id" => "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    "active" => true,
+    "verification_status" => "not_verified",
+    "currency" => "AUD",
+    "bank" => {
+      "bank_name" => "Bank of Australia",
+      "country" => "AUS",
+      "account_name" => "Samuel Seller",
+      "routing_number" => "XXXXX3",      # Masked for security
+      "account_number" => "XXX234",      # Masked for security
+      "iban" => "null,",                 # Or actual IBAN for UK
+      "swift_code" => "null,",           # Or actual SWIFT for UK
+      "holder_type" => "personal",
+      "account_type" => "checking",
+      "direct_debit_authority_status" => "approved"
+    },
+    "links" => {
+      "self" => "/bank_accounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+      "users" => "/bank_accounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/users",
+      "direct_debit_authorities" => "/bank_accounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/direct_debit_authorities"
+    }
+  }
+}
+```
+
+## Validation Rules
+
+### Account Type
+
+Must be one of:
+- `savings` - Savings account
+- `checking` - Checking/current account
+
+### Holder Type
+
+Must be one of:
+- `personal` - Personal/individual account
+- `business` - Business/company account
+
+### Country Code
+
+Must be a valid ISO 3166-1 alpha-3 code (3 letters):
+- Australia: `AUS`
+- United Kingdom: `GBR`
+
+### Currency Code
+
+When provided, must be a valid ISO 4217 alpha-3 code:
+- Australian Dollar: `AUD`
+- British Pound: `GBP`
+- US Dollar: `USD`
+
+## Error Handling
+
+The BankAccount resource raises the following errors:
+
+### ValidationError
+
+Raised when required fields are missing or invalid:
+
+```ruby
+begin
+  bank_accounts.create_au(
+    user_id: 'user_123',
+    bank_name: 'Test Bank'
+    # Missing required fields
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  puts "Validation failed: #{e.message}"
+  # => "Missing required fields: account_name, routing_number, account_number, account_type, holder_type, country"
+end
+```
+
+### Invalid Account Type
+
+```ruby
+begin
+  bank_accounts.create_au(
+    user_id: 'user_123',
+    bank_name: 'Test Bank',
+    account_name: 'Test',
+    routing_number: '111123',
+    account_number: '111234',
+    account_type: 'invalid',
+    holder_type: 'personal',
+    country: 'AUS'
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  puts e.message
+  # => "account_type must be one of: savings, checking"
+end
+```
+
+### Invalid Holder Type
+
+```ruby
+begin
+  bank_accounts.create_au(
+    user_id: 'user_123',
+    bank_name: 'Test Bank',
+    account_name: 'Test',
+    routing_number: '111123',
+    account_number: '111234',
+    account_type: 'checking',
+    holder_type: 'invalid',
+    country: 'AUS'
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  puts e.message
+  # => "holder_type must be one of: personal, business"
+end
+```
+
+### Invalid Country Code
+
+```ruby
+begin
+  bank_accounts.create_au(
+    user_id: 'user_123',
+    bank_name: 'Test Bank',
+    account_name: 'Test',
+    routing_number: '111123',
+    account_number: '111234',
+    account_type: 'checking',
+    holder_type: 'personal',
+    country: 'INVALID'
+  )
+rescue ZaiPayment::Errors::ValidationError => e
+  puts e.message
+  # => "country must be a valid ISO 3166-1 alpha-3 code (e.g., AUS, GBR)"
+end
+```
+
+## Use Cases
+
+### Use Case 1: Disbursement Account Setup
+
+After creating a payout user (seller), create a bank account for receiving payments:
+
+```ruby
+# Step 1: Create payout user
+users = ZaiPayment::Resources::User.new
+user_response = users.create(
+  user_type: 'payout',
+  email: 'seller@example.com',
+  first_name: 'Jane',
+  last_name: 'Seller',
+  country: 'AUS',
+  dob: '01/01/1990',
+  address_line1: '123 Main St',
+  city: 'Sydney',
+  state: 'NSW',
+  zip: '2000'
+)
+
+user_id = user_response.data['id']
+
+# Step 2: Create bank account
+bank_accounts = ZaiPayment::Resources::BankAccount.new
+bank_response = bank_accounts.create_au(
+  user_id: user_id,
+  bank_name: 'Commonwealth Bank',
+  account_name: 'Jane Seller',
+  routing_number: '062000',
+  account_number: '12345678',
+  account_type: 'savings',
+  holder_type: 'personal',
+  country: 'AUS',
+  payout_currency: 'AUD'
+)
+
+account_id = bank_response.data['id']
+
+# Step 3: Set as disbursement account
+users.set_disbursement_account(user_id, account_id)
+```
+
+### Use Case 2: Multi-Currency Business Account
+
+Create business bank accounts for different currencies:
+
+```ruby
+bank_accounts = ZaiPayment::Resources::BankAccount.new
+
+# Australian business account
+au_response = bank_accounts.create_au(
+  user_id: 'business_user_123',
+  bank_name: 'Westpac',
+  account_name: 'ABC Pty Ltd',
+  routing_number: '032000',
+  account_number: '87654321',
+  account_type: 'checking',
+  holder_type: 'business',
+  country: 'AUS',
+  payout_currency: 'AUD'
+)
+
+# UK business account
+uk_response = bank_accounts.create_uk(
+  user_id: 'business_user_123',
+  bank_name: 'Barclays',
+  account_name: 'ABC Limited',
+  routing_number: '200000',
+  account_number: '55779911',
+  account_type: 'checking',
+  holder_type: 'business',
+  country: 'GBR',
+  iban: 'GB33BUKB20000055779911',
+  swift_code: 'BARCGB22',
+  payout_currency: 'GBP'
+)
+```
+
+## Important Notes
+
+1. **Security**: Account numbers and routing numbers are masked in API responses for security
+2. **Verification**: New bank accounts typically have `verification_status: "not_verified"` until verified by Zai
+3. **Direct Debit**: The `direct_debit_authority_status` indicates if direct debit is available for the account
+4. **Token Usage**: The returned `id` can be used as a token for payment operations
+5. **Region Differences**:
+   - Australia: Only requires standard banking details
+   - UK: Additionally requires IBAN and SWIFT code
+
+## Related Resources
+
+- [User Management](users.md) - Creating and managing users
+- [Item Management](items.md) - Creating transactions/payments
+- [Disbursement Accounts](users.md#set-disbursement-account) - Setting default payout accounts
+
+## Further Reading
+
+- [Bank Account Formats by Country](https://developer.hellozai.com/docs/bank-account-formats)
+- [Payment Methods Guide](https://developer.hellozai.com/docs/payment-methods)
+- [Verification Process](https://developer.hellozai.com/docs/verification)
+