SDKs & Libraries

The Carbon Business API SDKs provide a convenient way to integrate with our platform, offering pre-built functions for common operations like account creation, payouts, and transaction management.

Node.js/JavaScript SDK

Our official Node.js SDK simplifies integration with the Carbon Business API, providing TypeScript support and comprehensive error handling.

Installation

Install the SDK via npm:

npm install carbon-baas-sdk

Requires Node.js 14.0 or higher for optimal compatibility.

Configuration

Initialize the SDK with your API key and environment mode.

Always use environment variables to store your API keys securely. Never hardcode them in your source code.

Environment Setup

# .env file
CARBON_API_KEY=your_api_key_here
CARBON_ENV=sandbox  # or 'live' for production

CommonJS Example

const carbon = require('carbon-baas-sdk');

// Initialize the SDK
carbon.initialize(process.env.CARBON_API_KEY, process.env.CARBON_ENV);

ES6/TypeScript Example

import { CarbonSDK } from 'carbon-baas-sdk';

// Initialize the SDK
const carbon = new CarbonSDK({
  apiKey: process.env.CARBON_API_KEY!,
  environment: process.env.CARBON_ENV as 'sandbox' | 'live'
});

Core Operations

Account Management

Create Collection Account

// Create a collection sub-account
const collectionAccount = await carbon.createAccount({
  accountType: 'static',
  thirdParty: false,
  accountName: 'My Collections'
});

console.log('Account Number:', collectionAccount.data.account.account_number);

Create Customer-Linked Account

// First create a customer
const customer = await carbon.createCustomer({
  email: 'customer@example.com',
  phone: '08012345678',
  firstName: 'John',
  lastName: 'Doe',
  bvn: '12345678901'
});

// Then create account linked to customer
const businessAccount = await carbon.createAccount({
  accountType: 'static',
  thirdParty: true,
  customerId: customer.data.id
});

Fetch Account Details

try {
  const account = await carbon.getAccount('1234567890');
  console.log('Account Details:', account.data);
} catch (error) {
  console.error('Account not found:', error.message);
}

Check Account Balance

const balance = await carbon.fetchBalance('1234567890');
console.log('Available Balance:', balance.data.available_balance);

Payouts

Validate Beneficiary Account

const validation = await carbon.resolveAccount({
  accountNumber: '0123456789',
  bankCode: '058'
});

if (validation.status === 'success') {
  console.log('Account Name:', validation.data.account_name);
}

Create Payout

const payout = await carbon.createPayout({
  amount: 50000, // Amount in kobo (₦500)
  source: {
    accountNumber: 'your_account_number'
  },
  beneficiary: {
    bankCode: '058',
    bankName: 'GTBank',
    accountNumber: '0123456789',
    accountName: 'Jane Smith'
  },
  reference: `PAY_${Date.now()}`, // Unique reference
  remark: 'Service payment'
});

console.log('Payout Reference:', payout.data.reference);

Track Payout Status

const status = await carbon.getPayoutStatus('PAY_1737326400123');
console.log('Payout Status:', status.data.status);

Transaction Management

Fetch Transactions

const transactions = await carbon.fetchTransactions({
  accountNumber: '1234567890',
  startDate: '2026-01-01',
  endDate: '2026-01-19',
  limit: 50
});

console.log('Transaction Count:', transactions.data.length);

Verify Transaction

const verification = await carbon.verifyTransaction('TXN_REF_123');

if (verification.data.status === 'successful') {
  console.log('Transaction verified successfully');
}

Error Handling

Implement robust error handling for production applications:

try {
  const result = await carbon.createPayout(payoutData);
  return result;
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    console.error('Insufficient funds for payout');
  } else if (error.code === 'INVALID_ACCOUNT') {
    console.error('Invalid beneficiary account details');
  } else if (error.code === 'DUPLICATE_REFERENCE') {
    console.error('Reference already used, generate new one');
  } else {
    console.error('Unexpected error:', error.message);
  }
  
  throw error; // Re-throw for upstream handling
}

Best Practices

Environment Configuration

Use environment variables for API keys and configuration
Never commit sensitive credentials to version control
Use different API keys for sandbox and live environments

Error Handling

Always implement try-catch blocks for async operations
Log errors appropriately for debugging
Provide meaningful error messages to users

Reference Generation

Use unique, timestamp-based references for payouts
Keep references under 30 characters
Include identifiable prefixes for easier tracking

Rate Limiting

Implement retry logic with exponential backoff
Monitor API usage to stay within limits
Cache frequently accessed data when appropriate

Webhook Integration

Handle webhook events for real-time notifications:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['carbon-signature'];
  const webhookSecret = process.env.CARBON_WEBHOOK_SECRET;
  
  // Verify webhook signature
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('hex');
    
  if (signature === computedSignature) {
    const event = req.body;
    
    switch (event.type) {
      case 'account.incoming-transaction':
        console.log('Payment received:', event.data);
        break;
      case 'payout.successful':
        console.log('Payout completed:', event.data);
        break;
      default:
        console.log('Unknown event type:', event.type);
    }
    
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Troubleshooting

Authentication Issues

Ensure you’re using the correct API key for your environment (sandbox vs live).

Network Errors

Implement retry logic for network failures and timeout errors.

Validation Errors

Check that all required fields are provided and account numbers are valid before making API calls.

Additional Resources

Payment Operations Guide - Complete workflow examples
Webhook Documentation - Real-time event handling
API Reference - Detailed endpoint documentation
Environment Setup - Sandbox vs Live configuration

For other programming languages or framework-specific integrations, please contact our support team at sme@getcarbon.co.

Get Started

Payment Operations

Lending

Webhooks

Plugins & Sdks

Node.js/JavaScript SDK

Installation

Configuration

Environment Setup

CommonJS Example

ES6/TypeScript Example

Core Operations

Account Management

Payouts

Transaction Management

Error Handling

Best Practices

Webhook Integration

Troubleshooting

Additional Resources

​Node.js/JavaScript SDK

​Installation

​Configuration

​Environment Setup

​CommonJS Example

​ES6/TypeScript Example

​Core Operations

​Account Management

​Payouts

​Transaction Management

​Error Handling

​Best Practices

​Webhook Integration

​Troubleshooting

​Additional Resources

Node.js/JavaScript SDK

Installation

Configuration

Environment Setup

CommonJS Example

ES6/TypeScript Example

Core Operations

Account Management

Payouts

Transaction Management

Error Handling

Best Practices

Webhook Integration

Troubleshooting

Additional Resources