MaliPoPay Ruby SDK

Official Ruby SDK for the MaliPoPay payment platform (Tanzania).

Installation

Add to your Gemfile:

gem "malipopay"

Then run:

bundle install

Or install directly:

gem install malipopay

Quick Start

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

# 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

# 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

# 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

# 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

# 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

# Get account transactions
txns = client..transactions(dateFrom: "2026-01-01")

# Reconciliation
recon = client..reconciliation(dateFrom: "2026-01-01", dateTo: "2026-03-31")

# Financial reports
client..financial_position
client..income_statement
client..general_ledger
client..trial_balance

SMS

# 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

banks = client.references.banks
currencies = client.references.currencies
countries = client.references.countries
institutions = client.references.institutions
business_types = client.references.business_types

Webhooks

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

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

See Also

SDK Install
Node.js npm install malipopay
Python pip install malipopay
PHP composer require malipopay/malipopay-php
Java Maven / Gradle
.NET dotnet add package MaliPoPay
Ruby gem install malipopay

API Reference | OpenAPI Spec | Test Scenarios