malipopay 1.0.0

data/docs/invoices.md

@@ -0,0 +1,200 @@
+# Invoices
+
+The `invoices` resource lets you create, manage, and track invoices. Invoices can include line items with tax, and you can record payments against them as they come in.
+
+## Create an Invoice
+
+```ruby
+invoice = client.invoices.create(
+  customer_id: 'cust_abc123',
+  currency: 'TZS',
+  due_date: '2024-03-15',
+  items: [
+    {
+      description: 'Website Development',
+      quantity: 1,
+      unit_price: 2_500_000
+    },
+    {
+      description: 'Domain Registration (.co.tz)',
+      quantity: 1,
+      unit_price: 75_000
+    },
+    {
+      description: 'Hosting (12 months)',
+      quantity: 12,
+      unit_price: 50_000
+    }
+  ],
+  notes: 'Payment due within 15 days. M-Pesa and bank transfer accepted.',
+  tax_rate: 18  # VAT at 18%
+)
+
+if invoice['success']
+  puts "Invoice created: #{invoice['data']['id']}"
+end
+```
+
+In this example, the subtotal is TZS 3,175,000 (2,500,000 + 75,000 + 600,000), and with 18% VAT the total would be TZS 3,746,500.
+
+## Tax Calculation
+
+MaliPoPay calculates tax automatically based on the `tax_rate` you provide:
+
+```ruby
+# Invoice with 18% VAT (Tanzania standard rate)
+invoice = client.invoices.create(
+  customer_id: 'cust_abc123',
+  currency: 'TZS',
+  due_date: '2024-04-30',
+  items: [
+    { description: 'Consulting (8 hours)', quantity: 8, unit_price: 150_000 }
+  ],
+  tax_rate: 18
+)
+
+# Subtotal: TZS 1,200,000
+# VAT (18%): TZS 216,000
+# Total: TZS 1,416,000
+```
+
+For tax-exempt invoices, omit the `tax_rate` field or set it to `0`:
+
+```ruby
+invoice = client.invoices.create(
+  customer_id: 'cust_abc123',
+  currency: 'TZS',
+  due_date: '2024-04-30',
+  items: [
+    { description: 'Government service (exempt)', quantity: 1, unit_price: 500_000 }
+  ],
+  tax_rate: 0
+)
+```
+
+## List Invoices
+
+```ruby
+invoices = client.invoices.list
+
+if invoices['success']
+  invoices['data'].each do |inv|
+    puts "#{inv['id']}: TZS #{inv['total']} (#{inv['status']})"
+  end
+end
+```
+
+## Get an Invoice by ID
+
+```ruby
+invoice = client.invoices.get('inv_xyz789')
+
+if invoice['success']
+  puts "Invoice: #{invoice['data']}"
+end
+```
+
+## Record a Payment Against an Invoice
+
+When a customer makes a partial or full payment, record it against the invoice:
+
+```ruby
+# Record a partial payment
+partial = client.invoices.record_payment(
+  invoice_id: 'inv_xyz789',
+  amount: 1_000_000,
+  reference: 'MPESA-TXN-ABC123',
+  payment_method: 'M-Pesa',
+  notes: 'Partial payment received via M-Pesa'
+)
+
+# Later, record the remaining balance
+final = client.invoices.record_payment(
+  invoice_id: 'inv_xyz789',
+  amount: 2_746_500,
+  reference: 'CRDB-TXN-DEF456',
+  payment_method: 'Bank Transfer',
+  notes: 'Final payment via CRDB bank transfer'
+)
+```
+
+## Approve a Draft Invoice
+
+Invoices may start as drafts. Approve them when ready to send to the customer:
+
+```ruby
+approval = client.invoices.approve_draft(invoice_id: 'inv_draft_001')
+
+if approval['success']
+  puts 'Invoice approved and ready to send.'
+end
+```
+
+## Invoice Workflow
+
+A typical invoice lifecycle:
+
+1. **Create** the invoice with line items and tax
+2. **Approve** the draft (optional, depending on your workflow)
+3. **Send** the invoice to the customer (via email, SMS, or payment link)
+4. **Collect** payment using a mobile money collection or payment link
+5. **Record** the payment against the invoice
+6. Invoice status moves to **Paid** when the full amount is received
+
+### Combining Invoices with Payment Collection
+
+```ruby
+# Step 1: Create the invoice
+invoice = client.invoices.create(
+  customer_id: 'cust_abc123',
+  currency: 'TZS',
+  due_date: '2024-02-28',
+  items: [
+    { description: 'Consulting (8 hours)', quantity: 8, unit_price: 150_000 }
+  ]
+)
+
+# Step 2: Collect payment via M-Pesa
+collection = client.payments.collect(
+  amount: 1_200_000,
+  currency: 'TZS',
+  phone: '255712345678',
+  provider: 'M-Pesa',
+  reference: 'inv_xyz789',
+  description: 'Invoice #INV-2024-0042 payment'
+)
+
+# Step 3: After webhook confirms payment, record it
+record = client.invoices.record_payment(
+  invoice_id: 'inv_xyz789',
+  amount: 1_200_000,
+  reference: 'MPESA-TXN-GHI789',
+  payment_method: 'M-Pesa'
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  invoice = client.invoices.create(
+    customer_id: 'nonexistent_customer',
+    currency: 'TZS',
+    items: [
+      { description: 'Test', quantity: 1, unit_price: 1_000 }
+    ]
+  )
+rescue MaliPoPay::ValidationError => e
+  puts "Invalid invoice data: #{e.message}"
+rescue MaliPoPay::NotFoundError
+  puts 'Customer not found. Create the customer first.'
+rescue MaliPoPay::Error => e
+  puts "Invoice error: #{e.message}"
+end
+```
+
+## Next Steps
+
+- [Payments](./payments.md) -- collect payments for your invoices
+- [Customers](./customers.md) -- manage the customers you invoice
+- [Webhooks](./webhooks.md) -- get notified when payments are received

