malipopay 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6492c53849e03b8431bfc390b4418b1077c18d7aa8098fc4aedb8507aeb0489b
+  data.tar.gz: dd706e99038d9fede2fd15a7777192087d6ab3b1b8b429b60635911e7e05ee7a
+SHA512:
+  metadata.gz: 00a447b13ed9b346df7ec49320179839fef574d44ef8c6e4faa16dc1ce2f26c948e6db20b014321ab83e0f5b4545f72e0ee0da0da53dc983f3868491974fe6ae
+  data.tar.gz: 158b3238b9f5a93ece0b32a078390733864ba04277be4bdab54ca789ce2e405f1931b9e693e44507bcfebb08a32ea878ce928deaeed982a623ea0228aa09b948

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lockwood Technology Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,312 @@
+# MaliPoPay Ruby SDK
+
+Official Ruby SDK for the [MaliPoPay](https://malipopay.co.tz) payment platform (Tanzania).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "malipopay"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install malipopay
+```
+
+## Quick Start
+
+```ruby
+require "malipopay"
+
+client = MaliPoPay::Client.new(
+  api_key: "your_api_token",
+  environment: :production  # or :uat for testing
+)
+```
+
+## Configuration
+
+| Option           | Default       | Description                          |
+|------------------|---------------|--------------------------------------|
+| `api_key`        | *required*    | Your MaliPoPay API token             |
+| `environment`    | `:production` | `:production` or `:uat`              |
+| `base_url`       | `nil`         | Override the base URL                |
+| `timeout`        | `30`          | Request timeout in seconds           |
+| `retries`        | `2`           | Number of retries on 429/5xx         |
+| `webhook_secret` | `nil`         | Secret for verifying webhook events  |
+
+## Resources
+
+### Payments
+
+```ruby
+# Collect mobile money
+result = client.payments.collect(
+  amount: 10_000,
+  phone: "255712345678",
+  provider: "Vodacom",
+  reference: "ORDER-001",
+  currency: "TZS"
+)
+
+# Disburse (send money)
+client.payments.disburse(
+  amount: 5_000,
+  phone: "255712345678",
+  provider: "M-Pesa",
+  reference: "PAY-001"
+)
+
+# Verify payment
+status = client.payments.verify("PAY-REF-123")
+
+# List payments
+payments = client.payments.list(page: 1, limit: 20)
+
+# Search payments
+results = client.payments.search(status: "completed", dateFrom: "2026-01-01")
+
+# Approve a pending payment
+client.payments.approve(reference: "PAY-REF-123")
+
+# Retry a failed collection
+client.payments.retry_collection("PAY-REF-123")
+
+# Create a payment link
+link = client.payments.create_link(amount: 50_000, description: "Product purchase")
+
+# Instant payment
+client.payments.pay_now(amount: 10_000, phone: "255712345678")
+```
+
+### Customers
+
+```ruby
+# Create a customer
+customer = client.customers.create(
+  name: "John Doe",
+  phone: "255712345678",
+  email: "john@example.com"
+)
+
+# List customers
+customers = client.customers.list(page: 1, limit: 20)
+
+# Get by ID
+customer = client.customers.get("customer_id")
+
+# Search
+results = client.customers.search(query: "John")
+
+# Get by phone
+customer = client.customers.get_by_phone("255712345678")
+
+# Verify customer
+client.customers.verify_customer(phone: "255712345678")
+```
+
+### Invoices
+
+```ruby
+# Create an invoice
+invoice = client.invoices.create(
+  customerId: "cust_123",
+  items: [
+    { description: "Service", quantity: 1, unitPrice: 100_000 }
+  ],
+  currency: "TZS",
+  dueDate: "2026-12-31"
+)
+
+# List invoices
+invoices = client.invoices.list(page: 1, limit: 20)
+
+# Get by ID
+invoice = client.invoices.get("invoice_id")
+
+# Approve a draft invoice
+client.invoices.approve_draft(invoiceId: "invoice_id")
+
+# Record a payment
+client.invoices.record_payment(
+  invoiceId: "invoice_id",
+  amount: 50_000,
+  reference: "RCPT-001"
+)
+```
+
+### Products
+
+```ruby
+# Create a product
+product = client.products.create(
+  name: "Premium Plan",
+  price: 99_000,
+  description: "Monthly subscription"
+)
+
+# List / Get / Update
+products = client.products.list
+product = client.products.get("product_id")
+client.products.update("product_id", price: 89_000)
+```
+
+### Transactions
+
+```ruby
+# List transactions
+transactions = client.transactions.list(page: 1, limit: 50)
+
+# Get by ID
+txn = client.transactions.get("txn_id")
+
+# Search
+results = client.transactions.search(dateFrom: "2026-01-01", dateTo: "2026-03-31")
+
+# Paginate through all transactions
+client.transactions.paginate(limit: 100).each do |page|
+  page["data"].each { |txn| process(txn) }
+end
+```
+
+### Account
+
+```ruby
+# Get account transactions
+txns = client.account.transactions(dateFrom: "2026-01-01")
+
+# Reconciliation
+recon = client.account.reconciliation(dateFrom: "2026-01-01", dateTo: "2026-03-31")
+
+# Financial reports
+client.account.financial_position
+client.account.income_statement
+client.account.general_ledger
+client.account.trial_balance
+```
+
+### SMS
+
+```ruby
+# Send a single SMS
+client.sms.send_sms(
+  to: "255712345678",
+  message: "Your payment of TZS 10,000 has been received.",
+  senderId: "MaliPoPay"
+)
+
+# Send bulk SMS
+client.sms.send_bulk(
+  messages: [
+    { to: "255712345678", message: "Hello John!" },
+    { to: "255798765432", message: "Hello Jane!" }
+  ],
+  senderId: "MaliPoPay"
+)
+
+# Schedule SMS
+client.sms.schedule(
+  to: "255712345678",
+  message: "Reminder: Your invoice is due tomorrow.",
+  senderId: "MaliPoPay",
+  scheduledAt: "2026-04-15T09:00:00Z"
+)
+```
+
+### References
+
+```ruby
+banks = client.references.banks
+currencies = client.references.currencies
+countries = client.references.countries
+institutions = client.references.institutions
+business_types = client.references.business_types
+```
+
+## Webhooks
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: "your_api_token",
+  webhook_secret: "whsec_your_secret"
+)
+
+# In your webhook endpoint (e.g., Sinatra, Rails controller)
+payload = request.body.read
+signature = request.headers["X-MaliPoPay-Signature"]
+timestamp = request.headers["X-MaliPoPay-Timestamp"]
+
+event = client.webhooks.construct_event(payload, signature, timestamp: timestamp)
+
+case event["event"]
+when "payment.completed"
+  # Handle successful payment
+when "payment.failed"
+  # Handle failed payment
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.payments.collect(amount: 10_000, phone: "255712345678")
+rescue MaliPoPay::AuthenticationError => e
+  # Invalid API key (401)
+rescue MaliPoPay::PermissionError => e
+  # Insufficient permissions (403)
+rescue MaliPoPay::NotFoundError => e
+  # Resource not found (404)
+rescue MaliPoPay::ValidationError => e
+  # Invalid parameters (400/422)
+  puts e.errors
+rescue MaliPoPay::RateLimitError => e
+  # Rate limited (429) - retry after e.retry_after seconds
+rescue MaliPoPay::ApiError => e
+  # Server error (5xx)
+rescue MaliPoPay::ConnectionError => e
+  # Network error
+end
+```
+
+## Environments
+
+| Environment  | Base URL                              |
+|-------------|---------------------------------------|
+| Production  | `https://core-prod.malipopay.co.tz`   |
+| UAT         | `https://core-uat.malipopay.co.tz`    |
+
+## Requirements
+
+- Ruby >= 3.0
+- Faraday ~> 2.0
+
+## License
+
+MIT License - Copyright (c) 2026 [Lockwood Technology Ltd](https://lockwood.co.tz)
+
+
+---
+
+## See Also
+
+| SDK | Install |
+|-----|---------|
+| [Node.js](https://github.com/Malipopay/malipopay-node) | `npm install malipopay` |
+| [Python](https://github.com/Malipopay/malipopay-python) | `pip install malipopay` |
+| [PHP](https://github.com/Malipopay/malipopay-php) | `composer require malipopay/malipopay-php` |
+| [Java](https://github.com/Malipopay/malipopay-java) | Maven / Gradle |
+| [.NET](https://github.com/Malipopay/malipopay-dotnet) | `dotnet add package MaliPoPay` |
+| [Ruby](https://github.com/Malipopay/malipopay-ruby) | `gem install malipopay` |
+
+[API Reference](https://developers.malipopay.co.tz) | [OpenAPI Spec](https://github.com/Malipopay/malipopay-openapi) | [Test Scenarios](https://github.com/Malipopay/malipopay-sdk-tests)
+

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/configuration.md

@@ -0,0 +1,300 @@
+# Configuration
+
+This guide covers all the ways to configure the MaliPoPay Ruby SDK, from basic client setup to Rails integration.
+
+## MaliPoPay::Client Options
+
+The `MaliPoPay::Client.new` constructor accepts the following options:
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: 'your_api_key',
+  environment: :production,   # or :uat
+  base_url: nil,              # overrides environment if set
+  timeout: 30,                # request timeout in seconds
+  retries: 2,                 # automatic retries on transient errors
+  webhook_secret: nil         # for webhook signature verification
+)
+```
+
+### Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | `String` | *required* | Your MaliPoPay API key |
+| `environment` | `Symbol` | `:production` | `:production` or `:uat` |
+| `base_url` | `String` | `nil` | Custom base URL; overrides `environment` when set |
+| `timeout` | `Integer` | `30` | HTTP request timeout in seconds |
+| `retries` | `Integer` | `2` | Number of automatic retries for transient errors |
+| `webhook_secret` | `String` | `nil` | HMAC-SHA256 secret for webhook signature verification |
+
+### Environment URLs
+
+| Environment | Base URL |
+|-------------|----------|
+| `:production` | `https://core-prod.malipopay.co.tz` |
+| `:uat` | `https://core-uat.malipopay.co.tz` |
+
+## Symbols vs Strings
+
+The SDK accepts both symbols and strings for the `environment` option. Symbols are the Ruby convention:
+
+```ruby
+# Preferred (symbol)
+client = MaliPoPay::Client.new(api_key: key, environment: :uat)
+
+# Also works (string)
+client = MaliPoPay::Client.new(api_key: key, environment: 'uat')
+```
+
+The same applies to provider names in payment methods -- you can use either:
+
+```ruby
+# Both work
+client.payments.collect(provider: 'M-Pesa', ...)
+client.payments.collect(provider: :'M-Pesa', ...)
+```
+
+## Basic Configuration
+
+### Minimal Setup
+
+```ruby
+# Production with defaults (30s timeout, 2 retries)
+client = MaliPoPay::Client.new(api_key: ENV['MALIPOPAY_API_KEY'])
+```
+
+### UAT for Testing
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_UAT_API_KEY'],
+  environment: :uat
+)
+```
+
+### Custom Timeout and Retries
+
+```ruby
+client = MaliPoPay::Client.new(
+  api_key: ENV['MALIPOPAY_API_KEY'],
+  environment: :production,
+  timeout: 60,    # longer timeout for slow networks
+  retries: 5      # more retries for critical operations
+)
+```
+
+## Environment Selection
+
+### Automatic Based on RACK_ENV / RAILS_ENV
+
+Tie the MaliPoPay environment to your application environment:
+
+```ruby
+malipopay_env = if ENV['RACK_ENV'] == 'production' || ENV['RAILS_ENV'] == 'production'
+                  :production
+                else
+                  :uat
+                end
+
+api_key = if malipopay_env == :production
+            ENV.fetch('MALIPOPAY_API_KEY')
+          else
+            ENV.fetch('MALIPOPAY_UAT_API_KEY')
+          end
+
+client = MaliPoPay::Client.new(
+  api_key: api_key,
+  environment: malipopay_env
+)
+```
+
+### Custom Base URL
+
+For proxies or custom routing:
+
+```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.
+
+## Rails Integration
+
+### Initializer
+
+Create a Rails initializer to configure the client globally:
+
+```ruby
+# config/initializers/malipopay.rb
+
+MALIPOPAY_CLIENT = MaliPoPay::Client.new(
+  api_key: Rails.application.credentials.dig(:malipopay, :api_key) ||
+           ENV.fetch('MALIPOPAY_API_KEY'),
+  environment: Rails.env.production? ? :production : :uat,
+  timeout: 30,
+  retries: 2,
+  webhook_secret: Rails.application.credentials.dig(:malipopay, :webhook_secret) ||
+                  ENV['MALIPOPAY_WEBHOOK_SECRET']
+)
+```
+
+Then use it anywhere in your Rails app:
+
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    result = MALIPOPAY_CLIENT.payments.collect(
+      amount: params[:amount].to_i,
+      currency: 'TZS',
+      phone: params[:phone],
+      provider: params[:provider],
+      reference: "ORD-#{SecureRandom.hex(6).upcase}",
+      description: params[:description]
+    )
+
+    if result['success']
+      render json: { status: 'initiated', reference: result['reference'] }
+    else
+      render json: { error: result['message'] }, status: :unprocessable_entity
+    end
+  rescue MaliPoPay::Error => e
+    render json: { error: e.message }, status: :service_unavailable
+  end
+end
+```
+
+### Rails Encrypted Credentials
+
+Store your API keys securely with Rails credentials:
+
+```bash
+EDITOR=vim rails credentials:edit
+```
+
+Add your MaliPoPay keys:
+
+```yaml
+malipopay:
+  api_key: your_production_api_key
+  webhook_secret: your_webhook_secret
+```
+
+Access them in your initializer:
+
+```ruby
+Rails.application.credentials.dig(:malipopay, :api_key)
+```
+
+### Per-Environment Credentials
+
+Use Rails environment-specific credentials:
+
+```bash
+EDITOR=vim rails credentials:edit --environment development
+```
+
+```yaml
+# config/credentials/development.yml.enc
+malipopay:
+  api_key: your_uat_api_key
+  webhook_secret: your_uat_webhook_secret
+```
+
+```bash
+EDITOR=vim rails credentials:edit --environment production
+```
+
+```yaml
+# config/credentials/production.yml.enc
+malipopay:
+  api_key: your_production_api_key
+  webhook_secret: your_production_webhook_secret
+```
+
+## Sinatra Integration
+
+For Sinatra apps, configure the client at the top of your app file:
+
+```ruby
+require 'sinatra'
+require 'malipopay'
+
+configure do
+  set :malipopay, MaliPoPay::Client.new(
+    api_key: ENV.fetch('MALIPOPAY_API_KEY'),
+    environment: settings.production? ? :production : :uat
+  )
+end
+
+post '/payments' do
+  result = settings.malipopay.payments.collect(
+    amount: params[:amount].to_i,
+    currency: 'TZS',
+    phone: params[:phone],
+    provider: 'M-Pesa',
+    reference: "ORD-#{SecureRandom.hex(6).upcase}",
+    description: 'Payment'
+  )
+
+  json result
+end
+```
+
+## Timeout and Retry Settings
+
+### Timeout
+
+The `timeout` option controls how long the SDK waits for an API response before raising `MaliPoPay::ConnectionError`:
+
+```ruby
+# Short timeout for fast-fail scenarios
+client = MaliPoPay::Client.new(api_key: key, timeout: 10)
+
+# Longer timeout for slow networks or large batch operations
+client = MaliPoPay::Client.new(api_key: key, timeout: 120)
+```
+
+### Retries
+
+The `retries` option controls how many times the SDK retries on transient errors (5xx and connection failures):
+
+```ruby
+# No automatic retries (handle retries yourself)
+client = MaliPoPay::Client.new(api_key: key, retries: 0)
+
+# Aggressive retries for critical operations
+client = MaliPoPay::Client.new(api_key: key, retries: 5)
+```
+
+The SDK uses exponential backoff between retries (1s, 2s, 4s, ...).
+
+## Security Best Practices
+
+1. **Never hardcode API keys.** Use environment variables or Rails encrypted credentials.
+
+2. **Use `.env` files for local development** (with [dotenv](https://github.com/bkeepers/dotenv)):
+   ```ruby
+   # Gemfile
+   gem 'dotenv-rails', groups: [:development, :test]
+   ```
+
+   ```bash
+   # .env (add to .gitignore!)
+   MALIPOPAY_API_KEY=your_uat_key
+   MALIPOPAY_WEBHOOK_SECRET=your_webhook_secret
+   ```
+
+3. **Rotate keys regularly.** Generate new keys at [app.malipopay.co.tz](https://app.malipopay.co.tz) and update your credentials store.
+
+4. **Use separate keys per environment.** Never share keys between UAT and production.
+
+## Next Steps
+
+- [Getting Started](./getting-started.md) -- quick start guide
+- [Error Handling](./error-handling.md) -- handle errors and configure retries
+- [Webhooks](./webhooks.md) -- webhook configuration
+- [Payments](./payments.md) -- payment operations