@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

npm install @bloonio/lokotro-pay
# or
yarn add @bloonio/lokotro-pay

🚀 Quick Start

Basic Usage (Standalone Components - Recommended)

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: '[email protected]',
    // 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

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:

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:

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: '[email protected]',

  // 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

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: '[email protected]',
  walletNumber: '3005710720108954',
  walletPin: '048698'
};

Mobile Money Payment

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: '[email protected]',
  mobileMoneyPhoneNumber: '2439978540000'
};

Card Payment (Hosted Session - Recommended)

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: '[email protected]',
  successRedirectUrl: 'https://yourserver.com/success',
  failRedirectUrl: 'https://yourserver.com/failed',
  notifyUrl: 'https://yourserver.com/notify'
};

Flash Payment

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: '[email protected]',
  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 |

// 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:

@import '@bloonio/lokotro-pay/styles/lokotro-pay.scss';

CSS Variables

Override theme variables in your styles:

:root {
  --lokotro-primary: #5A5E39;
  --lokotro-accent: #3BFBDA;
  --lokotro-background: #1C2621;
  --lokotro-text-primary: #F2F0D5;
}

🌐 Multi-Language Support

Setting Language

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

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

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

const devConfig: LokotroPayConfig = {
  token: 'your_dev_token',
  isProduction: false  // Uses dev.apps.api.bloonio.com
};

Production

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: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

Made with ❤️ for the Angular community