Zai Payment Ruby Library

A lightweight and extensible Ruby client for the Zai (AssemblyPay) API — starting with secure OAuth2 authentication, and ready for Payments, Virtual Accounts, Webhooks, and more.

---

✨ Features

• 🔐 OAuth2 Authentication - Client Credentials flow with automatic token management
• 🧠 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
• 💳 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
• ⚙️ Environment-Aware - Seamless Pre-live / Production switching
• 🧱 Modular & Extensible - Clean resource-based architecture
• 🧰 Zero Heavy Dependencies - Lightweight, fast, and reliable
• 📦 Production Ready - 97%+ test coverage, RuboCop compliant

---

🧭 Installation

Add this line to your Gemfile:

gem 'zai_payment'

Then install

bundle install

⚙️ Configuration

# config/initializers/zai_payment.rb
ZaiPayment.configure do |c|
  c.environment   = Rails.env.production? ? :production : :prelive
  c.client_id     = ENV.fetch("ZAI_CLIENT_ID")
  c.client_secret = ENV.fetch("ZAI_CLIENT_SECRET")
  c.scope         = ENV.fetch("ZAI_OAUTH_SCOPE")
  
  # Optional: Configure timeout settings (defaults shown)
  c.timeout       = 30  # General request timeout in seconds
  c.open_timeout  = 10  # Connection open timeout in seconds
  c.read_timeout  = 30  # Read timeout in seconds
end

🚀 Quick Start

Authentication

Get an OAuth2 token with automatic caching and refresh:

# Simple one-liner (recommended)
token = ZaiPayment.token

# Or with full control (advanced)
config = ZaiPayment::Config.new
config.environment = :prelive
config.client_id = 'your_client_id'
config.client_secret = 'your_client_secret'
config.scope = 'your_scope'

token_provider = ZaiPayment::Auth::TokenProvider.new(config: config)
token = token_provider.bearer_token

The gem handles OAuth2 Client Credentials flow automatically - tokens are cached and refreshed before expiration.

📖 Complete Authentication Guide - Two approaches, examples, and best practices

Users

Manage payin (buyer) and payout (seller/merchant) users.

📚 Documentation:

• 📖 User Management Guide - Complete guide for payin and payout users
• 💡 User Examples - Real-world usage patterns and Rails integration
• 🔗 Zai: Onboarding a Payin User
• 🔗 Zai: Onboarding a Payout User

Items

Manage transactions/payments between buyers and sellers.

📚 Documentation:

• 📖 Item Management Guide - Complete guide for creating and managing items
• 💡 Item Examples - Real-world usage patterns and complete workflows
• 🔗 Zai: Items API Reference

Bank Accounts

Manage bank accounts for Australian and UK users, with routing number validation.

📚 Documentation:

• 📖 Bank Account Management Guide - Complete guide for bank accounts
• 💡 Bank Account Examples - Real-world patterns and integration
• 🔗 Zai: Bank Accounts API Reference

BPay Accounts

Manage BPay accounts for Australian bill payments.

📚 Documentation:

• 📖 BPay Account Management Guide - Complete guide for BPay accounts
• 💡 BPay Account Examples - Real-world patterns and bill payment workflows
• 🔗 Zai: BPay Accounts API Reference

Wallet Accounts

Manage wallet accounts, check balances, and pay bills via BPay.

📚 Documentation:

• 📖 Wallet Account Management Guide - Complete guide for wallet accounts
• 💡 Wallet Account Examples - Real-world patterns and payment workflows
• 🔗 Zai: Wallet Accounts API Reference

Quick Example:

wallet_accounts = ZaiPayment::Resources::WalletAccount.new

# Check wallet balance
response = wallet_accounts.show('wallet_account_id')
balance = response.data['balance']  # in cents
puts "Balance: $#{balance / 100.0}"

# Pay a bill from wallet to BPay account
payment_response = wallet_accounts.pay_bill(
  'wallet_account_id',
  account_id: 'bpay_account_id',
  amount: 17300,  # $173.00 in cents
  reference_id: 'bill_nov_2024'
)

if payment_response.success?
  disbursement = payment_response.data
  puts "Payment successful: #{disbursement['id']}"
  puts "State: #{disbursement['state']}"
end

Virtual Accounts

Manage virtual accounts with support for AKA names and Confirmation of Payee (CoP) lookups.

📚 Documentation:

• 📖 Virtual Account Management Guide - Complete guide for virtual accounts
• 💡 Virtual Account Examples - Real-world patterns and workflows
• 🔗 Zai: Virtual Accounts API Reference

PayID

Register and manage PayIDs (EMAIL type) for Australian NPP (New Payments Platform) payments.

📚 Documentation:

• 📖 PayID Management Guide - Complete guide for PayID registration
• 💡 PayID Examples - Real-world patterns and workflows

