​
Build your first payment integration

This quickstart guide will walk you through setting up FundKit and processing your first payment in just a few minutes.
  • JavaScript/TypeScript
  • Python
Prerequisites: Node.js 16+ and npm/yarn/pnpm/bun installed on your machine.

​
Step 1: Install FundKit

Install the core package and your chosen providers:
npm install @fundkit/core @fundkit/honeycoin @fundkit/easypay

​
Step 2: Get API Keys

Get API keys from your chosen providers: HoneyCoin: - Sign up at honeycoin.io - Get your API key and public key from the dashboard EasyPay: - Register at easypay.ug - Obtain your client ID and API secret

​
Step 3: Initialize the Payment Client

  • JavaScript/TypeScript
  • Python
Create a new file payment.js (or payment.ts for TypeScript):
import { PaymentClient } from '@fundkit/core';
import { HoneyCoin } from '@fundkit/honeycoin';
import { EasyPay } from '@fundkit/easypay';

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

const easypay = new EasyPay({
  apiKey: process.env.EASYPAY_SECRET!,
  clientId: process.env.EASYPAY_CLIENT_ID!,
});

// Create payment client
const client = new PaymentClient({
  apiKey: process.env.FUNDKIT_API_KEY!,
  providers: [honeycoin, easypay],
  environment: 'sandbox',
  // Webhook is optional - see webhooks guide for production setup
  webhook: {
    url: process.env.WEBHOOK_URL!,
    secret: process.env.WEBHOOK_SECRET!,
  },
});

export default client;

​
Step 4: Process Your First Payment

  • JavaScript/TypeScript
  • Python
import client from './payment';

async function processPayment() {
  try {
    // Create a payment collection
    const result = await client.collection({
      amount: 10000, // Amount in smallest currency unit (10,000 = 100.00 UGX)
      currency: 'UGX',
      operator: 'mtn',
      accountNumber: '+256701234567',
      externalId: 'tx_' + Date.now(),
      reason: 'Test payment from FundKit'
    });

    console.log('Payment initiated:', {
      provider: result.provider,
      transactionId: result.data.transactionId,
      status: result.data.status
    });

    // Check payment status (you can also use webhooks for real-time updates)
    const status = await client.getTransaction({
      provider: result.provider,
      txId: result.data.transactionId,
    });

    console.log('Payment status:', status?.data.status);

  } catch (error) {
    console.error('Payment failed:', error.message);
  }
}

processPayment();

​
Step 5: Run Your Integration

  • JavaScript/TypeScript
  • Python
Set up your environment variables in a .env file:
.env
FUNDKIT_API_KEY=fk_test_your_sandbox_key_here
HONEYCOIN_API_KEY=your_honeycoin_api_key
HONEYCOIN_PUBLIC_KEY=your_honeycoin_public_key
EASYPAY_SECRET=your_easypay_secret
EASYPAY_CLIENT_ID=your_easypay_client_id
# Webhook configuration is optional - see webhooks guide for production setup
WEBHOOK_URL=https://api.myapp.com/webhooks/fundkit
WEBHOOK_SECRET=your_webhook_secret
Then run your code:
node payment.js
# or for TypeScript:
npx tsx payment.ts

​
Testing Without the Emulator

Auto-confirm testing: In sandbox mode, you can test successful and failed transactions without opening the emulator by using special test phone numbers:

​
Auto-Success Transactions

Use a phone number ending in 11111111 to automatically simulate a successful transaction: 
// Automatically succeeds without emulator interaction
const result = await client.collection({
  amount: 10000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: '25611111111', // Country code + 11111111
  externalId: 'test_success_' + Date.now(),
  reason: 'Auto-success test',
});

​
Auto-Failed Transactions

Use a phone number ending in 00000000 to automatically simulate a failed transaction: 
// Automatically fails without emulator interaction
const result = await client.collection({
  amount: 10000,
  currency: 'UGX',
  operator: 'mtn',
  accountNumber: '25600000000', // Country code + 00000000
  externalId: 'test_failed_' + Date.now(),
  reason: 'Auto-fail test',
});
Supported formats:
  • 25611111111 (Uganda - auto-success)
  • 25600000000 (Uganda - auto-fail)
  • 25411111111 (Kenya - auto-success)
  • 25400000000 (Kenya - auto-fail)
  • Works with any country code + 11111111 or 00000000
This feature is only available in sandbox mode. Use these test numbers to quickly test your integration without manual emulator interaction.

​
Success!

You should see output similar to:
  • JavaScript/TypeScript
  • Python
Payment initiated: {
  provider: 'honeycoin',
  transactionId: 'txn_abc123xyz',
  status: 'pending'
}
Payment status: completed

​
Next Steps

Core Concepts

Learn about providers, transactions, and error handling

Provider Setup

Configure specific payment providers

Error Handling

Handle errors gracefully in production

API Reference

Explore the complete FundKit API

​
Need Help?

Join our Discord Community

Get help from other developers and the FundKit team