Core Banking API

Core Banking APIs

Overview

The Buburuza Core Banking APIs provide comprehensive financial services including account management, transaction processing, and balance operations. Built on our Layer 3 blockchain infrastructure with AI-powered features for enhanced user experiences.

Accounts API

Create Account

Create a new bank account for a customer.

POST /v1/accounts

const account = await buburuza.accounts.create({
  customerId: 'cust_1234567890abcdef',
  type: 'checking', // 'checking', 'savings', 'business'
  currency: 'USD',
  name: 'Primary Checking Account',
  metadata: {
    productType: 'premium',
    openedVia: 'mobile_app'
  }
});

console.log('Account created:', account);

Request Body:

{
  "customerId": "cust_1234567890abcdef",
  "type": "checking",
  "currency": "USD",
  "name": "Primary Checking Account",
  "initialDeposit": 10000,
  "metadata": {
    "productType": "premium",
    "openedVia": "mobile_app"
  }
}

Response:

{
  "id": "acc_1234567890abcdef",
  "customerId": "cust_1234567890abcdef",
  "type": "checking",
  "currency": "USD",
  "name": "Primary Checking Account",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "balance": 10000,
  "availableBalance": 10000,
  "status": "active",
  "createdAt": "2025-11-07T14:30:00Z",
  "updatedAt": "2025-11-07T14:30:00Z"
}

Get Account Details

Retrieve detailed information about a specific account.

GET /v1/accounts/{accountId}

const account = await buburuza.accounts.retrieve('acc_1234567890abcdef');

console.log('Account balance:', account.balance);
console.log('Available balance:', account.availableBalance);

Response:

{
  "id": "acc_1234567890abcdef",
  "customerId": "cust_1234567890abcdef",
  "type": "checking",
  "currency": "USD",
  "name": "Primary Checking Account",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "balance": 15750,
  "availableBalance": 15250,
  "pendingBalance": 500,
  "status": "active",
  "features": {
    "overdraftProtection": true,
    "interestBearing": false,
    "minimumBalance": 100
  },
  "limits": {
    "dailyWithdrawal": 100000,
    "monthlyTransfer": 500000
  },
  "createdAt": "2025-11-07T14:30:00Z",
  "updatedAt": "2025-11-07T15:45:00Z"
}

List Accounts

Get all accounts for a customer.

GET /v1/accounts

const accounts = await buburuza.accounts.list({
  customerId: 'cust_1234567890abcdef',
  status: 'active',
  limit: 10
});

console.log('Customer accounts:', accounts.data);

Query Parameters:

• customerId (string): Filter by customer ID

• type (string): Filter by account type

• status (string): Filter by account status

• currency (string): Filter by currency

• limit (number): Number of results to return (default: 10, max: 100)

• startingAfter (string): Pagination cursor

Response:

{
  "data": [
    {
      "id": "acc_1234567890abcdef",
      "type": "checking",
      "currency": "USD",
      "balance": 15750,
      "status": "active"
    },
    {
      "id": "acc_0987654321fedcba",
      "type": "savings",
      "currency": "USD",
      "balance": 25000,
      "status": "active"
    }
  ],
  "hasMore": false,
  "total": 2
}

Transactions API

Create Transaction

Process a new transaction (transfer, deposit, withdrawal).

POST /v1/transactions

// Transfer between accounts
const transfer = await buburuza.transactions.create({
  type: 'transfer',
  fromAccount: 'acc_1234567890abcdef',
  toAccount: 'acc_0987654321fedcba',
  amount: 5000, // $50.00 in cents
  currency: 'USD',
  description: 'Transfer to savings',
  reference: 'monthly_savings_001',
  metadata: {
    category: 'savings',
    automated: true
  }
});

// External bank transfer
const externalTransfer = await buburuza.transactions.create({
  type: 'ach_transfer',
  fromAccount: 'acc_1234567890abcdef',
  toExternalAccount: {
    accountNumber: '9876543210',
    routingNumber: '021000021',
    accountType: 'checking',
    holderName: 'John Doe'
  },
  amount: 10000, // $100.00
  currency: 'USD',
  description: 'Rent payment',
  processingSpeed: 'standard' // 'standard', 'expedited', 'instant'
});

