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: '+1-555-0123'
  }
});

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].

PreviousAuthentication API NextAi-Services API

Last updated 3 months ago

hashtagCore Banking APIs

hashtagOverview

hashtagAccounts API

hashtagCreate Account

hashtagGet Account Details

hashtagList Accounts

hashtagTransactions API

hashtagCreate Transaction

hashtagAI-Powered Natural Language Transactions

hashtagGet Transaction History

hashtagBalance Management

hashtagGet Real-Time Balance

hashtagBalance Alerts

hashtagAdvanced Banking Features

hashtagScheduled Transfers

hashtagAccount Limits and Controls

hashtagOverdraft Protection

hashtagMulti-Currency Support

hashtagCurrency Exchange

hashtagReal-Time Exchange Rates

hashtagBlockchain Integration

hashtagBlockchain Transaction Records

hashtagSmart Contract Interactions

hashtagError Handling

hashtagCommon Error Responses

hashtagError Response Format

hashtagWebhooks

hashtagTransaction Events

hashtagTesting in Sandbox

Core Banking APIs

Overview

Accounts API

Create Account

Get Account Details

List Accounts

Transactions API

Create Transaction

AI-Powered Natural Language Transactions

Get Transaction History

Balance Management

Get Real-Time Balance

Balance Alerts

Advanced Banking Features

Scheduled Transfers

Account Limits and Controls

Overdraft Protection

Multi-Currency Support

Currency Exchange

Real-Time Exchange Rates

Blockchain Integration

Blockchain Transaction Records

Smart Contract Interactions

Error Handling

Common Error Responses

Error Response Format

Webhooks

Transaction Events

Testing in Sandbox