data/docs/payments.md

@@ -0,0 +1,284 @@
+# Payments
+
+The `payments` resource handles all payment operations: mobile money collections, disbursements, payment verification, payment links, and search.
+
+## How Payments Work in Tanzania
+
+MaliPoPay integrates with Tanzania's major mobile money and banking networks:
+
+- **Vodacom M-Pesa** -- largest mobile money network
+- **Airtel Money** -- second-largest MNO
+- **Tigo Pesa (Mixx by Yas)** -- merged MNO brand
+- **Halotel Halopesa** -- growing rural network
+- **TTCL T-Pesa** -- state telco mobile money
+- **USSD (*146*08#)** -- unified USSD payment channel
+- **Bank transfers** -- CRDB, NMB, and other banks via H2H integration
+- **Card payments** -- Visa and Mastercard
+
+### Collection Flow
+
+1. Your app calls `collect` with the customer's phone number and amount
+2. MaliPoPay sends a USSD push to the customer's phone
+3. The customer sees a prompt like: *"Pay TZS 50,000 to ACME Ltd? Enter PIN to confirm"*
+4. The customer enters their mobile money PIN
+5. MaliPoPay receives the confirmation and notifies you via webhook
+6. You can also poll using `verify`
+
+### Disbursement Flow
+
+1. Your app calls `disburse` with the recipient's phone/account and amount
+2. MaliPoPay processes the transfer from your merchant float
+3. The recipient receives the funds in their mobile money or bank account
+4. You receive a webhook notification with the result
+
+## Mobile Money Collection
+
+Collect payments from any supported mobile money provider:
+
+```ruby
+# M-Pesa collection
+mpesa = client.payments.collect(
+  amount: 75_000,
+  currency: 'TZS',
+  phone: '255712345678',
+  provider: 'M-Pesa',
+  reference: 'INV-2024-0042',
+  description: 'Invoice payment - Office furniture'
+)
+
+# Airtel Money collection
+airtel = client.payments.collect(
+  amount: 25_000,
+  currency: 'TZS',
+  phone: '255782345678',
+  provider: 'Airtel Money',
+  reference: 'INV-2024-0043',
+  description: 'Delivery fee'
+)
+
+# Halopesa collection
+halo = client.payments.collect(
+  amount: 10_000,
+  currency: 'TZS',
+  phone: '255622345678',
+  provider: 'Halopesa',
+  reference: 'INV-2024-0044',
+  description: 'Service charge'
+)
+
+# Tigo Pesa / Mixx by Yas collection
+tigo = client.payments.collect(
+  amount: 35_000,
+  currency: 'TZS',
+  phone: '255652345678',
+  provider: 'Mixx',
+  reference: 'INV-2024-0045',
+  description: 'Consultation fee'
+)
+
+# T-Pesa collection
+tpesa = client.payments.collect(
+  amount: 20_000,
+  currency: 'TZS',
+  phone: '255742345678',
+  provider: 'T-Pesa',
+  reference: 'INV-2024-0046',
+  description: 'Registration fee'
+)
+```
+
+## Card Payments
+
+Collect payments via Visa or Mastercard:
+
+```ruby
+card = client.payments.collect(
+  amount: 150_000,
+  currency: 'TZS',
+  provider: 'Card',
+  reference: 'INV-2024-0050',
+  description: 'Annual membership',
+  customer_email: 'juma@example.com',
+  redirect_url: 'https://yoursite.co.tz/payment/success'
+)
+
+# The result includes a checkout URL for the customer
+puts "Redirect customer to: #{card['checkout_url']}"
+```
+
+## Disbursement
+
+Send money to mobile money wallets or bank accounts:
+
+```ruby
+# Disburse to M-Pesa wallet
+disbursement = client.payments.disburse(
+  amount: 150_000,
+  currency: 'TZS',
+  phone: '255712345678',
+  provider: 'M-Pesa',
+  reference: 'PAYOUT-2024-001',
+  description: 'Salary payment - January 2024'
+)
+
+# Disburse to bank account (CRDB)
+bank_disbursement = client.payments.disburse(
+  amount: 500_000,
+  currency: 'TZS',
+  account_number: '01J1234567890',
+  bank_code: 'CRDB',
+  account_name: 'Juma Hassan',
+  reference: 'PAYOUT-2024-002',
+  description: 'Vendor payment'
+)
+
+# Disburse to NMB account
+nmb_disbursement = client.payments.disburse(
+  amount: 2_500_000,
+  currency: 'TZS',
+  account_number: '2345678901',
+  bank_code: 'NMB',
+  account_name: 'Maria Joseph',
+  reference: 'PAYOUT-2024-003',
+  description: 'Contractor payout'
+)
+```
+
+## Payment Verification
+
+After initiating a collection, verify the payment status. In production you should rely on webhooks, but polling is useful for synchronous flows and reconciliation:
+
+```ruby
+# Verify by reference
+status = client.payments.verify('INV-2024-0042')
+
+if status['success']
+  puts "Payment status: #{status['status']}"
+end
+```
+
+### Polling with Timeout
+
+For cases where you need to wait for the customer to complete the payment:
+
+```ruby
+def wait_for_payment(client, reference, timeout: 120, interval: 5)
+  deadline = Time.now + timeout
+
+  while Time.now < deadline
+    result = client.payments.verify(reference)
+
+    return true if result['status'] == 'completed'
+    return false if result['status'] == 'failed'
+
+    sleep interval
+  end
+
+  false # timed out
+end
+
+# Wait up to 2 minutes, polling every 5 seconds
+paid = wait_for_payment(client, 'INV-2024-0042')
+```
+
+> **Recommendation:** Use webhooks instead of polling in production. Polling is acceptable for testing, CLI tools, and reconciliation scripts.
+
+## Payment Links
+
+Generate a shareable payment link that customers can use to pay via any supported method:
+
+```ruby
+link = client.payments.pay(
+  amount: 250_000,
+  currency: 'TZS',
+  reference: 'LINK-2024-001',
+  description: 'Annual membership fee',
+  customer_name: 'Asha Mwalimu',
+  customer_email: 'asha@example.com',
+  customer_phone: '255712345678',
+  redirect_url: 'https://yoursite.co.tz/payment/success',
+  callback_url: 'https://yoursite.co.tz/api/webhooks/malipopay'
+)
+
+puts "Send this link to the customer: #{link['payment_url']}"
+```
+
+## Retry Failed Collections
+
+If a collection failed due to a transient issue (timeout, network error), you can retry it:
+
+```ruby
+retry_result = client.payments.retry('INV-2024-0042')
+
+if retry_result['success']
+  puts 'Collection retry initiated. Customer will receive a new USSD push.'
+end
+```
+
+## List and Search Payments
+
+### List All Payments
+
+```ruby
+payments = client.payments.list
+
+if payments['success']
+  puts "Total payments: #{payments['data'].length}"
+end
+```
+
+### Search Payments
+
+```ruby
+results = client.payments.search
+```
+
+### Get Payment by Reference
+
+```ruby
+payment = client.payments.get_by_reference('INV-2024-0042')
+
+if payment['success']
+  puts "Amount: #{payment['data']['amount']}"
+  puts "Status: #{payment['data']['status']}"
+  puts "Provider: #{payment['data']['provider']}"
+end
+```
+
+## Error Handling for Payments
+
+Always wrap payment operations in begin/rescue:
+
+```ruby
+begin
+  result = client.payments.collect(
+    amount: 50_000,
+    currency: 'TZS',
+    phone: '255712345678',
+    provider: 'M-Pesa',
+    reference: 'ORDER-001',
+    description: 'Test payment'
+  )
+rescue MaliPoPay::ValidationError => e
+  # Invalid parameters (wrong phone format, missing fields, etc.)
+  puts "Validation error: #{e.message}"
+rescue MaliPoPay::AuthenticationError
+  # Bad API key
+  puts 'Check your API key.'
+rescue MaliPoPay::RateLimitError
+  # Too many requests -- back off and retry
+  puts 'Rate limited. Please wait and retry.'
+rescue MaliPoPay::ConnectionError => e
+  # Network issue
+  puts "Network error: #{e.message}"
+rescue MaliPoPay::Error => e
+  # Catch-all for other SDK errors
+  puts "Payment error: #{e.message}"
+end
+```
+
+## Next Steps
+
+- [Webhooks](./webhooks.md) -- receive real-time payment status updates
+- [Invoices](./invoices.md) -- create invoices and record payments against them
+- [Error Handling](./error-handling.md) -- comprehensive error handling patterns

data/docs/sms.md

@@ -0,0 +1,182 @@
+# SMS
+
+The `sms` resource lets you send transactional and promotional SMS messages to Tanzanian phone numbers. You can send single messages, bulk messages to multiple recipients, and schedule messages for future delivery.
+
+## Sending a Single SMS
+
+```ruby
+sms = client.sms.send_message(
+  to: '255712345678',
+  message: 'Your payment of TZS 50,000 has been confirmed. Reference: ORD-2024-100. Thank you for shopping with us!',
+  sender_id: 'MALIPOPAY'
+)
+
+if sms['success']
+  puts "SMS sent: #{sms['data']}"
+else
+  puts "Failed: #{sms['message']}"
+end
+```
+
+### With Error Handling
+
+```ruby
+begin
+  sms = client.sms.send_message(
+    to: '255754321098',
+    message: 'Dear Amina, your invoice INV-2024-042 of TZS 3,746,500 is due on 15 March 2024. Pay via M-Pesa to avoid late fees.',
+    sender_id: 'ACME'
+  )
+
+  puts "Message delivered: #{sms['data']}"
+rescue MaliPoPay::ValidationError => e
+  puts "Invalid request: #{e.message}"
+rescue MaliPoPay::Error => e
+  puts "SMS error: #{e.message}"
+end
+```
+
+## Bulk SMS
+
+Send the same message or different messages to multiple recipients at once.
+
+### Same Message to Multiple Recipients
+
+```ruby
+bulk = client.sms.send_bulk(
+  recipients: [
+    '255712345678',
+    '255754321098',
+    '255622345678',
+    '255652345678',
+    '255742345678'
+  ],
+  message: 'Reminder: Our office will be closed on Monday 1st January for the New Year holiday. Happy New Year from ACME Ltd!',
+  sender_id: 'ACME'
+)
+
+if bulk['success']
+  puts "Bulk SMS sent to #{bulk['data']} recipients"
+end
+```
+
+### Individual Messages per Recipient
+
+```ruby
+personalized = client.sms.send_bulk(
+  messages: [
+    {
+      to: '255712345678',
+      message: 'Hi Juma, your account balance is TZS 125,000. Login at app.malipopay.co.tz to view details.'
+    },
+    {
+      to: '255754321098',
+      message: 'Hi Amina, your account balance is TZS 340,500. Login at app.malipopay.co.tz to view details.'
+    },
+    {
+      to: '255622345678',
+      message: 'Hi Baraka, your account balance is TZS 78,200. Login at app.malipopay.co.tz to view details.'
+    }
+  ],
+  sender_id: 'ACME'
+)
+```
+
+## Scheduling SMS
+
+Schedule messages for future delivery by providing a `scheduled_at` timestamp in ISO 8601 format. All times are in East Africa Time (EAT, UTC+3):
+
+```ruby
+# Schedule a payment reminder for 9:00 AM tomorrow
+scheduled = client.sms.send_message(
+  to: '255712345678',
+  message: 'Reminder: Your subscription of TZS 15,000 is due tomorrow. Pay now via M-Pesa to avoid interruption.',
+  sender_id: 'ACME',
+  scheduled_at: '2024-03-15T09:00:00+03:00'
+)
+
+if scheduled['success']
+  puts "SMS scheduled: #{scheduled['data']}"
+end
+```
+
+### Schedule Bulk SMS
+
+```ruby
+# Schedule a promotional message for Friday at 2:00 PM
+scheduled_bulk = client.sms.send_bulk(
+  recipients: [
+    '255712345678',
+    '255754321098',
+    '255652345678'
+  ],
+  message: 'Weekend offer! Get 20% off all services this Saturday and Sunday. Visit our shop on Samora Avenue or pay via M-Pesa. Code: WEEKEND20',
+  sender_id: 'ACME',
+  scheduled_at: '2024-03-15T14:00:00+03:00'
+)
+```
+
+## Sender IDs
+
+The `sender_id` field controls what appears as the sender on the recipient's phone. This is the name or short code displayed instead of a phone number.
+
+| Sender ID | Description |
+|-----------|-------------|
+| `MALIPOPAY` | Default MaliPoPay sender ID |
+| Custom (e.g., `ACME`) | Your registered brand name |
+
+### Registering a Custom Sender ID
+
+Custom sender IDs must be registered and approved in your MaliPoPay dashboard:
+
+1. Go to [app.malipopay.co.tz](https://app.malipopay.co.tz) > **Settings > SMS > Sender IDs**
+2. Click **Request New Sender ID**
+3. Enter your desired sender name (up to 11 characters, alphanumeric)
+4. Submit for approval -- this typically takes 24-48 hours
+
+> **Note:** TCRA regulations in Tanzania require sender IDs to be registered. Unregistered sender IDs will be replaced with a default numeric sender.
+
+## SMS Character Limits
+
+Standard SMS messages have a 160-character limit per segment. Messages longer than 160 characters are split into multiple segments and reassembled on the recipient's device:
+
+| Length | Segments | Effective Characters per Segment |
+|--------|----------|----------------------------------|
+| 1--160 | 1 | 160 |
+| 161--306 | 2 | 153 (7 bytes used for concatenation header) |
+| 307--459 | 3 | 153 |
+
+Billing is per segment. Keep messages concise to minimize costs.
+
+## Complete Example: Payment Confirmation SMS
+
+A common pattern is sending an SMS after a successful payment webhook:
+
+```ruby
+# In your Sinatra/Rails webhook handler
+post '/webhooks/malipopay' do
+  # ... verify signature (see Webhooks guide) ...
+
+  event = verifier.construct_event(payload, signature)
+
+  if event['event_type'] == 'payment.completed'
+    client.sms.send_message(
+      to: event['phone'],
+      message: "Payment confirmed! TZS #{event['amount']} received for #{event['reference']}. " \
+               "Transaction ID: #{event['transaction_id']}. Thank you!",
+      sender_id: 'ACME'
+    )
+
+    puts "Confirmation SMS sent to #{event['phone']}"
+  end
+
+  status 200
+end
+```
+
+## Next Steps
+
+- [Payments](./payments.md) -- collect payments that trigger SMS notifications
+- [Webhooks](./webhooks.md) -- automate SMS sending from webhook events
+- [Error Handling](./error-handling.md) -- handle SMS delivery failures
+- [Configuration](./configuration.md) -- configure timeouts and retries