readme.md

Documentation Index

Welcome to the Zai Payment Ruby gem documentation. This guide will help you find the information you need.

📖 Getting Started

New to the gem? Start here:

1. Main README - Installation and basic configuration
2. Authentication Guide - Get tokens with two approaches (short & long way)
3. Webhook Quick Start - Set up secure webhooks in 5 minutes
4. Webhook Examples - Complete usage examples

🏗️ Architecture & Design

• architecture.md - System architecture and design principles
• authentication.md - OAuth2 implementation, token management, two approaches
• users.md - User management for payin (buyers) and payout (sellers/merchants)
• items.md - Item management for transactions and payments
• token_auths.md - Token generation for secure bank and card data collection
• webhooks.md - Webhook implementation details, best practices, and patterns

🔐 Security Guides

• webhook_security_quickstart.md - Quick 5-minute security setup guide
• webhook_signature.md - Detailed signature verification implementation

📝 Examples

• User Examples - User management examples and patterns
• Item Examples - Transaction and payment workflows
• Token Auth Examples - Token generation and PromisePay.js integration
• Webhook Examples - Comprehensive webhook usage examples including:
  • Basic CRUD operations
  • Rails controller implementation
  • Sinatra example
  • Rack middleware
  • Background job processing
  • Idempotency patterns

🔗 Quick Links

Authentication

• Getting Started: Authentication Guide
• Short Way: ZaiPayment.token (one-liner)
• Long Way: TokenProvider.new(config: config).bearer_token (full control)

Users

• Guide: User Management
• Examples: User Examples
• API Reference: Zai Users API

Items

• Guide: Item Management
• Examples: Item Examples
• API Reference: Zai Items API

Token Auth

• Guide: Token Auth
• Examples: Token Auth Examples
• API Reference: Zai Generate Token API

Webhooks

• Setup: Quick Start Guide
• Examples: Complete Examples
• Details: Technical Documentation
• Security: Signature Verification

External Resources

• Zai Developer Portal
• Zai API Reference
• Webhook Signature Docs

📚 Documentation Structure

docs/
├── readme.md                        # This file - documentation index
├── authentication.md                # OAuth2 authentication guide
├── users.md                         # User management guide
├── items.md                         # Item management guide
├── token_auths.md                   # Token generation guide (NEW!)
├── architecture.md                  # System architecture
├── webhooks.md                      # Webhook technical docs
├── webhook_security_quickstart.md   # Quick security setup
└── webhook_signature.md             # Signature implementation

examples/
├── users.md                         # User management examples
├── items.md                         # Item examples
├── token_auths.md                   # Token auth examples (NEW!)
└── webhooks.md                      # Webhook examples

💡 Tips

• Getting tokens? Check authentication.md for both approaches
• Managing users? See users.md for payin and payout user guides
• Creating transactions? Review items.md for item management
• Collecting payment data? See token_auths.md for secure token generation
• Looking for code examples? Check the examples directory
• Need quick setup? See webhook_security_quickstart.md
• Want to understand the design? Read architecture.md
• Security details? Review webhook_signature.md

🆘 Need Help?

1. Check the relevant documentation section above
2. Review the examples
3. Consult the Zai API documentation
4. Open an issue on GitHub