Quick Start

Get your ledger service up and running in under 10 minutes. This guide walks you through everything from account creation to processing your first transaction with our complete double-entry accounting system.

Start Processing TransactionsLearn Architecture

Before You Begin

Make sure you have everything ready for a smooth setup process.

Chart of accounts guide

What You'll Need

  • Valid email address for account registration
  • HTTP client like curl, Postman, or your favorite programming language
  • Business information for your organization setup
  • 10 minutes to complete the entire process

What You'll Build

By the end of this guide, you'll have:

  • A registered user account with JWT authentication
  • A tenant organization with complete data isolation
  • Scoped API keys for secure service-to-service calls
  • A complete chart of accounts ready for transactions
  • Your first posted transaction with real-time balance updates
  • Webhook notifications for real-time event streaming

Step 1: Create Your Account

Start by registering your user account. This gives you access to create and manage organizations.

curl -X POST https://api.sandbox.whocomply.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourfintech.com",
    "password": "YourSecurePassword123!",
    "first_name": "Admin",
    "last_name": "User"
  }'

curl -X POST https://api.sandbox.whocomply.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourfintech.com",
    "password": "YourSecurePassword123!"
  }'

Step 2: Create Your Organization

Create a tenant organization with complete database isolation. Each tenant gets their own schema for maximum security and compliance.

curl -X POST https://api.sandbox.whocomply.com/v1/tenants \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Fintech Limited",
    "slug": "acme-fintech",
    "business_type": "wallet",
    "description": "Digital wallet and payment services"
  }'

Complete Isolation: Your tenant gets its own database schema (tenant_acme_fintech) ensuring complete separation from other customers for regulatory compliance.

Step 3: Generate API Keys

API keys provide secure, scoped access for your applications. Much better than passing JWT tokens around in production.

# Use your tenant ID from Step 2
curl -X POST https://api.sandbox.whocomply.com/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": [
      "accounts:write",
      "accounts:read",
      "balances:read",
      "transactions:write",
      "transactions:read",
      "webhooks:manage"
    ],
    "description": "Full access for production backend service"
  }'

Available Permission Scopes

  • accounts:read - View accounts and chart structure
  • accounts:write - Create and modify accounts
  • balances:read - Query account balances and history
  • transactions:read - View transaction history ✅ Available Now
  • transactions:write - Create and process transactions ✅ Available Now
  • webhooks:manage - Configure real-time notifications ✅ Available Now
  • reports:read - Generate basic reports (Coming Soon)

Security Warning: The API key is only shown once! Save it immediately - we only store the hash on our servers for security.

Step 4: Setup Chart of Accounts

Use business templates to instantly create a complete, compliant chart of accounts structure.

# Create 25+ accounts instantly with our wallet template
curl -X POST https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/setup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_type": "wallet"
  }'

What this creates:

  • Settlement accounts (GTBank NGN, USD accounts)
  • Customer wallet pools (NGN and USD segregation)
  • Fee collection accounts (transaction fees, FX fees)
  • Regulatory reserves (CBN compliance accounts)
  • Operational accounts (expenses, equity, revenue)
curl -X GET https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/hierarchy \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 5: Process Your First Transaction

Now the exciting part - let's process a real transaction with automatic double-entry accounting and balance updates.

# Post a customer wallet funding transaction
curl -X POST https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "first_transaction_001",
    "description": "Customer wallet funding from GTBank",
    "reference": "BANK_TXN_ABC123",
    "account_code": "2001",
    "amount": "50000.00",
    "side": "credit",
    "currency": "NGN",
    "metadata": {
      "customer_id": "cust_123",
      "bank_name": "GTBank",
      "channel": "mobile_app"
    }
  }'

# Create a proper double-entry transaction with balanced debits and credits
curl -X POST https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/transactions/double-entry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "double_entry_001",
    "description": "Customer funding with bank settlement",
    "reference": "BANK_TXN_DEF456",
    "entries": [
      {
        "account_code": "1101",
        "amount": "75000.00",
        "side": "debit",
        "currency": "NGN"
      },
      {
        "account_code": "2001",
        "amount": "75000.00",
        "side": "credit",
        "currency": "NGN"
      }
    ],
    "metadata": {
      "customer_id": "cust_456",
      "settlement_batch": "batch_morning_001"
    }
  }'

Check Updated Balances

# Check the updated balance after your transactions
curl -X GET https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/accounts/code/2001/balance?currency=NGN \
  -H "Authorization: Bearer YOUR_API_KEY"

🎉 Congratulations! You've just processed ₦125,000 in transactions with automatic double-entry accounting and real-time balance updates!

Step 6: Setup Real-Time Webhooks (Optional)

Get instant notifications when transactions are posted or balances change.

curl -X POST https://api.sandbox.whocomply.com/v1/tenants/acme-fintech/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-api.com/webhooks/ledger",
    "events": ["transaction.posted", "balance.updated"],
    "enabled": true
  }'

Your webhook will receive real-time notifications like:

{
  "id": "evt_01JB2M3N4P5Q6R7S8T9U10",
  "type": "transaction.posted",
  "created": 1727348700,
  "data": {
    "transaction_id": "txn_01JB2M3N4P5Q6R7S8T9U0X",
    "amount": "75000.00",
    "currency": "NGN",
    "description": "Customer funding with bank settlement"
  },
  "tenant_id": "tenant_01JB2M3N4P5Q6R7S8T9U0V",
  "livemode": true
}

Next Steps

You now have a complete, production-ready financial infrastructure! Here's what you can do next:

Start Building Your Applications

Wallet Operations - Customer onboarding with account setup - Wallet funding and withdrawal flows - P2P transfers with fee collection - Real-time balance notifications

Payment Processing - Merchant payment acceptance - Settlement and reconciliation - Fee management and collection - Multi-currency support

Available Now - Production Ready

✅ Complete Transaction Processing - Simple and double-entry with validation
✅ Real-Time Balance Updates - Instant balance calculations with optimistic locking
✅ Webhook Notifications - Real-time event streaming with reliable delivery
✅ Multi-Currency Support - NGN, USD, EUR, GBP with proper separation
✅ Audit Trails - Complete event sourcing for compliance and debugging
✅ Nigerian Compliance - CBN-ready account structures and reporting

Integration Examples

import { LedgerClient } from '@ledger/api-client'

const client = new LedgerClient({
  apiKey: 'lsk_live_your_api_key',
  tenantSlug: 'acme-fintech',
})

// Process customer deposit
const transaction = await client.transactions.create({
  idempotency_key: `deposit_${customerId}_${Date.now()}`,
  description: `Wallet funding for ${customerName}`,
  account_code: '2001', // Customer Deposits
  amount: depositAmount,
  side: 'credit',
  currency: 'NGN',
  metadata: { customer_id: customerId, source: 'bank_transfer' },
})

// Check updated balance
const balance = await client.accounts.getBalance('2001', { currency: 'NGN' })
console.log(`New customer deposits balance: ₦${balance.balance}`)

Advanced Features Coming Soon

  • Advanced Reporting Suite - Trial balance, P&L, balance sheet generation
  • Bulk Operations - Process thousands of transactions efficiently
  • Reconciliation Tools - Automated bank statement reconciliation
  • Analytics Dashboard - Business intelligence and insights

Resources & Support

Transactions API ReferenceWebhooks API Reference

Get Help & Stay Connected

🚀 You're Ready to Build the Future of Nigerian Fintech! You now have enterprise-grade financial infrastructure that processes real transactions with proper double-entry accounting, real-time notifications, and complete compliance. Start building your next-generation financial application today!

Was this page helpful?