@bloonio/lokotro-pay 1.0.0

package/README.md

@@ -0,0 +1,585 @@
+# @bloonio/lokotro-pay
+
+Angular SDK for Lokotro Pay - A comprehensive payment processing library with support for multiple payment methods including cards, mobile money, e-wallets, and more.
+
+## ✨ Features
+
+- 🎨 **Glassmorphism UI** - Beautiful dark theme with modern glass effects
+- 🌍 **Multi-language Support** - 10 languages (EN, FR, ES, DE, IT, RU, HI, JA, ZH, LN)
+- 💳 **Multiple Payment Methods** - Card (Mastercard Hosted Session), Mobile Money, E-Wallet, Flash, Bank Transfer
+- 📱 **Responsive Design** - Works on all screen sizes
+- ⚡ **Angular 17+** - Built with standalone components
+- 🔒 **Secure** - Built-in encryption and secure payment handling
+- 🎯 **Type Safe** - Full TypeScript support
+
+## 📦 Installation
+
+```bash
+npm install @bloonio/lokotro-pay
+# or
+yarn add @bloonio/lokotro-pay
+```
+
+## 🚀 Quick Start
+
+### Basic Usage (Standalone Components - Recommended)
+
+```typescript
+import { Component } from '@angular/core';
+import {
+  LokotroCheckoutComponent,
+  LokotroPayConfig,
+  LokotroPaymentBody,
+  LokotroPayOnResponse,
+  LokotroPayOnError
+} from '@bloonio/lokotro-pay';
+
+@Component({
+  selector: 'app-payment',
+  standalone: true,
+  imports: [LokotroCheckoutComponent],
+  template: `
+    <lokotro-checkout
+      [configs]="configs"
+      [paymentBody]="paymentBody"
+      (onResponse)="handleSuccess($event)"
+      (onError)="handleError($event)"
+    />
+  `
+})
+export class PaymentComponent {
+  // API Configuration
+  configs: LokotroPayConfig = {
+    token: 'your_encrypted_app_key',
+    isProduction: false,
+    acceptLanguage: 'en'
+  };
+
+  // Payment Request
+  paymentBody: LokotroPaymentBody = {
+    customerReference: `ORDER_${Date.now()}`,
+    amount: '50.00',
+    currency: 'USD',
+    paymentMethod: 'wallet',
+    userInfo: 'full',
+    paymentMethodInfo: 'full',
+    feeCoveredBy: 'buyer',
+    deliveryBehaviour: 'direct_delivery',
+    // User information
+    firstName: 'John',
+    lastName: 'Doe',
+    phoneNumber: '2439978540000',
+    email: 'johndoe@email.com',
+    // E-wallet credentials
+    walletNumber: '3005710720108954',
+    walletPin: '048698',
+    // Callbacks
+    notifyUrl: 'https://yourserver.com/notify',
+    successRedirectUrl: 'https://yourserver.com/success',
+    failRedirectUrl: 'https://yourserver.com/failed',
+    // Merchant info
+    merchant: {
+      id: 'merchant_123',
+      name: 'My Store',
+      logoUrl: 'https://mystore.com/logo.png',
+      website: 'https://mystore.com'
+    },
+    metadata: { orderId: '12345' }
+  };
+
+  handleSuccess(response: LokotroPayOnResponse) {
+    console.log('Payment successful!', response);
+  }
+
+  handleError(error: LokotroPayOnError) {
+    console.error('Payment failed:', error.message);
+  }
+}
+```
+
+### Using NgModule
+
+```typescript
+import { NgModule } from '@angular/core';
+import { LokotroPayModule } from '@bloonio/lokotro-pay';
+
+@NgModule({
+  imports: [LokotroPayModule]
+})
+export class AppModule {}
+```
+
+## 📖 Configuration
+
+### LokotroPayConfig
+
+Configure your payment environment and authentication:
+
+```typescript
+const configs: LokotroPayConfig = {
+  token: 'your_encrypted_app_key',   // Required: Encrypted API key
+  isProduction: false,               // Optional: Environment (default: false)
+  customApiUrl: 'https://api.custom.com', // Optional: Custom API endpoint
+  timeout: 60000,                    // Optional: Request timeout in ms
+  acceptLanguage: 'en'               // Optional: API response language
+};
+```
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `token` | `string` | Yes | - | Encrypted API key from backend |
+| `isProduction` | `boolean` | No | `false` | Use production environment |
+| `customApiUrl` | `string` | No | - | Custom API endpoint |
+| `timeout` | `number` | No | `30000` | Request timeout (ms) |
+| `acceptLanguage` | `string` | No | `'fr'` | Language for API responses |
+
+### LokotroPaymentBody
+
+Define your payment request details:
+
+```typescript
+const paymentBody: LokotroPaymentBody = {
+  // Required fields
+  customerReference: 'ORDER_12345',  // Unique customer reference
+  amount: '100.00',                  // Amount as string
+  currency: 'USD',                   // Currency code
+
+  // Payment configuration
+  paymentMethod: 'wallet',           // wallet, card, mobile_money, flash, bank_transfer
+  userInfo: 'full',                  // full, partial, none - controls user form visibility
+  paymentMethodInfo: 'full',         // full, partial, none - controls payment method form
+  feeCoveredBy: 'buyer',             // buyer or seller
+  deliveryBehaviour: 'direct_delivery', // direct_delivery or escrow
+
+  // User information (required when userInfo = 'full')
+  firstName: 'John',
+  lastName: 'Doe',
+  phoneNumber: '2439978540000',
+  email: 'johndoe@email.com',
+
+  // E-wallet fields (when paymentMethod = 'wallet')
+  walletNumber: '3005710720108954',
+  walletPin: '048698',
+
+  // Mobile money fields (when paymentMethod = 'mobile_money')
+  mobileMoneyPhoneNumber: '2439978540000',
+
+  // Flash fields (when paymentMethod = 'flash')
+  flashNumber: '1234567890',
+  flashPin: '1234',
+
+  // Card fields (when paymentMethod = 'card' with DIRECT_CAPTURE)
+  cardNumber: '4111111111111111',
+  cardExpiryDate: '12/25',
+  cardCvv: '123',
+  cardHolderName: 'John Doe',
+
+  // Mastercard payment method (for card payments)
+  mastercardPaymentMethod: 'HOSTED_SESSION', // or 'DIRECT_CAPTURE'
+
+  // Callback URLs
+  notifyUrl: 'https://yourserver.com/notify',
+  successRedirectUrl: 'https://yourserver.com/success',
+  failRedirectUrl: 'https://yourserver.com/failed',
+
+  // Merchant information
+  merchant: {
+    id: 'merchant_123',
+    name: 'My Store',
+    logoUrl: 'https://mystore.com/logo.png',
+    website: 'https://mystore.com'
+  },
+
+  // Additional metadata
+  metadata: { orderId: '12345', source: 'web' }
+};
+```
+
+## 💳 Payment Methods
+
+### Supported Payment Methods
+
+| Method | Value | Description |
+|--------|-------|-------------|
+| E-Wallet | `wallet` | Lokotro wallet payments |
+| Card | `card` | Credit/Debit card (Mastercard Hosted Session) |
+| Mobile Money | `mobile_money` | Mobile money providers |
+| Flash | `flash` | Lokotro Flash instant payments |
+| Bank Transfer | `bank_transfer` | Direct bank transfers |
+
+### Payment Method Examples
+
+#### E-Wallet Payment
+
+```typescript
+const paymentBody: LokotroPaymentBody = {
+  customerReference: `WALLET_${Date.now()}`,
+  amount: '50.00',
+  currency: 'USD',
+  paymentMethod: 'wallet',
+  userInfo: 'full',
+  paymentMethodInfo: 'full',
+  firstName: 'John',
+  lastName: 'Doe',
+  phoneNumber: '2439978540000',
+  email: 'johndoe@email.com',
+  walletNumber: '3005710720108954',
+  walletPin: '048698'
+};
+```
+
+#### Mobile Money Payment
+
+```typescript
+const paymentBody: LokotroPaymentBody = {
+  customerReference: `MOMO_${Date.now()}`,
+  amount: '25.00',
+  currency: 'USD',
+  paymentMethod: 'mobile_money',
+  userInfo: 'full',
+  paymentMethodInfo: 'full',
+  firstName: 'John',
+  lastName: 'Doe',
+  phoneNumber: '2439978540000',
+  email: 'johndoe@email.com',
+  mobileMoneyPhoneNumber: '2439978540000'
+};
+```
+
+#### Card Payment (Hosted Session - Recommended)
+
+```typescript
+const paymentBody: LokotroPaymentBody = {
+  customerReference: `CARD_${Date.now()}`,
+  amount: '100.00',
+  currency: 'USD',
+  paymentMethod: 'card',
+  userInfo: 'full',
+  paymentMethodInfo: 'full',
+  mastercardPaymentMethod: 'HOSTED_SESSION',
+  firstName: 'John',
+  lastName: 'Doe',
+  phoneNumber: '2439978540000',
+  email: 'johndoe@email.com',
+  successRedirectUrl: 'https://yourserver.com/success',
+  failRedirectUrl: 'https://yourserver.com/failed',
+  notifyUrl: 'https://yourserver.com/notify'
+};
+```
+
+#### Flash Payment
+
+```typescript
+const paymentBody: LokotroPaymentBody = {
+  customerReference: `FLASH_${Date.now()}`,
+  amount: '10.00',
+  currency: 'USD',
+  paymentMethod: 'flash',
+  userInfo: 'full',
+  paymentMethodInfo: 'full',
+  firstName: 'John',
+  lastName: 'Doe',
+  phoneNumber: '2439978540000',
+  email: 'johndoe@email.com',
+  flashNumber: '1234567890',
+  flashPin: '1234'
+};
+```
+
+### User Info & Payment Method Info Options
+
+Control which forms are shown to the user:
+
+| `userInfo` | `paymentMethodInfo` | User Form | Payment Form |
+|------------|---------------------|-----------|--------------|
+| `none` | `none` | Visible | Visible |
+| `full` | `none` | Hidden | Visible |
+| `none` | `full` | Visible | Hidden |
+| `full` | `full` | Hidden | Hidden |
+
+```typescript
+// Show both forms (user enters all info)
+const paymentBody: LokotroPaymentBody = {
+  userInfo: 'none',
+  paymentMethodInfo: 'none',
+  // ... other fields
+};
+
+// Pre-fill user info, show payment form only
+const paymentBody: LokotroPaymentBody = {
+  userInfo: 'full',
+  paymentMethodInfo: 'none',
+  firstName: 'John',
+  lastName: 'Doe',
+  // ... other fields
+};
+```
+
+## 🎨 Styling
+
+### Import Global Styles
+
+Add to your `angular.json` or `styles.scss`:
+
+```scss
+@import '@bloonio/lokotro-pay/styles/lokotro-pay.scss';
+```
+
+### CSS Variables
+
+Override theme variables in your styles:
+
+```css
+:root {
+  --lokotro-primary: #5A5E39;
+  --lokotro-accent: #3BFBDA;
+  --lokotro-background: #1C2621;
+  --lokotro-text-primary: #F2F0D5;
+}
+```
+
+## 🌐 Multi-Language Support
+
+### Setting Language
+
+```typescript
+import { LokotroLocalizationService, LokotroPayLanguage } from '@bloonio/lokotro-pay';
+
+constructor(private localization: LokotroLocalizationService) {
+  this.localization.setLanguage(LokotroPayLanguage.French);
+}
+```
+
+### Supported Languages
+
+| Language | Code | Native Name |
+|----------|------|-------------|
+| English | `en` | English |
+| French | `fr` | Français |
+| German | `de` | Deutsch |
+| Spanish | `es` | Español |
+| Italian | `it` | Italiano |
+| Russian | `ru` | Русский |
+| Hindi | `hi` | हिंदी |
+| Japanese | `ja` | 日本語 |
+| Chinese | `zh` | 中文 |
+| Lingala | `ln` | Lingala |
+
+## 🔧 Advanced Usage
+
+### Using the Payment Service Directly
+
+```typescript
+import { LokotroPaymentService } from '@bloonio/lokotro-pay';
+
+@Component({...})
+export class MyComponent {
+  constructor(private paymentService: LokotroPaymentService) {
+    // Subscribe to payment state changes
+    this.paymentService.state$.subscribe(state => {
+      console.log('Payment state:', state);
+    });
+  }
+
+  async initiatePayment() {
+    await this.paymentService.initiatePayment(configs, paymentBody);
+  }
+}
+```
+
+## API Reference
+
+### Services
+
+#### LokotroPaymentService
+
+| Method | Description |
+|--------|-------------|
+| `initiatePayment(config, body)` | Start a new payment |
+| `submitPayment(channel, data)` | Submit payment with specific method |
+| `verifyOtp(otp)` | Verify OTP code |
+| `resendOtp()` | Resend OTP |
+| `cancelPayment()` | Cancel current payment |
+| `state$` | Observable of payment state |
+
+#### LokotroLocalizationService
+
+| Method | Description |
+|--------|-------------|
+| `setLanguage(lang)` | Set UI language |
+| `translate(key, params?)` | Translate a key |
+| `currentLanguage$` | Observable of current language |
+
+#### LokotroHttpClientService
+
+| Method | Description |
+|--------|-------------|
+| `get<T>(url)` | HTTP GET request |
+| `post<T>(url, body)` | HTTP POST request |
+| `setAppKey(key)` | Set API app key |
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `LokotroCheckoutComponent` | Main checkout widget |
+| `LokotroPaymentStatusComponent` | Payment status tracker (uses only paymentId) |
+| `LokotroPaymentMethodSelectionComponent` | Payment method grid |
+| `LokotroPaymentFormComponent` | Payment forms |
+| `LokotroOtpVerificationComponent` | OTP input |
+| `LokotroProcessingComponent` | Processing spinner |
+| `LokotroResultComponent` | Success/error screens |
+| `LokotroLoadingComponent` | Loading indicator |
+
+## Payment Status Tracking
+
+Use `LokotroPaymentStatusComponent` when you only have a payment ID and want to track the payment status. This is useful for scenarios where the payment was initiated elsewhere (e.g., from a Flutter app or server-side).
+
+### Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import {
+  LokotroPaymentStatusComponent,
+  LokotroPaymentStatusConfig,
+  LokotroPaymentStatusResponse,
+  LokotroPayLanguage
+} from '@bloonio/lokotro-pay';
+
+@Component({
+  selector: 'app-payment-status',
+  standalone: true,
+  imports: [LokotroPaymentStatusComponent],
+  template: `
+    <lokotro-payment-status
+      [statusConfig]="statusConfig"
+      (statusChange)="onStatusChange($event)"
+      (paymentComplete)="onPaymentComplete($event)"
+      (paymentFailed)="onPaymentFailed($event)"
+      (onClose)="onClose()"
+    />
+  `
+})
+export class PaymentStatusPageComponent {
+  statusConfig: LokotroPaymentStatusConfig = {
+    paymentId: 'your-payment-id', // Only the payment ID is required!
+    config: {
+      token: 'your-app-key',
+      isProduction: false
+    },
+    pollingInterval: 5000, // Check every 5 seconds
+    maxPollingAttempts: 60, // Stop after 5 minutes
+    language: LokotroPayLanguage.French
+  };
+
+  onStatusChange(response: LokotroPaymentStatusResponse) {
+    console.log('Status changed:', response.status);
+  }
+
+  onPaymentComplete(response: LokotroPaymentStatusResponse) {
+    console.log('Payment completed!', response);
+    // Navigate to success page or update UI
+  }
+
+  onPaymentFailed(response: LokotroPaymentStatusResponse) {
+    console.error('Payment failed:', response.message);
+    // Show error message or retry option
+  }
+
+  onClose() {
+    // Navigate away or close modal
+  }
+}
+```
+
+### LokotroPaymentStatusConfig
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `paymentId` | `string` | Yes | - | The payment/transaction ID to track |
+| `config` | `LokotroPayConfig` | Yes | - | API configuration with token |
+| `pollingInterval` | `number` | No | `5000` | Polling interval in milliseconds |
+| `maxPollingAttempts` | `number` | No | `60` | Max attempts before timeout |
+| `language` | `LokotroPayLanguage` | No | `English` | UI language |
+| `autoStart` | `boolean` | No | `true` | Auto-start polling on init |
+
+### Component Inputs/Outputs
+
+#### Inputs
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `statusConfig` | `LokotroPaymentStatusConfig` | Configuration object |
+| `showHeader` | `boolean` | Show/hide header (default: true) |
+| `showCloseButton` | `boolean` | Show/hide close button (default: true) |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `statusChange` | `LokotroPaymentStatusResponse` | Emitted on every status check |
+| `paymentComplete` | `LokotroPaymentStatusResponse` | Emitted when payment succeeds |
+| `paymentFailed` | `LokotroPaymentStatusResponse` | Emitted when payment fails |
+| `onClose` | `void` | Emitted when close/done is clicked |
+| `onDoneEvent` | `LokotroPaymentStatusResponse` | Emitted with details when done |
+
+### Payment Status States
+
+The component handles these payment states:
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Payment awaiting confirmation |
+| `processing` | Payment being processed |
+| `approved` | Payment completed successfully |
+| `declined` | Payment was declined |
+| `failed` | Payment failed |
+| `cancelled` | Payment was cancelled |
+| `expired` | Payment session expired |
+
+## 🔧 Environment Setup
+
+### Development
+
+```typescript
+const devConfig: LokotroPayConfig = {
+  token: 'your_dev_token',
+  isProduction: false  // Uses dev.apps.api.bloonio.com
+};
+```
+
+### Production
+
+```typescript
+const prodConfig: LokotroPayConfig = {
+  token: 'your_prod_token',
+  isProduction: true  // Uses apps.api.bloonio.com
+};
+```
+
+## 📋 Requirements
+
+- Angular 17+
+- TypeScript 5.0+
+- RxJS 7.8+
+
+## 🌐 Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## 📄 License
+
+MIT © Bloonio
+
+## 🆘 Support
+
+- 📧 Email: support@lokotroo.com
+- 🐛 Issues: [GitHub Issues](https://github.com/bloonio/lokotro-pay-angular/issues)
+- 📖 Documentation: [Full Documentation](https://docs.bloonio.com/pay)
+
+---
+
+**Made with ❤️ for the Angular community**