Getting Started

Getting Started

Quick Start Guide

Welcome to the Buburuza Developer Platform! This guide will help you integrate AI-powered banking services into your application in under 10 minutes.

⚠️ Developer Preview Notice

The Buburuza API is currently in development. This guide shows the planned developer experience. Early access available Q1 2026.

Prerequisites

• Development Environment: Node.js 18+, Python 3.9+, or Java 11+

• Business Information: Company details for compliance verification

• Use Case Description: Brief overview of your intended integration

Step 1: Account Registration

Register for Developer Access

# Registration will be available at https://developers.buburuza.com
curl -X POST https://api.buburuza.com/v1/developer/register \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Acme Corporation",
    "email": "[email protected]",
    "phone": "[phone]",
    "country": "US",
    "use_case": "E-commerce marketplace payments",
    "expected_volume": "1000 transactions/month"
  }'

Verify Your Identity

{
  "registration_id": "reg_1234567890abcdef",
  "status": "pending_verification",
  "next_steps": [
    "Check your email for verification link",
    "Complete business verification form",
    "Upload business documentation"
  ],
  "estimated_approval": "24-48 hours"
}

Step 2: Environment Setup

Install the SDK

# JavaScript/Node.js
npm install @buburuza/sdk

# Python
pip install buburuza-python

# Java
# Add to pom.xml
<dependency>
    <groupId>com.buburuza</groupId>
    <artifactId>buburuza-java</artifactId>
    <version>1.0.0</version>
</dependency>

API Key Configuration

Once approved, you'll receive API keys for both sandbox and production environments:

// JavaScript Example
import { BuburuざAPI } from '@buburuza/sdk';

// Initialize for sandbox testing
const buburuza = new BuburuざAPI({
  apiKey: 'bb_test_1234567890abcdef',
  environment: 'sandbox', // or 'production'
  version: 'v1'
});

// Verify API connection
const status = await buburuza.health.check();
console.log('API Status:', status);

# Python Example
from buburuza import BuburuざAPI

# Initialize client
buburuza = BuburuざAPI(
    api_key='bb_test_1234567890abcdef',
    environment='sandbox'
)

# Test connection
status = buburuza.health.check()
print(f"API Status: {status}")

Step 3: Your First Integration

Create a Customer Account

// Create a new customer
const customer = await buburuza.customers.create({
  email: '[email protected]',
  phone: '[phone]',
  firstName: 'John',
  lastName: 'Doe',
  dateOfBirth: '1990-01-15',
  address: {
    street: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US'
  },
  metadata: {
    source: 'mobile_app',
    referral_code: 'FRIEND123'
  }
});

console.log('Customer created:', customer.id);
// Output: Customer created: cust_1234567890abcdef

Create a Wallet

// Create a USD wallet for the customer
const wallet = await buburuza.wallets.create({
  customerId: customer.id,
  currency: 'USD',
  type: 'personal',
  name: 'Primary Checking'
});

console.log('Wallet created:', wallet);
// Output: {
//   id: 'wallet_1234567890abcdef',
//   customerId: 'cust_1234567890abcdef',
//   currency: 'USD',
//   balance: 0,
//   availableBalance: 0,
//   status: 'active'
// }

Process Your First Payment

// Add funds to the wallet (in sandbox, this is simulated)
const deposit = await buburuza.transactions.create({
  type: 'deposit',
  walletId: wallet.id,
  amount: 10000, // $100.00 (amounts in cents)
  currency: 'USD',
  source: {
    type: 'bank_account',
    accountId: 'bank_acc_sandbox_123'
  },
  description: 'Initial deposit'
});

// Send money to another user
const transfer = await buburuza.transactions.create({
  type: 'transfer',
  fromWalletId: wallet.id,
  toWalletId: 'wallet_recipient_456',
  amount: 2500, // $25.00
  currency: 'USD',
  description: 'Payment for services',
  metadata: {
    orderId: 'order_789',
    category: 'services'
  }
});

console.log('Transfer completed:', transfer.id);

Step 4: Natural Language Processing

AI-Powered Transaction Intent

// Process natural language commands
const aiIntent = await buburuza.ai.parseIntent({
  customerId: customer.id,
  message: "Send $50 to Sarah for dinner last night",
  context: {
    recentContacts: ['sarah_johnson', 'mike_smith'],
    accountBalance: 10000
  }
});

console.log('Parsed intent:', aiIntent);
// Output: {
//   action: 'send_money',
//   amount: 5000,
//   currency: 'USD',
//   recipient: {
//     name: 'Sarah',
//     suggestions: [
//       { id: 'sarah_johnson', confidence: 0.95, name: 'Sarah Johnson' }
//     ]
//   },
//   description: 'dinner last night',
//   confidence: 0.92
// }

// Execute the AI-suggested transaction
if (aiIntent.confidence > 0.8) {
  const aiTransaction = await buburuza.transactions.createFromIntent({
    intentId: aiIntent.id,
    confirmations: {
      recipient: 'sarah_johnson'
    }
  });
}

Step 5: KYC Verification

Initiate Identity Verification

// Start KYC process for the customer
const kycSession = await buburuza.kyc.initiate({
  customerId: customer.id,
  verificationType: 'individual',
  requiredDocuments: ['government_id', 'proof_of_address'],
  webhook: 'https://yourapp.com/webhooks/kyc'
});

