HoneyCoin Provider API Reference

HoneyCoin is a multi-country mobile money provider supporting Uganda (MTN, Airtel), Kenya (M-Pesa, Airtel), and Tanzania (M-Pesa, Tigo, Airtel). This page documents HoneyCoin-specific configurations, methods, and response formats.

Provider Configuration

Basic Configuration

import { HoneyCoin } from '@fundkit/honeycoin';

const honeycoin = new HoneyCoin({
  apiKey: process.env.HONEYCOIN_API_KEY!,
  publicKey: process.env.HONEYCOIN_PUBLIC_KEY!,
  environment: 'sandbox', // or 'production'
});

Advanced Configuration

const honeycoin = new HoneyCoin({
  apiKey: process.env.HONEYCOIN_API_KEY!,
  publicKey: process.env.HONEYCOIN_PUBLIC_KEY!,
  environment: 'production',
  timeout: 30000, // 30 second timeout
  retries: 3, // Retry attempts
});

Configuration Options

HoneyCoinConfig Interface

interface HoneyCoinConfig {
  apiKey: string; // Required: Your HoneyCoin API key
  publicKey: string; // Required: Your HoneyCoin public key
  environment?: 'sandbox' | 'production'; // Default: 'sandbox'
  timeout?: number; // Request timeout in milliseconds
  retries?: number; // Number of retry attempts
}

Supported Features

Multi-Country Support

CountryCurrencyNetworksMin AmountMax Amount
UgandaUGXMTN, Airtel1,000 (10 UGX)10,000,000 (100,000 UGX)
KenyaKESM-Pesa, Airtel100 (1 KES)1,000,000 (10,000 KES)
TanzaniaTZSM-Pesa, Tigo, Airtel1,000 (10 TZS)5,000,000 (50,000 TZS)

Phone Number Formats

// Uganda numbers
const ugandaNumbers = [
  '+256701234567', // MTN
  '+256751234567', // MTN
  '+256782234567', // Airtel
  '+256702234567', // Airtel
];

// Kenya numbers
const kenyaNumbers = [
  '+254712345678', // Safaricom (M-Pesa)
  '+254722345678', // Safaricom (M-Pesa)
  '+254733345678', // Airtel
  '+254750345678', // Airtel
];

// Tanzania numbers
const tanzaniaNumbers = [
  '+255712345678', // Vodacom (M-Pesa)
  '+255622345678', // Airtel
  '+255652345678', // Tigo
];

HoneyCoin-Specific Methods

Direct Provider Access

import { HoneyCoin } from '@fundkit/honeycoin';

const honeycoin = new HoneyCoin({
  apiKey: process.env.HONEYCOIN_API_KEY!,
  publicKey: process.env.HONEYCOIN_PUBLIC_KEY!,
  environment: 'sandbox',
});

// Direct collection
const result = await honeycoin.collection({
  amount: 10000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: '256701234567',
  externalId: 'order_12345',
  reason: 'Payment for order #12345',
});

Network Detection

// HoneyCoin automatically detects the mobile network
const networkInfo = await honeycoin.detectNetwork('+256701234567');
console.log(networkInfo);
// {
//   country: 'UG',
//   network: 'MTN',
//   currency: 'UGX',
//   supported: true
// }

Balance Inquiry

// Check account balance (if supported by network)
const balance = await honeycoin.checkBalance('+256701234567');
console.log(balance);
// {
//   available: 150000,  // 1,500 UGX
//   currency: 'UGX',
//   lastUpdated: '2024-01-15T10:30:00Z'
// }

Response Formats

HoneyCoin Collection Response

interface HoneyCoinCollectionResponse extends CollectionResponse {
  // Standard fields
  transactionId: string;
  status: TransactionStatus;
  amount: number;
  currency: string;
  phoneNumber: string;
  reason: string;

  // HoneyCoin-specific fields
  providerData: {
    honeycoinTransactionId: string; // HoneyCoin's internal ID
    networkOperator: string; // 'MTN', 'Airtel', 'M-Pesa', etc.
    networkReference?: string; // Network confirmation code
    customerName?: string; // Customer name from network
    accountBalance?: number; // Customer's account balance
    networkFee: number; // Network transaction fee
    processingStage: string; // Current processing stage
    estimatedCompletion?: string; // Estimated completion time
  };
}

Status-Specific Data

// Pending status
{
  status: 'pending',
  providerData: {
    processingStage: 'awaiting_customer_approval',
    estimatedCompletion: '2024-01-15T10:05:00Z'
  }
}

// Processing status
{
  status: 'processing',
  providerData: {
    processingStage: 'network_confirmation',
    networkReference: 'MTN123456789'
  }
}

// Completed status
{
  status: 'completed',
  providerData: {
    processingStage: 'completed',
    networkReference: 'MTN123456789',
    customerName: 'John Doe',
    accountBalance: 145000,
    networkFee: 500
  }
}

// Failed status
{
  status: 'failed',
  providerData: {
    processingStage: 'failed',
    failureCode: 'INSUFFICIENT_FUNDS',
    failureMessage: 'Customer has insufficient balance'
  }
}

Error Codes

HoneyCoin-Specific Errors

// Network not supported
{
  name: 'ProviderError',
  code: 'NETWORK_NOT_SUPPORTED',
  message: 'Phone number network not supported in this country',
  provider: 'honeycoin',
  details: {
    phoneNumber: '+256123456789',
    detectedNetwork: 'unknown',
    supportedNetworks: ['MTN', 'Airtel']
  }
}