Token Auth

Generate secure tokens for collecting bank and card account information.

📚 Documentation:

• 💡 Token Auth Examples - Complete integration guide with PromisePay.js
• 🔗 Zai: Generate Token API Reference

Webhooks

Manage webhook endpoints with secure signature verification.

📚 Documentation:

• 📖 Webhook Examples & Complete Guide - Full CRUD operations and patterns
• 🔒 Security Quick Start - 5-minute webhook security setup
• 🏗️ Architecture & Implementation - Detailed technical documentation
• 🔐 Signature Verification Details - Security implementation specs

Batch Transactions (Prelive Only)

Simulate batch transaction processing for testing in the prelive environment.

📚 Documentation:

• 📖 Batch Transaction Guide - Complete guide and method reference
• 💡 Batch Transaction Examples - Testing workflows and webhook simulation
• ⚠️ Note: These endpoints are only available in prelive environment

Quick Example:

# Export pending transactions to batched state
export_response = ZaiPayment.batch_transactions.export_transactions
batch_id = export_response.data.first['batch_id']
transaction_ids = export_response.data.map { |t| t['id'] }

# Move to bank_processing state
ZaiPayment.batch_transactions.process_to_bank_processing(
  batch_id,
  exported_ids: transaction_ids
)

# Complete processing (triggers webhooks)
ZaiPayment.batch_transactions.process_to_successful(
  batch_id,
  exported_ids: transaction_ids
)

Error Handling

The gem provides specific error classes for different scenarios:

begin
  response = ZaiPayment.webhooks.create(
    url: 'https://example.com/webhook',
    object_type: 'transactions'
  )
rescue ZaiPayment::Errors::ValidationError => e
  # Handle validation errors (400, 422)
  puts "Validation error: #{e.message}"
rescue ZaiPayment::Errors::UnauthorizedError => e
  # Handle authentication errors (401)
  puts "Authentication failed: #{e.message}"
rescue ZaiPayment::Errors::NotFoundError => e
  # Handle not found errors (404)
  puts "Resource not found: #{e.message}"
rescue ZaiPayment::Errors::ApiError => e
  # Handle other API errors
  puts "API error: #{e.message}"
end

🧩 Roadmap

Area	Description	Status
✅ Authentication	OAuth2 Client Credentials flow	Done
✅ 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
✅ BPay Accounts	Manage BPay accounts	Done
✅ Wallet Accounts	Show, check balance, pay bills	Done
✅ Token Auth	Generate bank/card tokens	Done
✅ Batch Transactions (Prelive)	Simulate batch processing flows	Done
✅ Payments	Single and recurring payments	Done
✅ Virtual Accounts	Manage virtual accounts & PayTo	Done
✅ PayID	Create and manage PayIDs	Done

🧪 Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Running Tests

bundle exec rspec

Code Quality

This project uses RuboCop for linting. Run it with:

bundle exec rubocop

Interactive Console

For development and testing, use the interactive console:

bin/console

This will load the gem and all its dependencies, allowing you to experiment with the API in a REPL environment.

🧾 Versioning

This gem follows Semantic Versioning.

See changelog.md for release history.

🤝 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Sentia/zai-payment. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

🪪 License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ZaiPayment project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

📚 Documentation

Getting Started

• Authentication Guide - Two approaches to getting tokens, automatic management
• User Management Guide - Managing payin and payout users
• Item Management Guide - Creating and managing transactions/payments
• Bank Account Guide - Managing bank accounts for AU/UK users
• BPay Account Guide - Managing BPay accounts for Australian bill payments
• Wallet Account Guide - Managing wallet accounts, checking balances, and paying bills
• Virtual Account Guide - Managing virtual accounts with PayTo and BPay support
• PayID Guide - Creating and managing PayIDs for Australian NPP payments
• Webhook Examples - Complete webhook usage guide
• Documentation Index - Full documentation navigation

Examples & Patterns

• User Examples - Real-world user management patterns
• Item Examples - Transaction and payment workflows
• Bank Account Examples - Bank account integration patterns
• BPay Account Examples - BPay account integration patterns
• Wallet Account Examples - Wallet account and bill payment workflows
• Virtual Account Examples - Virtual account management and PayTo workflows
• PayID Examples - PayID creation and management workflows
• Token Auth Examples - Secure token generation and integration
• Webhook Examples - Webhook integration patterns
• Batch Transaction Examples - Testing batch transaction flows (prelive only)

Technical Guides

• Webhook Architecture - Technical implementation details
• Architecture Overview - System architecture and design
• Direct API Usage Guide - 🔥 How to call unimplemented APIs directly

Security

• Webhook Security Quick Start - 5-minute setup guide
• Signature Verification - Implementation details

External Resources

• Zai Developer Portal
• Zai API Reference
• Zai OAuth Documentation