console.log('KYC session:', kycSession);
// Output: {
//   sessionId: 'kyc_1234567890abcdef',
//   status: 'initiated',
//   verificationUrl: 'https://verify.buburuza.com/kyc_1234567890abcdef',
//   expiresAt: '2025-11-07T15:30:00Z'
// }

// Check verification status
const kycStatus = await buburuza.kyc.getStatus(kycSession.sessionId);
console.log('KYC Status:', kycStatus.status); // 'pending', 'approved', 'rejected'

Step 6: Webhook Integration

Set Up Real-Time Notifications

// Configure webhooks for your application
const webhook = await buburuza.webhooks.create({
  url: 'https://yourapp.com/webhooks/buburuza',
  events: [
    'transaction.completed',
    'transaction.failed',
    'kyc.completed',
    'wallet.balance_updated'
  ],
  description: 'Main application webhook'
});

// Webhook payload example
app.post('/webhooks/buburuza', (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'transaction.completed':
      console.log('Transaction completed:', event.data.transaction.id);
      // Update your database, send notifications, etc.
      break;
      
    case 'kyc.completed':
      console.log('KYC completed for customer:', event.data.customer.id);
      // Enable additional features for verified customers
      break;
  }
  
  res.status(200).send('OK');
});

Step 7: Error Handling

Robust Error Management

try {
  const transaction = await buburuza.transactions.create({
    type: 'transfer',
    fromWalletId: 'wallet_123',
    toWalletId: 'wallet_456',
    amount: 5000,
    currency: 'USD'
  });
} catch (error) {
  switch (error.code) {
    case 'insufficient_funds':
      console.log('Not enough money in wallet');
      // Show user-friendly error message
      break;
      
    case 'wallet_not_found':
      console.log('Invalid wallet ID');
      // Handle invalid wallet reference
      break;
      
    case 'rate_limit_exceeded':
      console.log('Too many requests');
      // Implement exponential backoff
      break;
      
    default:
      console.log('Unexpected error:', error.message);
      // Log for investigation
  }
}

Step 8: Testing with Sandbox

Use Test Data

// Sandbox provides realistic test data
const testCard = await buburuza.cards.create({
  customerId: customer.id,
  type: 'virtual',
  currency: 'USD',
  metadata: {
    testing: true
  }
});

// Use test card numbers for transactions
const testPayment = await buburuza.payments.create({
  amount: 1000, // $10.00
  currency: 'USD',
  source: {
    type: 'card',
    number: '4111111111111111', // Test Visa card
    expMonth: 12,
    expYear: 2030,
    cvc: '123'
  },
  destination: {
    walletId: wallet.id
  }
});

Simulate Different Scenarios

// Test various scenarios in sandbox
const scenarios = [
  { amount: 100, expected: 'success' },
  { amount: 999999, expected: 'insufficient_funds' },
  { amount: -100, expected: 'invalid_amount' }
];

for (const scenario of scenarios) {
  try {
    const result = await buburuza.transactions.create({
      type: 'withdrawal',
      walletId: wallet.id,
      amount: scenario.amount,
      currency: 'USD'
    });
    console.log(`Scenario ${scenario.amount}: Success`);
  } catch (error) {
    console.log(`Scenario ${scenario.amount}: ${error.code}`);
  }
}

Next Steps

1. Explore Advanced Features

• AI Services: Natural language processing and intelligent automation

• Blockchain Integration: Smart contracts and DeFi connectivity

• Investment APIs: Trading and portfolio management

• Card Programs: Virtual and physical card issuance

2. Production Readiness

• Security Review: Implement proper API key management

• Compliance Setup: Configure KYC/AML requirements for your region

• Monitoring: Set up application monitoring and alerting

• Scaling: Optimize for your expected transaction volume

3. Join the Community

• Developer Forum: https://community.buburuza.com

• Discord: https://discord.gg/buburuza-dev

• GitHub: https://github.com/buburuza-platform

• Email Support: [email protected]

Common Integration Patterns

E-commerce Marketplace

// Split payments between sellers and platform
const marketplacePayment = await buburuza.payments.create({
  amount: 10000, // $100
  currency: 'USD',
  splits: [
    { recipient: 'seller_wallet_123', amount: 9500 }, // 95% to seller
    { recipient: 'platform_wallet_456', amount: 500 }  // 5% platform fee
  ],
  metadata: {
    orderId: 'order_789',
    productId: 'product_456'
  }
});

Subscription Service

// Recurring billing with intelligent retry
const subscription = await buburuza.subscriptions.create({
  customerId: customer.id,
  planId: 'premium_monthly',
  price: 2999, // $29.99
  currency: 'USD',
  trialDays: 14,
  retryPolicy: {
    maxAttempts: 3,
    intervalDays: [1, 3, 7]
  }
});

Gig Economy Platform

// Instant payouts for gig workers
const instantPayout = await buburuza.payouts.create({
  recipientId: 'driver_123',
  amount: 4500, // $45.00
  currency: 'USD',
  speed: 'instant', // Available in minutes
  description: 'Ride earnings - Trip #456'
});

---

You're now ready to build with Buburuza! The platform provides enterprise-grade financial infrastructure with the simplicity of modern APIs. Start building and let us know what you create.