// Country restrictions
{
  name: 'ProviderError',
  code: 'COUNTRY_RESTRICTED',
  message: 'Transactions not available in this country',
  provider: 'honeycoin',
  details: {
    detectedCountry: 'RW',
    supportedCountries: ['UG', 'KE', 'TZ']
  }
}

// Network maintenance
{
  name: 'ProviderError',
  code: 'NETWORK_MAINTENANCE',
  message: 'Mobile network is under maintenance',
  provider: 'honeycoin',
  details: {
    network: 'MTN',
    country: 'UG',
    estimatedRestoration: '2024-01-15T12:00:00Z'
  }
}

// Daily limit exceeded
{
  name: 'ProviderError',
  code: 'DAILY_LIMIT_EXCEEDED',
  message: 'Customer has exceeded daily transaction limit',
  provider: 'honeycoin',
  details: {
    dailyLimit: 1000000,
    currentTotal: 950000,
    requestedAmount: 100000
  }
}

Webhooks

Webhooks are configured at the PaymentClient level, not at the provider level. This provides a unified webhook endpoint for all providers.

Webhook Configuration

import { PaymentClient } from '@fundkit/core';
import { HoneyCoin } from '@fundkit/honeycoin';

const honeycoin = new HoneyCoin({
  apiKey: process.env.HONEYCOIN_API_KEY!,
  publicKey: process.env.HONEYCOIN_PUBLIC_KEY!,
});

const client = new PaymentClient({
  apiKey: process.env.FUNDKIT_API_KEY!,
  providers: [honeycoin],
  webhook: {
    url: 'https://api.myapp.com/webhooks/fundkit',
    secret: process.env.WEBHOOK_SECRET!,
  },
});

Unified Webhook Event Structure

All webhook events follow this unified structure:
interface WebhookEvent {
  event: 'transaction_completed' | 'transaction_failed' | 'transaction_pending';
  data: {
    transactionId: string;
    transactionType: 'COLLECTION' | 'PAYOUT';
    amount: string;
    currency: string;
    operator: string;
    accountNumber: string;
    externalId: string;
    environment: 'sandbox' | 'production';
  };
}
For detailed webhook implementation, see the Webhooks Guide.

Advanced Features

Bulk Transactions

// Process multiple transactions
const bulkResults = await honeycoin.bulkCollect([
  {
    amount: 10000,
    currency: 'UGX',
    phoneNumber: '+256701234567',
    reason: 'Payment 1',
  },
  {
    amount: 20000,
    currency: 'KES',
    phoneNumber: '+254712345678',
    reason: 'Payment 2',
  },
]);

console.log('Bulk processing results:', bulkResults);

Scheduled Payments

// Schedule a future payment
const scheduledPayment = await honeycoin.schedulePayment({
  amount: 50000,
  currency: 'UGX',
  phoneNumber: '+256701234567',
  reason: 'Monthly subscription',
  scheduledFor: '2024-02-01T09:00:00Z',
  recurrence: 'monthly',
});

Transaction Analytics

// Get transaction analytics
const analytics = await honeycoin.getAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  country: 'UG',
  network: 'MTN',
});

console.log(analytics);
// {
//   totalTransactions: 1250,
//   totalAmount: 125000000,
//   successRate: 0.945,
//   averageAmount: 100000,
//   networkBreakdown: {
//     MTN: 800,
//     Airtel: 450
//   },
//   peakHours: ['14:00', '15:00', '20:00']
// }

Testing with HoneyCoin

Sandbox Environment

// Sandbox configuration
const honeycoin = new HoneyCoin({
  apiKey: process.env.HONEYCOIN_API_KEY!,
  publicKey: process.env.HONEYCOIN_PUBLIC_KEY!,
  environment: 'sandbox',
});

Test Phone Numbers

// HoneyCoin sandbox test numbers
const testNumbers = {
  // Uganda - Always successful
  successUG: '+256700000001',
  // Uganda - Always fails
  failureUG: '+256700000002',
  // Uganda - Times out
  timeoutUG: '+256700000003',

  // Kenya - Always successful
  successKE: '+254700000001',
  // Kenya - Insufficient funds
  insufficientKE: '+254700000002',

  // Tanzania - Always successful
  successTZ: '+255700000001',
  // Tanzania - Network error
  networkErrorTZ: '+255700000002',
};

Testing Scenarios

import { PaymentClient } from '@fundkit/core';

const client = new PaymentClient({
  apiKey: process.env.FUNDKIT_API_KEY!,
  providers: [honeycoin],
  environment: 'sandbox',
});

// Test successful payment
const successTest = await client.collection({
  amount: 10000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: testNumbers.successUG.replace('+', ''),
  externalId: 'test_success_001',
  reason: 'Test successful payment',
});

// Test failure scenarios
const failureTest = await client.collection({
  amount: 50000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: testNumbers.failureUG.replace('+', ''),
  externalId: 'test_failure_001',
  reason: 'Test payment failure',
});

// Test timeout scenarios
const timeoutTest = await client.collection({
  amount: 25000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: testNumbers.timeoutUG.replace('+', ''),
  externalId: 'test_timeout_001',
  reason: 'Test payment timeout',
});

Rate Limits

API Rate Limits

EnvironmentRequests per minuteConcurrent requests
Sandbox10010
Production100050

Handling Rate Limits

import { retry } from '@fundkit/core/utils';

const collectWithRetry = retry(
  async () => {
    return await honeycoin.collect(request);
  },
  {
    retries: 3,
    delay: 1000,
    backoff: 'exponential',
  }
);