TwitterProduct HuntLinkedInGitHubJumboGet Started
API ReferenceCorePayment Providers

Payment Providers

This guide details the payment providers available through lomi.’s API and their specific requirements.

Overview

lomi. supports multiple payment providers across Africa, each with its own features and requirements:

ProviderCountriesMethodsCurrencies
Orange MoneySN, ML, BFMobile MoneyXOF
WaveSN, CIMobile Money, QRXOF
MTNCI, BFMobile MoneyXOF
MoovSN, CIMobile MoneyXOF
EcobankGlobalCardsXOF, USD, EUR
M-PesaKEMobile MoneyUSD

Provider Setup

Orange Money

// Connect Orange Money account
const provider = await lomi.providers.connect({
  provider_code: 'ORANGE',
  phone_number: '+221777777777',
  merchant_code: 'OM123456'
});
 
// Create transaction
const transaction = await lomi.transactions.create({
  provider_code: 'ORANGE',
  payment_method_code: 'MOBILE_MONEY',
  amount: 1000,
  currency_code: 'XOF',
  customer_phone: '+221777777777'
});

Requirements

  • Merchant account with Orange Money
  • Business KYC verification
  • Valid merchant code
  • API credentials

Wave

// Connect Wave account
const provider = await lomi.providers.connect({
  provider_code: 'WAVE',
  business_id: 'WAVE123456',
  api_key: 'wave_api_key'
});
 
// Create QR code payment
const qr = await lomi.qrCodes.create({
  provider_code: 'WAVE',
  amount: 1000,
  currency_code: 'XOF'
});

Requirements

  • Wave Business account
  • Business verification
  • API credentials
  • Callback URL configuration

Provider Features

Orange Money

  • Payment Methods
    • USSD push payments
    • QR code payments
    • Direct debit
  • Limits
    • Min: 100 XOF
    • Max: 1,000,000 XOF per transaction
    • Daily: 2,000,000 XOF
  • Features
    • Instant notifications
    • Refund support
    • Recurring payments
    • Split payments

Wave

  • Payment Methods
    • QR code payments
    • Direct payments
    • Payment links
  • Limits
    • Min: 100 XOF
    • Max: 2,000,000 XOF per transaction
    • Daily: 5,000,000 XOF
  • Features
    • Real-time notifications
    • Instant refunds
    • Business profiles
    • Analytics dashboard

Testing

Test Credentials

Each provider has specific test credentials:

// Orange Money test account
const lomi = new LomiClient({
  apiKey: 'test_key',
  provider_credentials: {
    ORANGE: {
      test_numbers: ['+221770000000', '+221770000001'],
      merchant_code: 'TEST123'
    }
  }
});

Test Scenarios

Successful Payment

const transaction = await lomi.transactions.create({
  provider_code: 'ORANGE',
  amount: 1000,
  customer_phone: '+221770000000' // Test success number
});

Failed Payment

const transaction = await lomi.transactions.create({
  provider_code: 'ORANGE',
  amount: 1000,
  customer_phone: '+221770000001' // Test failure number
});

Provider-Specific Errors

Orange Money Errors

CodeDescriptionResolution
INSUFFICIENT_BALANCECustomer lacks fundsAsk customer to top up
INVALID_PINWrong PIN enteredAsk customer to retry
DAILY_LIMITDaily limit exceededTry different provider

Wave Errors

CodeDescriptionResolution
USER_CANCELLEDUser cancelled paymentPrompt to retry
ACCOUNT_LOCKEDAccount security lockContact Wave support
INVALID_BUSINESSInvalid business accountVerify credentials

Best Practices

1. Provider Selection

// Check provider availability
const providers = await lomi.providers.list({
  country: 'SN',
  currency: 'XOF'
});
 
// Sort by priority
const preferredProvider = providers.sort((a, b) => 
  b.success_rate - a.success_rate
)[0];

2. Fallback Strategy

async function processPayment(data) {
  const providers = ['ORANGE', 'WAVE', 'MTN'];
  
  for (const provider of providers) {
    try {
      return await lomi.transactions.create({
        ...data,
        provider_code: provider
      });
    } catch (error) {
      if (error.code === 'provider_unavailable') {
        continue; // Try next provider
      }
      throw error;
    }
  }
}

3. Provider Health Monitoring

// Monitor provider status
const status = await lomi.providers.getStatus('ORANGE');
if (status.health !== 'healthy') {
  // Use fallback provider
}

Integration Checklist

  • Provider account setup
  • API credentials configuration
  • Webhook endpoint setup
  • Test transactions verification
  • Error handling implementation
  • Monitoring setup
  • Production verification

Support

Each provider has dedicated support channels:

For general integration support:

WebhooksChangelog