malipopay 1.0.0

data/docs/customers.md

@@ -0,0 +1,133 @@
+# Customers
+
+The `customers` resource lets you create, retrieve, search, and verify customer records. Customers are linked to payments, invoices, and transaction history in MaliPoPay.
+
+## Create a Customer
+
+```ruby
+customer = client.customers.create(
+  name: 'Juma Bakari',
+  phone: '255712345678',
+  email: 'juma.bakari@example.com',
+  address: 'Plot 45, Samora Avenue, Dar es Salaam',
+  customer_type: 'individual',
+  notes: 'Preferred payment method: M-Pesa'
+)
+
+if customer['success']
+  puts "Customer created: #{customer['data']['id']}"
+end
+```
+
+### Create a Business Customer
+
+```ruby
+business = client.customers.create(
+  name: 'Kilimanjaro Trading Co.',
+  phone: '255222123456',
+  email: 'accounts@kilitrade.co.tz',
+  address: 'Industrial Area, Arusha',
+  customer_type: 'business',
+  tin: '123-456-789',
+  notes: 'Net 30 payment terms'
+)
+```
+
+## List All Customers
+
+```ruby
+customers = client.customers.list
+
+if customers['success']
+  customers['data'].each do |c|
+    puts "#{c['name']} (#{c['phone']})"
+  end
+end
+```
+
+## Get a Customer by ID
+
+```ruby
+customer = client.customers.get('cust_abc123')
+
+if customer['success']
+  puts "Name: #{customer['data']['name']}"
+  puts "Phone: #{customer['data']['phone']}"
+  puts "Email: #{customer['data']['email']}"
+end
+```
+
+## Get a Customer by Phone Number
+
+Look up a customer using their phone number:
+
+```ruby
+customer = client.customers.get_by_phone('255712345678')
+
+if customer['success']
+  puts "Found: #{customer['data']['name']}"
+end
+```
+
+## Get a Customer by Customer Number
+
+Look up using the MaliPoPay-assigned customer number:
+
+```ruby
+customer = client.customers.get_by_number('CUST-2024-001')
+
+if customer['success']
+  puts "Found: #{customer['data']['name']}"
+end
+```
+
+## Search Customers
+
+Search by name, phone, email, or other fields:
+
+```ruby
+results = client.customers.search
+
+if results['success']
+  puts "Found #{results['data'].length} customers"
+end
+```
+
+## Verify a Customer
+
+Customer verification is useful for KYC (Know Your Customer) compliance. This checks the customer's identity against the phone number or ID document registered with their mobile money provider:
+
+```ruby
+verification = client.customers.verify(
+  phone: '255712345678',
+  provider: 'M-Pesa'
+)
+
+if verification['success']
+  puts "Verified: #{verification['data']}"
+else
+  puts "Verification failed: #{verification['message']}"
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  customer = client.customers.create(
+    name: 'Incomplete Customer'
+    # missing phone -- will trigger validation error
+  )
+rescue MaliPoPay::ValidationError => e
+  puts "Missing required fields: #{e.message}"
+rescue MaliPoPay::NotFoundError
+  puts 'Customer not found.'
+rescue MaliPoPay::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+## Next Steps
+
+- [Invoices](./invoices.md) -- create invoices for your customers
+- [Payments](./payments.md) -- collect payments from customers

data/docs/error-handling.md

@@ -0,0 +1,274 @@
+# Error Handling
+
+The MaliPoPay Ruby SDK uses a structured exception hierarchy so you can rescue specific error types and respond appropriately. All exceptions inherit from `MaliPoPay::Error`.
+
+## Exception Hierarchy
+
+```
+MaliPoPay::Error (base)
+├── MaliPoPay::AuthenticationError    (HTTP 401 -- invalid or missing API key)
+├── MaliPoPay::PermissionError        (HTTP 403 -- insufficient permissions)
+├── MaliPoPay::NotFoundError          (HTTP 404 -- resource does not exist)
+├── MaliPoPay::ValidationError        (HTTP 422 -- invalid request parameters)
+├── MaliPoPay::RateLimitError         (HTTP 429 -- too many requests)
+├── MaliPoPay::ApiError               (HTTP 5xx -- server-side error)
+└── MaliPoPay::ConnectionError        (network timeout, DNS failure, etc.)
+```
+
+## Rescuing Specific Exceptions
+
+### Ordered by Specificity
+
+```ruby
+begin
+  result = client.payments.collect(
+    amount: 50_000,
+    currency: 'TZS',
+    phone: '255712345678',
+    provider: 'M-Pesa',
+    reference: 'ORD-2024-100',
+    description: 'Monthly subscription'
+  )
+
+  puts "Collection initiated: #{result['reference']}"
+
+rescue MaliPoPay::AuthenticationError
+  # API key is invalid or expired
+  puts 'Authentication failed. Rotate your API key at app.malipopay.co.tz'
+
+rescue MaliPoPay::PermissionError
+  # API key lacks permission for this operation
+  puts 'Insufficient permissions. Check your API key scopes.'
+
+rescue MaliPoPay::ValidationError => e
+  # The request had invalid fields
+  puts "Invalid request: #{e.message}"
+  # e.message might say: "phone must be a valid Tanzanian number (255xxxxxxxxx)"
+
+rescue MaliPoPay::NotFoundError
+  puts 'The requested resource was not found.'
+
+rescue MaliPoPay::RateLimitError
+  puts 'Too many requests. Back off and retry.'
+
+rescue MaliPoPay::ApiError => e
+  # MaliPoPay server error -- transient, safe to retry
+  puts "Server error (#{e.message}). Retrying..."
+
+rescue MaliPoPay::ConnectionError => e
+  # Network-level failure
+  puts "Connection failed: #{e.message}"
+
+rescue MaliPoPay::Error => e
+  # Catch-all for any other SDK error
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+## Exception Properties
+
+Every `MaliPoPay::Error` includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `message` | `String` | Human-readable error description |
+| `status_code` | `Integer` or `nil` | HTTP status code (`nil` for `ConnectionError`) |
+
+## Retry Strategies
+
+The SDK automatically retries transient errors (5xx, connection timeouts) based on the `retries` option. You can also implement your own retry logic for specific cases.
+
+### Built-in Retries
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_API_KEY'],
+  retries: 3  # retry up to 3 times on transient failures (default: 2)
+)
+```
+
+The SDK uses exponential backoff between retries. It will only retry on:
+- `MaliPoPay::ApiError` (5xx responses)
+- `MaliPoPay::ConnectionError` (network timeouts and DNS failures)
+
+It will **not** retry on:
+- `AuthenticationError` (fix your API key)
+- `PermissionError` (check your API key scopes)
+- `ValidationError` (fix your request)
+- `NotFoundError` (the resource doesn't exist)
+- `RateLimitError` (handled separately -- see below)
+
+### Custom Retry for Rate Limits
+
+```ruby
+def with_rate_limit_retry(max_retries: 3)
+  attempts = 0
+
+  begin
+    yield
+  rescue MaliPoPay::RateLimitError
+    attempts += 1
+    raise if attempts > max_retries
+
+    delay = 2**attempts  # exponential backoff: 2s, 4s, 8s
+    puts "Rate limited. Retrying in #{delay}s..."
+    sleep delay
+    retry
+  end
+end
+
+# Usage
+result = with_rate_limit_retry do
+  client.payments.collect(
+    amount: 75_000,
+    currency: 'TZS',
+    phone: '255712345678',
+    provider: 'M-Pesa',
+    reference: 'ORD-2024-200',
+    description: 'Retry example'
+  )
+end
+```
+
+### Generic Retry Helper
+
+```ruby
+def with_retry(max_retries: 3, on: [MaliPoPay::ApiError, MaliPoPay::ConnectionError])
+  attempts = 0
+
+  begin
+    yield
+  rescue *on => e
+    attempts += 1
+    raise if attempts > max_retries
+
+    delay = 2**attempts
+    puts "#{e.class}: #{e.message}. Retry #{attempts}/#{max_retries} in #{delay}s..."
+    sleep delay
+    retry
+  end
+end
+
+# Usage
+result = with_retry(max_retries: 5) do
+  client.payments.disburse(
+    amount: 250_000,
+    currency: 'TZS',
+    phone: '255754321098',
+    provider: 'Airtel Money',
+    reference: 'PAY-2024-055',
+    description: 'Supplier payment'
+  )
+end
+```
+
+## Common Errors and Solutions
+
+### AuthenticationError (401)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Invalid API key" | The `apiToken` header is wrong or missing | Verify your key at [app.malipopay.co.tz](https://app.malipopay.co.tz) under Settings > API Keys |
+| "API key expired" | Key was revoked or rotated | Generate a new key in the dashboard |
+| "Unauthorized environment" | Using a production key on UAT or vice versa | Use the correct key for your environment |
+
+### PermissionError (403)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Insufficient permissions" | API key lacks required scope | Check key permissions in the dashboard |
+
+### ValidationError (422)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "phone must be a valid Tanzanian number" | Phone number not in `255xxxxxxxxx` format | Use the full international format: `255712345678` |
+| "amount must be greater than 0" | Zero or negative amount | Provide a positive integer amount in TZS |
+| "provider is required" | Missing `provider` field | Specify one of: `M-Pesa`, `Airtel Money`, `Mixx`, `Halopesa`, `T-Pesa`, `CRDB`, `NMB` |
+| "reference must be unique" | Duplicate reference string | Generate a unique reference per transaction |
+| "currency must be TZS" | Unsupported currency | MaliPoPay currently supports TZS only |
+
+### NotFoundError (404)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Payment not found" | Reference doesn't match any payment | Double-check the reference string |
+| "Customer not found" | Customer ID doesn't exist | Create the customer first or verify the ID |
+| "Invoice not found" | Invoice ID doesn't exist | Check the invoice ID from your records |
+
+### RateLimitError (429)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Rate limit exceeded" | Too many API calls in a short period | Implement exponential backoff; batch operations where possible |
+
+### ApiError (5xx)
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Internal server error" | Temporary server issue | Retry after a short delay; these are transient |
+| "Service unavailable" | Maintenance or provider downtime | Check [status.malipopay.co.tz](https://status.malipopay.co.tz) for updates |
+
+### ConnectionError
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Request timed out" | Network latency or server unresponsive | Increase `timeout` in client options; check network connectivity |
+| "DNS resolution failed" | Cannot resolve the API hostname | Verify your DNS settings and internet connection |
+
+## Logging Errors
+
+Use Ruby's Logger for production error tracking:
+
+```ruby
+require 'logger'
+
+logger = Logger.new($stdout)
+
+begin
+  result = client.payments.collect(
+    amount: 30_000,
+    currency: 'TZS',
+    phone: '255622345678',
+    provider: 'Halopesa',
+    reference: 'ORD-2024-300',
+    description: 'Logging example'
+  )
+rescue MaliPoPay::Error => e
+  logger.error("MaliPoPay API error: status=#{e.status_code} message=#{e.message}")
+  raise
+end
+```
+
+### Rails Integration
+
+In Rails, errors are automatically logged. You can add custom handling in an initializer or concern:
+
+```ruby
+# app/controllers/concerns/malipopay_error_handling.rb
+module MalipopayErrorHandling
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from MaliPoPay::AuthenticationError do |e|
+      Rails.logger.error("MaliPoPay auth error: #{e.message}")
+      render json: { error: 'Payment service authentication failed' }, status: :service_unavailable
+    end
+
+    rescue_from MaliPoPay::ValidationError do |e|
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+
+    rescue_from MaliPoPay::Error do |e|
+      Rails.logger.error("MaliPoPay error: #{e.class} - #{e.message}")
+      render json: { error: 'Payment service error' }, status: :service_unavailable
+    end
+  end
+end
+```
+
+## Next Steps
+
+- [Configuration](./configuration.md) -- configure retries and timeouts at the client level
+- [Payments](./payments.md) -- payment operations that may raise these exceptions
+- [Webhooks](./webhooks.md) -- webhook signature verification errors

data/docs/getting-started.md

@@ -0,0 +1,160 @@
+# Getting Started with MaliPoPay Ruby SDK
+
+## Prerequisites
+
+- **Ruby 3.0** or later
+- **Bundler** (included with Ruby)
+- A MaliPoPay merchant account with API credentials
+
+## Installation
+
+Add MaliPoPay to your Gemfile:
+
+```ruby
+gem 'malipopay'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install malipopay
+```
+
+## Getting Your API Key
+
+1. Sign in to your merchant dashboard at [app.malipopay.co.tz](https://app.malipopay.co.tz)
+2. Navigate to **Settings > API Keys**
+3. Click **Generate New Key**
+4. Copy the API key immediately -- it will only be shown once
+5. Store it securely (environment variable, credentials file, etc.)
+
+> **Important:** Never commit API keys to source control. Use environment variables or Rails encrypted credentials.
+
+## Your First Payment Collection
+
+Collect TZS 50,000 from an M-Pesa customer in five lines:
+
+```ruby
+require 'malipopay'
+
+client = MaliPoPay::Client.new(api_key: ENV['MALIPOPAY_API_KEY'])
+
+result = client.payments.collect(
+  amount: 50_000,
+  currency: 'TZS',
+  phone: '255712345678',
+  provider: 'M-Pesa',
+  reference: 'ORDER-2024-001',
+  description: 'Payment for office supplies'
+)
+
+puts "Collection initiated: #{result['reference']}" if result['success']
+```
+
+When this runs, the customer at `255712345678` receives a USSD push prompt on their phone asking them to confirm the TZS 50,000 payment with their M-Pesa PIN.
+
+## Environment Selection
+
+MaliPoPay provides two environments:
+
+| Environment | Base URL | Purpose |
+|-------------|----------|---------|
+| **Production** | `https://core-prod.malipopay.co.tz` | Live transactions with real money |
+| **UAT** | `https://core-uat.malipopay.co.tz` | Testing and integration development |
+
+### Using UAT for Testing
+
+Always develop and test against UAT before going live:
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_UAT_API_KEY'],
+  environment: :uat
+)
+```
+
+### Custom Base URL
+
+For advanced setups (proxies, custom routing), you can override the base URL:
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_API_KEY'],
+  base_url: 'https://custom-proxy.example.com'
+)
+```
+
+When `base_url` is set, it takes precedence over the `environment` setting.
+
+## Configuring Timeouts and Retries
+
+The SDK automatically retries transient failures. You can adjust timeout and retry behavior:
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_API_KEY'],
+  environment: :production,
+  timeout: 60,    # seconds (default: 30)
+  retries: 3      # automatic retries (default: 2)
+)
+```
+
+## Complete Minimal Example
+
+A full script that collects a payment and verifies it:
+
+```ruby
+require 'malipopay'
+
+api_key = ENV.fetch('MALIPOPAY_API_KEY') { raise 'Set the MALIPOPAY_API_KEY environment variable' }
+
+client = MaliPoPay::Client.new(
+  api_key: api_key,
+  environment: :uat
+)
+
+begin
+  reference = "ORD-#{Time.now.strftime('%Y%m%d%H%M%S')}"
+
+  # Step 1: Initiate collection
+  collection = client.payments.collect(
+    amount: 15_000,
+    currency: 'TZS',
+    phone: '255754321098',
+    provider: 'Airtel Money',
+    reference: reference,
+    description: 'Monthly subscription'
+  )
+
+  puts "Collection initiated. Reference: #{reference}"
+
+  # Step 2: Wait for the customer to approve on their phone
+  # In production, use webhooks instead of polling
+  sleep 30
+
+  # Step 3: Verify the payment
+  verification = client.payments.verify(reference)
+
+  puts "Payment status: #{verification['status']}"
+
+rescue MaliPoPay::AuthenticationError
+  puts 'Invalid API key. Check your credentials.'
+rescue MaliPoPay::ValidationError => e
+  puts "Invalid request: #{e.message}"
+rescue MaliPoPay::Error => e
+  puts "Payment error: #{e.message}"
+end
+```
+
+## Next Steps
+
+- [Payments Guide](./payments.md) -- all payment operations in detail
+- [Webhooks](./webhooks.md) -- receive real-time payment notifications
+- [Configuration](./configuration.md) -- advanced client setup
+- [Error Handling](./error-handling.md) -- handling failures gracefully