Request Body (Internal Transfer):

{
  "type": "transfer",
  "fromAccount": "acc_1234567890abcdef",
  "toAccount": "acc_0987654321fedcba",
  "amount": 5000,
  "currency": "USD",
  "description": "Transfer to savings",
  "reference": "monthly_savings_001",
  "idempotencyKey": "txn_unique_key_123"
}

Response:

{
  "id": "txn_1234567890abcdef",
  "type": "transfer",
  "status": "completed",
  "amount": 5000,
  "currency": "USD",
  "description": "Transfer to savings",
  "reference": "monthly_savings_001",
  "fromAccount": "acc_1234567890abcdef",
  "toAccount": "acc_0987654321fedcba",
  "fee": 0,
  "blockchainHash": "0x1234567890abcdef...",
  "createdAt": "2025-11-07T15:30:00Z",
  "completedAt": "2025-11-07T15:30:15Z"
}

AI-Powered Natural Language Transactions

Process transactions using natural language with AI interpretation.

POST /v1/transactions/ai-intent

// Process natural language transaction request
const aiTransaction = await buburuza.transactions.processAIIntent({
  customerId: 'cust_1234567890abcdef',
  message: "Send $50 to Sarah for dinner last night",
  context: {
    recentContacts: [
      { name: 'Sarah Johnson', accountId: 'acc_sarah_123' },
      { name: 'Mike Smith', accountId: 'acc_mike_456' }
    ],
    currentLocation: 'San Francisco, CA',
    recentTransactions: ['restaurant', 'uber', 'grocery']
  }
});

console.log('AI Intent:', aiTransaction.intent);
console.log('Suggested recipient:', aiTransaction.suggestedRecipient);

// Confirm and execute the AI-suggested transaction
if (aiTransaction.confidence > 0.8) {
  const executedTransaction = await buburuza.transactions.executeAIIntent({
    intentId: aiTransaction.intentId,
    confirmations: {
      recipient: 'acc_sarah_123',
      amount: 5000,
      description: 'Dinner payment'
    }
  });
}

AI Intent Response:

{
  "intentId": "intent_1234567890abcdef",
  "confidence": 0.92,
  "intent": {
    "action": "send_money",
    "amount": 5000,
    "currency": "USD",
    "description": "dinner last night"
  },
  "suggestedRecipient": {
    "name": "Sarah Johnson",
    "accountId": "acc_sarah_123",
    "confidence": 0.95
  },
  "alternatives": [
    {
      "name": "Sarah Mitchell",
      "accountId": "acc_sarah_789",
      "confidence": 0.15
    }
  ]
}

Get Transaction History

Retrieve transaction history for an account.

GET /v1/transactions

const transactions = await buburuza.transactions.list({
  accountId: 'acc_1234567890abcdef',
  startDate: '2025-11-01',
  endDate: '2025-11-07',
  type: 'transfer',
  limit: 25
});

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

Query Parameters:

• accountId (string): Filter by account ID

• customerId (string): Filter by customer ID

• type (string): Filter by transaction type

• status (string): Filter by transaction status

• startDate (string): Start date (ISO format)

• endDate (string): End date (ISO format)

• minAmount (number): Minimum transaction amount

• maxAmount (number): Maximum transaction amount

• limit (number): Number of results (default: 10, max: 100)

Response:

{
  "data": [
    {
      "id": "txn_1234567890abcdef",
      "type": "transfer",
      "status": "completed",
      "amount": 5000,
      "currency": "USD",
      "description": "Transfer to savings",
      "fromAccount": "acc_1234567890abcdef",
      "toAccount": "acc_0987654321fedcba",
      "createdAt": "2025-11-07T15:30:00Z"
    }
  ],
  "hasMore": true,
  "total": 156
}

Balance Management

Get Real-Time Balance

Get current balance with pending transactions.

GET /v1/accounts/{accountId}/balance

const balance = await buburuza.accounts.getBalance('acc_1234567890abcdef');

console.log('Current balance:', balance.current);
console.log('Available balance:', balance.available);
console.log('Pending transactions:', balance.pending);

Response:

{
  "accountId": "acc_1234567890abcdef",
  "current": 15750,
  "available": 15250,
  "pending": 500,
  "reserved": 0,
  "currency": "USD",
  "asOf": "2025-11-07T15:45:30Z",
  "pendingTransactions": [
    {
      "id": "txn_pending_123",
      "amount": 500,
      "description": "Pending ACH transfer",
      "expectedCompletion": "2025-11-08T09:00:00Z"
    }
  ]
}

Balance Alerts

Set up automatic balance notifications.

POST /v1/accounts/{accountId}/alerts

const balanceAlert = await buburuza.accounts.createAlert('acc_1234567890abcdef', {
  type: 'low_balance',
  threshold: 10000, // Alert when balance drops below $100
  notifications: {
    email: true,
    sms: true,
    push: true,
    webhook: 'https://yourapp.com/webhooks/balance-alert'
  },
  frequency: 'immediate' // 'immediate', 'daily', 'weekly'
});

Advanced Banking Features

Scheduled Transfers

Set up recurring or future-dated transfers.

POST /v1/transactions/scheduled

// Recurring monthly transfer
const recurringTransfer = await buburuza.transactions.createScheduled({
  fromAccount: 'acc_1234567890abcdef',
  toAccount: 'acc_0987654321fedcba',
  amount: 50000, // $500.00
  currency: 'USD',
  description: 'Monthly savings',
  schedule: {
    frequency: 'monthly',
    dayOfMonth: 1,
    startDate: '2025-12-01',
    endDate: '2026-12-01'
  }
});

// One-time future transfer
const futureTransfer = await buburuza.transactions.createScheduled({
  fromAccount: 'acc_1234567890abcdef',
  toExternalAccount: {
    accountNumber: '9876543210',
    routingNumber: '021000021'
  },
  amount: 120000, // $1,200.00
  currency: 'USD',
  description: 'Rent payment',
  schedule: {
    frequency: 'once',
    executeAt: '2025-12-01T09:00:00Z'
  }
});

Account Limits and Controls

Manage account spending limits and controls.

PUT /v1/accounts/{accountId}/limits

const updatedLimits = await buburuza.accounts.updateLimits('acc_1234567890abcdef', {
  dailyWithdrawal: 50000, // $500 daily withdrawal limit
  monthlyTransfer: 1000000, // $10,000 monthly transfer limit
  transactionLimit: 100000, // $1,000 per transaction limit
  internationalTransfers: false, // Block international transfers
  atmWithdrawals: true // Allow ATM withdrawals
});

Overdraft Protection

Configure overdraft protection settings.

POST /v1/accounts/{accountId}/overdraft

const overdraftSetup = await buburuza.accounts.setupOverdraft('acc_1234567890abcdef', {
  enabled: true,
  protectionAccount: 'acc_0987654321fedcba', // Savings account for coverage
  limit: 50000, // $500 overdraft limit
  fee: 0, // No overdraft fees
  notifications: {
    email: '[email protected]',
    sms: '[phone]'
  }
});

Multi-Currency Support

Currency Exchange

Convert between supported currencies.

POST /v1/transactions/exchange

const exchange = await buburuza.transactions.createExchange({
  fromAccount: 'acc_usd_123',
  toAccount: 'acc_eur_456',
  fromAmount: 100000, // $1,000.00
  fromCurrency: 'USD',
  toCurrency: 'EUR',
  rateType: 'market', // 'market' or 'fixed'
  slippageTolerance: 0.01 // 1% slippage tolerance
});

console.log('Exchange rate:', exchange.exchangeRate);
console.log('Amount received:', exchange.toAmount);

Real-Time Exchange Rates

Get current exchange rates for supported currencies.

GET /v1/exchange-rates

const rates = await buburuza.exchangeRates.get({
  baseCurrency: 'USD',
  targetCurrencies: ['EUR', 'GBP', 'CAD', 'BTC', 'ETH']
});

console.log('USD to EUR:', rates.EUR);
console.log('USD to BTC:', rates.BTC);

Response:

{
  "baseCurrency": "USD",
  "rates": {
    "EUR": 0.8234,
    "GBP": 0.7456,
    "CAD": 1.2567,
    "BTC": 0.000024,
    "ETH": 0.000412
  },
  "timestamp": "2025-11-07T15:45:00Z",
  "source": "real-time-market"
}

