Package Exports
- settlesettle
Readme
SettleSettle SDK
The official, zero-dependency TypeScript SDK for SettleSettle — the Revenue Operating System for African developers.
SettleSettle equips software businesses with the tools needed to monetize applications across Africa using dynamic billing rails. Securely integrate virtual credit wallets, recurring subscriptions, rewarded ad monetization, and payment ledger auditing in just a few lines of code.
Table of Contents
- Installation
- Quick Start
- Core Concepts & Billing Modes
- SDK Modules Reference
- Error Handling
- Graceful Shutdown
- TypeScript Support
Installation
Install the package via your preferred package manager. SettleSettle is zero-dependency, maintaining a ultra-light footprint in both serverless and long-running backend environments.
# Using npm
npm install settlesettle
# Using pnpm
pnpm add settlesettle
# Using yarn
yarn add settlesettleQuick Start
Initialize the client with your secret API key. The SDK automatically falls back to the SETTLESETTLE_API_KEY environment variable if no options are passed explicitly.
import { SettleSettle } from 'settlesettle'
// Configured via argument or SETTLESETTLE_API_KEY environment variable
const settle = new SettleSettle({
apiKey: 'ss_live_your_secret_key'
})
// Query user credits wallet balance
const { balance } = await settle.wallet.getBalance('user_123')
console.log(`User has ${balance} credits remaining.`)Core Concepts & Billing Modes
SettleSettle supports three major billing configurations, which can be toggled and combined within your developer dashboard configuration:
1. Credits Billing
An atomic, high-velocity virtual wallet system. Perfect for usage-based apps (e.g., deducting 5 credits per AI prompt or 15 credits per image rendering).
- Benefit: End-users top up credit packages in local currencies, and developers charge programmatically for granular usage.
- Fallbacks: When credits hit zero, seamlessly offer rewarded ad videos as an instant credit replenishment fallback.
2. Subscriptions Billing
Enforce recurring time-bound payments (Monthly, Annual, etc.) with automatic background renewals, grace periods, and trial days.
- Supported Rails: Wallet-based debit cycles (virtual balances charged automatically on interval) or Paystack-backed recurrent card billing.
- Checks: Block premium features with a simple access gate in your code.
3. One-Time Payments
Traditional digital checkout for specific items, physical goods, lifetime access passes, or one-off credit bundle packages.
- Supported Rails: Paystack (Card, Bank Transfer, USSD, NQR) and Solana Devnet (manual USDC operations).
SDK Modules Reference
The SettleSettle client coordinates distinct submodules to handle specific monetization features:
Payments
Easily initialize visual checkout interfaces and verify Paystack or Solana transactions.
// 1. Initialize a checkout session
const { checkoutUrl, reference } = await settle.payments.initialize({
endUserId: 'user_123',
amountKobo: 500000, // ₦5,000 in kobo (always in smallest currency unit)
email: 'user@example.com',
callbackUrl: 'https://myapp.com/checkout/callback' // Optional success return URL
})
// Redirect your user to checkoutUrl to complete the payment
console.log(`Checkout URL: ${checkoutUrl}`)
// 2. Verify payment status later (e.g., inside callback page or cron checks)
const result = await settle.payments.verify(reference)
if (result.status === 'success') {
console.log('Payment successfully processed!')
}
// 3. Support for Web3 Solana USDC audit tracking (Devnet)
const solanaResult = await settle.payments.verifySolana(
'sol_ref_9901',
'4t6fHnQ9...' // On-chain transaction signature
)Wallet
Manage user virtual credit balances directly from the SDK with atomic transaction logs.
// Credit a user's wallet (e.g., promotional sign-up bonus)
await settle.wallet.credit('user_123', {
amount: 100,
description: 'Welcome bonus',
})
// Deduct credits for usage
import { InsufficientCreditsError } from 'settlesettle'
try {
await settle.wallet.debit('user_123', {
amount: 10,
description: 'AI Query execution',
})
} catch (err) {
if (err instanceof InsufficientCreditsError) {
// Gracefully handle balance exhaustion
console.log(`Insufficient credits. Current balance: ${err.currentBalance}`)
}
}
// View paginated transaction history
const history = await settle.wallet.getHistory('user_123', { page: 1, limit: 10 })
console.log(history.transactions) // List of past credits/debitsSubscriptions
Check user recurring subscription plans, verify access states, activate webhooks, or schedule cancellations.
// 1. Check if user has active subscription access to your premium tier
const { hasAccess, reason, subscription } = await settle.subscriptions.checkAccess('user_123')
if (!hasAccess) {
console.log(`Access Denied: ${reason}`)
// Trigger pricing paywall modal
} else {
console.log(`Access Granted! Active Plan: ${subscription?.planId}`)
}
// 2. Get full user subscription details
const subDetails = await settle.subscriptions.getSubscription('user_123')
if (subDetails) {
console.log(`Subscription status: ${subDetails.status}`)
}
// 3. Activate a subscription manually (e.g., upon successful checkout webhook confirmation)
const newSub = await settle.subscriptions.activate('user_123', 'plan_pro_monthly', {
userEmail: 'user@example.com',
billingMode: 'wallet_balance' // Supports 'wallet_balance' or 'paystack_recurrent'
})
// 4. Cancel subscription (defaults to cancel-at-period-end so user retains access until period expires)
const cancelled = await settle.subscriptions.cancel('user_123', 'plan_pro_monthly')
console.log(`Subscription will officially expire on: ${cancelled.currentPeriodEnd}`)Events (Usage Metering)
Track user usage activities with a high-performance background buffering queue. Event reporting is non-blocking and synchronous in your hot code path.
// Non-blocking and synchronous — events are batched and flushed in background thread
settle.events.track({
userId: 'user_123',
eventType: 'AI_QUERY',
metadata: { model: 'gpt-4', tokens: 1500 }
})
// Query usage summary metrics for a user
const summary = await settle.events.getSummary('user_123')
console.log(`Total events tracked today: ${summary.totalCount}`)Authentication
Retrieve, rotate, and manage JWT session credentials for programmatically calling administrative developer APIs.
const auth = await settle.auth.login({
email: 'dev@example.com',
password: 'securepassword',
})
// Set the access token to authenticate the SDK for developer configuration routes
settle.setAccessToken(auth.accessToken)Users (Directory Sync)
Keep customer accounts in sync. Idempotently mirror user profiles from your application database into SettleSettle's unified directory.
// Safe to call on every user login or profile update
await settle.users.sync({
externalUserId: 'user_abc123',
email: 'user@example.com',
name: 'Tunde Adeyemi',
})Billing (Widget Support & Ad Rewards)
Bootstrap checkout widgets, load pricing modes, and issue free virtual credits to users for completing ad video views.
// 1. Bootstrap all UI config, plans, wallet balances, and active billing modes in a single call
const config = await settle.billing.bootstrap('user_123')
console.log('Theme Color:', config.uiConfig.themeColor)
console.log('Allowed Modes:', config.allowedBillingModes) // e.g. ['credits', 'subscription']
// 2. Reward ad credits upon completed video stream (calculated server-side)
const result = await settle.billing.rewardAd('user_123')
console.log(`Awarded ${result.creditsAwarded} credits. New balance: ${result.newBalance}`)
// 3. Report custom ad network impressions
await settle.billing.reportAdImpression('imp_abc123', 45) // 45 seconds duration
// 4. Developer Management (Requires JWT Auth)
const packages = await settle.billing.listPackages('app_123')
const newAction = await settle.billing.createAction('app_123', {
eventType: 'PREMIUM_FEATURE',
creditCost: 50
})Ads (Developer Earnings)
Track and withdraw the ad-reward revenue generated by your application's ad completions.
// Fetch ad-rewards earnings summary and ledger balances
const earnings = await settle.ads.getEarningsSummary()
console.log('Available for withdrawal:', earnings.balance.availableKobo)
// Withdraw earnings to your registered developer bank account
await settle.ads.withdrawEarnings(500000) // Withdraw ₦5,000 in koboAdvertiser (Campaign Management)
Configure advertising campaigns, creative media assets, and programmatic budgets.
// Create a new campaign const campaign = await settle.advertiser.createCampaign({ name: 'Summer Promo 2026', budgetKobo: 1000000, // ₦10,000 rewardCredits: 10 })
// Attach creative copywriting and link assets to campaign await settle.advertiser.addCreative(campaign.id, { headline: 'Premium Coding Assistant!', body: 'Work 10x faster with AI.', ctaLabel: 'Try Now', ctaUrl: 'https://brand.com/assistant', brandName: 'BrandX' })
---
## Error Handling
The SettleSettle SDK uses strictly typed, self-documenting error classes. Catching specific exception types is essential for constructing seamless failover systems:
```typescript
import {
SettleSettleError,
InsufficientCreditsError,
AuthenticationError,
} from 'settlesettle'
try {
await settle.wallet.debit('user_123', { amount: 15 })
} catch (err) {
if (err instanceof InsufficientCreditsError) {
console.log(`Balance: ${err.currentBalance}. Requested: ${err.requestedAmount}.`)
// Trigger rewarded ad view fallback or credit top-up paywall
} else if (err instanceof AuthenticationError) {
console.error('Invalid API Key credentials')
} else if (err instanceof SettleSettleError) {
console.error('General SettleSettle Exception:', err.message)
}
}SDK Error Mapping
| Error Class | HTTP Code | Root Cause |
|---|---|---|
AuthenticationError |
401 | Invalid, expired, or deactivated API secret key |
ValidationError |
400 | Malformed request body, missing fields, or invalid formats |
InsufficientCreditsError |
402 | Debit amount exceeds user's current wallet balance |
RateLimitError |
429 | Request volume exceeded limits. SDK automatically backs off and retries |
TimeoutError |
- | Network connection timed out (Default limit: 10000ms) |
ApiError |
500 / Other | General server execution errors or database lock faults |
Graceful Shutdown
The usage metering events module utilizes memory buffering to optimize network overhead. When deploying in server environments, ensure the queue is cleanly flushed during server shutdown or container termination:
// On server shutdown or process exit
await settle.destroy()Documentation
For full documentation and API reference, please visit settlesettle.uno.