Blockchain Integration

Blockchain Transaction Records

All transactions are automatically recorded on the Buburuza-Chain L3 blockchain for transparency and immutability.

// Get blockchain details for a transaction
const blockchainInfo = await buburuza.transactions.getBlockchainInfo('txn_1234567890abcdef');

console.log('Blockchain hash:', blockchainInfo.hash);
console.log('Block number:', blockchainInfo.blockNumber);
console.log('Confirmations:', blockchainInfo.confirmations);

Response:

{
  "transactionId": "txn_1234567890abcdef",
  "blockchainHash": "0x1234567890abcdef1234567890abcdef12345678",
  "blockNumber": 2847561,
  "confirmations": 12,
  "gasUsed": 21000,
  "gasPrice": "0.000000001",
  "timestamp": "2025-11-07T15:30:15Z",
  "networkId": "buburuza-l3-mainnet"
}

Smart Contract Interactions

Execute smart contract functions for advanced financial operations.

// Interact with a lending smart contract
const lendingContract = await buburuza.blockchain.contract.interact({
  contractAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
  function: 'deposit',
  parameters: {
    amount: '1000000000000000000', // 1 token (18 decimals)
    duration: 2592000 // 30 days in seconds
  },
  fromAccount: 'acc_1234567890abcdef'
});

Error Handling

Common Error Responses

try {
  const transaction = await buburuza.transactions.create({
    type: 'transfer',
    fromAccount: 'acc_1234567890abcdef',
    toAccount: 'acc_0987654321fedcba',
    amount: 1000000, // $10,000
    currency: 'USD'
  });
} catch (error) {
  switch (error.code) {
    case 'insufficient_funds':
      console.log('Not enough money in account');
      console.log('Available:', error.details.availableBalance);
      console.log('Requested:', error.details.requestedAmount);
      break;
      
    case 'account_frozen':
      console.log('Account is temporarily frozen');
      console.log('Reason:', error.details.reason);
      break;
      
    case 'daily_limit_exceeded':
      console.log('Daily withdrawal limit exceeded');
      console.log('Limit:', error.details.dailyLimit);
      console.log('Used today:', error.details.usedToday);
      break;
      
    case 'invalid_recipient':
      console.log('Recipient account not found or invalid');
      break;
      
    default:
      console.log('Unexpected error:', error.message);
  }
}

Error Response Format

{
  "error": {
    "code": "insufficient_funds",
    "message": "The account does not have sufficient funds for this transaction",
    "details": {
      "availableBalance": 5000,
      "requestedAmount": 10000,
      "accountId": "acc_1234567890abcdef"
    },
    "requestId": "req_1234567890abcdef"
  }
}

Webhooks

Transaction Events

Receive real-time notifications for transaction events.

// Configure webhook endpoints
const webhook = await buburuza.webhooks.create({
  url: 'https://yourapp.com/webhooks/transactions',
  events: [
    'transaction.created',
    'transaction.completed',
    'transaction.failed',
    'account.balance_updated'
  ]
});

// Example webhook payload
{
  "id": "evt_1234567890abcdef",
  "type": "transaction.completed",
  "data": {
    "transaction": {
      "id": "txn_1234567890abcdef",
      "type": "transfer",
      "amount": 5000,
      "currency": "USD",
      "status": "completed",
      "fromAccount": "acc_1234567890abcdef",
      "toAccount": "acc_0987654321fedcba"
    }
  },
  "createdAt": "2025-11-07T15:30:00Z"
}

---

Testing in Sandbox

The sandbox environment provides realistic test data and scenarios:

// Sandbox provides test accounts with predefined balances
const sandboxAccount = await buburuza.accounts.create({
  customerId: 'test_customer_123',
  type: 'checking',
  currency: 'USD',
  initialDeposit: 100000 // $1,000 test balance
});

// Test various transaction scenarios
const testScenarios = [
  { amount: 1000, expected: 'success' },
  { amount: 200000, expected: 'insufficient_funds' },
  { amount: -100, expected: 'invalid_amount' }
];

For complete API reference and additional examples, contact support at [email protected].