Traditional Wallet Module

The wallet module provides comprehensive traditional wallet management functionality for fiat currencies, transfers, and cross-border payments.

Import

const wallet = await brdzSDK.wallet;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
createWallet	Create new wallet	✅	POST /wallet/create
topUpWallet	Top-up wallet (Mobile/Firebase)	✅	POST /wallet/topup
verifyTopUpOTP	Top-up wallet (Web/Manual)	✅	POST /wallet/topup/verify
checkBalance	Check primary wallet balance	✅	GET /wallet/balance
checkAllBalances	Check all wallet balances	✅	GET /wallet/balances
internalTransfer	Internal wallet transfer	✅	POST /wallet/transfer
convertCurrency	Currency conversion	✅	POST /wallet/convert
withdrawFunds	Bank withdrawal	✅	POST /wallet/withdraw
crossBorderTransfer	Cross-border bank transfer	✅	POST /wallet/cross_border
crossPspTransfer	Cross-PSP transfer	✅	POST /wallet/cross_psp_transfer
mockActivateWallet	Mock wallet activation (⚠️ Deprecated)	⚠️	POST /wallet/mock_activate
getAdminWalletDetail	Admin wallet overview	✅	GET /wallet/admin/detail
updateWalletKeys	Update wallet keys	✅	POST /wallet/admin/update_keys
manualCreateAdminWallet	Create admin wallet	✅	POST /wallet/manual_create_admin_wallet
getWalletsByUserId	Get user wallets (Admin)	✅	GET /wallet/user/:user_id
getPayinQuote	Calculate payin fees	✅	POST /wallet/payin/quote
getPendingPayins	Get pending payins	✅	GET /wallet/payins/:user_id
cancelPendingPayin	Cancel pending payin	✅	DELETE /wallet/payin/:transaction_id
getOfframpQuote	Calculate offramp fees	✅	POST /wallet/offramp/quote
getOfframpByUser	Get offramp history	✅	GET /wallet/offramps/:user_id
deleteOfframpById	Delete offramp record	✅	DELETE /wallet/offramps/:transaction_id
getAllPrefundedAccounts	Get prefunded accounts	✅	GET /wallet/prefunded-accounts
getPrefundedAccountById	Get prefunded account detail	✅	GET /wallet/prefunded-accounts/:id
getPrefundedAccountHistory	Get prefunded account history	✅	GET /wallet/prefunded-accounts/:id/history

Core Wallet Operations

createWallet

Create a new wallet for a user with automatic PSP integration and KYC compliance.

const wallet = await brdzSDK.wallet.createWallet({
  user_id: 123,
  country_code: "ID"
});

console.log(`Wallet created: ${wallet.wallet_id}`);
console.log(`Status: ${wallet.status}`);
console.log(`Currency: ${wallet.currency}`);

Parameters:

• user_id (number, required): User ID who will own the wallet
• country_code (string, required): Country code for wallet currency (ID, SG, AU, etc.)

Returns: Wallet creation response with wallet_id, status, and activation info

topUpWallet

Mobile-optimized top-up with Firebase push notification OTP (2-step process).

// Step 1: Request OTP via Firebase
const otpRequest = await brdzSDK.wallet.topUpWallet({
  wallet_id: "wallet_456789",
  amount: 100000,
  currency: "IDR",
  firebase_token: "your_firebase_token"
});

// Step 2: Complete with OTP from push notification
const topupResult = await brdzSDK.wallet.topUpWallet({
  wallet_id: "wallet_456789",
  amount: 100000,
  currency: "IDR",
  otp_code: "123456"
});

Parameters:

• wallet_id (string, required): Wallet ID to top-up
• amount (number, required): Amount to top-up
• currency (string, required): Currency code
• firebase_token (string, optional): Firebase token for OTP (Step 1)
• otp_code (string, optional): OTP code for verification (Step 2)

Returns: OTP request confirmation or top-up transaction details

verifyTopUpOTP

Web-optimized top-up with manual OTP verification (1-step process).

const topupResult = await brdzSDK.wallet.verifyTopUpOTP({
  wallet_id: "wallet_456789",
  otp_code: "123456"
});

console.log(`Top-up successful: ${topupResult.transaction.transaction_id}`);

Parameters:

• wallet_id (string, required): Wallet ID to top-up
• otp_code (string, required): OTP code for verification

Returns: Top-up transaction details

checkBalance

Get balance information for user's primary wallet using ledger-based calculation.

const balances = await brdzSDK.wallet.checkBalance();

balances.wallets.forEach(wallet => {
  console.log(`${wallet.currency}: ${wallet.balance}`);
  console.log(`  Received: ${wallet.total_received}`);
  console.log(`  Spent: ${wallet.total_spent}`);
});

Returns: Balance information with total received, spent, and current balance

checkAllBalances

Get balance information for all user's active wallets across different currencies.

const allBalances = await brdzSDK.wallet.checkAllBalances();

console.log(`User has ${allBalances.wallets.length} active wallets`);

allBalances.wallets.forEach(wallet => {
  console.log(`${wallet.currency}: ${wallet.balance}`);
});

Returns: Balance information for all user wallets

Transfer Operations

internalTransfer

Transfer funds between wallets within the same PSP provider.

const transfer = await brdzSDK.wallet.internalTransfer({
  from_wallet_id: "wallet_456789",
  to_wallet_id: "wallet_789012",
  amount: 50000,
  note: "Payment for services"
});

console.log(`Transfer ID: ${transfer.transaction_id_transfer}`);
console.log(`Sender balance: ${transfer.from_wallet_balance_after}`);

Parameters:

• from_wallet_id (string, required): Source wallet ID
• to_wallet_id (string, required): Destination wallet ID
• amount (number, required): Transfer amount
• note (string, optional): Transfer note

Returns: Transfer confirmation with transaction IDs and updated balances

convertCurrency

Convert funds between different currencies using real-time exchange rates.

const conversion = await brdzSDK.wallet.convertCurrency({
  user_id: 123,
  amount: 1000000,
  from_currency: "IDR",
  to_currency: "SGD"
});

console.log(`Rate: ${conversion.data.exchange_rate}`);
console.log(`Converted: ${conversion.data.converted_amount} ${conversion.data.to_currency}`);

Parameters:

• user_id (number, required): User ID performing conversion
• amount (number, required): Amount to convert
• from_currency (string, required): Source currency code
• to_currency (string, required): Target currency code

Returns: Conversion details with rates and converted amounts

crossBorderTransfer

Transfer funds from wallet to international bank accounts.

const transfer = await brdzSDK.wallet.crossBorderTransfer({
  from_wallet_id: "wallet_456789",
  amount: 500000,
  to_currency: "SGD",
  bank_account: {
    account_number: "1234567890",
    account_name: "John Doe",
    bank_name: "DBS Bank",
    country_code: "SG"
  },
  note: "International payment"
});

console.log(`Bank transfer: ${transfer.bank_transaction_id}`);

Parameters:

• from_wallet_id (string, required): Source wallet ID
• amount (number, required): Transfer amount
• to_currency (string, required): Target currency
• bank_account (object, required): Bank account details
• note (string, optional): Transfer note

Returns: Cross-border transfer confirmation with bank details

crossPspTransfer

Transfer funds between wallets using different PSP providers.

const transfer = await brdzSDK.wallet.crossPspTransfer({
  from_wallet_id: "wallet_456789",
  to_wallet_id: "wallet_789012",
  amount: 100000,
  note: "Cross-PSP payment"
});

console.log(`Conversion steps: ${transfer.logSteps.length}`);
transfer.logSteps.forEach(step => {
  console.log(`Step ${step.step}: ${step.description}`);
});

Parameters:

• from_wallet_id (string, required): Source wallet ID
• to_wallet_id (string, required): Destination wallet ID
• amount (number, required): Transfer amount
• note (string, optional): Transfer note

Returns: Cross-PSP transfer confirmation with conversion steps

withdrawFunds

Withdraw funds from wallet to bank account.

const withdrawal = await brdzSDK.wallet.withdrawFunds({
  user_id: 123,
  amount: 200000,
  currency: "IDR",
  bank_account: {
    account_number: "9876543210",
    account_name: "Jane Doe",
    bank_name: "Bank Mandiri"
  }
});

Parameters:

• user_id (number, required): User ID
• amount (number, required): Withdrawal amount
• currency (string, required): Currency code
• bank_account (object, required): Bank account details

Returns: Withdrawal confirmation

Payin/Offramp Operations

getPayinQuote

Calculate total fees and amount for payin operations.

const quote = await brdzSDK.wallet.getPayinQuote({
  wallet_id: "wallet_456789",
  amount: 100000,
  currency: "IDR",
  cover_fee: true
});

console.log(`Total with fees: ${quote.total_with_fee}`);
console.log(`Platform fee: ${quote.platform_fee}`);

Parameters:

• wallet_id (string, required): Wallet ID for payin
• amount (number, required): Base payin amount
• currency (string, required): Currency code
• cover_fee (boolean, optional): Include fees in total

Returns: Quote with fee breakdown

getPendingPayins

Retrieve all pending payin transactions for a user.

const payins = await brdzSDK.wallet.getPendingPayins("123");

payins.payins.forEach(payin => {
  console.log(`VA: ${payin.va_number}`);
  console.log(`Amount: ${payin.amount} ${payin.currency_from}`);
  console.log(`Expires: ${payin.va_expired_at}`);
});

Parameters:

• user_id (string, required): User ID to get payins for

Returns: List of pending payin transactions

cancelPendingPayin

Cancel/delete a pending payin transaction.

await brdzSDK.wallet.cancelPendingPayin("TOPUP-1705123456-A1B2");
console.log("Payin cancelled successfully");

Parameters:

• transaction_id (string, required): Transaction ID to cancel

Returns: Cancellation confirmation

getOfframpQuote

Calculate fees and total amount for offramp operations.

const quote = await brdzSDK.wallet.getOfframpQuote({
  wallet_id: "wallet_456789",
  amount: 200000,
  cover_fee: true
});

console.log(`Total cost: ${quote.total_with_fee}`);

Parameters:

• wallet_id (string, required): Wallet ID for offramp
• amount (number, required): Offramp amount
• cover_fee (boolean, optional): Include fees in calculation

Returns: Offramp quote with fees

getOfframpByUser

Retrieve offramp transaction history for a user.

const offramps = await brdzSDK.wallet.getOfframpByUser("123");

offramps.offramps.forEach(offramp => {
  console.log(`${offramp.amount} ${offramp.currency_from} → ${offramp.converted_amount} ${offramp.currency_to}`);
  console.log(`Status: ${offramp.settlement_status}`);
});

Parameters:

• user_id (string, required): User ID to get history for

Returns: Offramp transaction history

deleteOfframpById

Delete an offramp transaction record.

await brdzSDK.wallet.deleteOfframpById("CBT-wallet_456789-200000-1705123456-BANK");
console.log("Offramp record deleted");

Parameters:

• transaction_id (string, required): Transaction ID to delete

Returns: Deletion confirmation

Admin Operations

mockActivateWallet (Deprecated)

Deprecated Method

This method has been deprecated and is no longer available in the backend. Wallet activation now happens automatically during wallet creation when MOCK_MODE is enabled. This method exists in the SDK for backward compatibility but will return an error if called.

Manually activate wallet in mock/development mode.

// ⚠️ DEPRECATED - This method no longer works
// Wallets are now auto-activated during creation in MOCK_MODE

// const activation = await brdzSDK.wallet.mockActivateWallet({
//   wallet_id: "wallet_456789",
//   country_code: "ID"
// });

// Use createWallet instead - activation is automatic
const wallet = await brdzSDK.wallet.createWallet({
  user_id: 123,
  country_code: "ID"
});
// Wallet is automatically activated if MOCK_MODE=true

getAdminWalletDetail

Retrieve comprehensive wallet information for admin users.

const adminWallets = await brdzSDK.wallet.getAdminWalletDetail();

adminWallets.wallets.forEach(wallet => {
  console.log(`${wallet.currency}: ${wallet.balance}`);
  console.log(`Status: ${wallet.wallet_status}`);
});

Returns: Admin wallet overview with balance breakdowns

updateWalletKeys

Update public/secret keys for wallet.

await brdzSDK.wallet.updateWalletKeys({
  public_key: "PUB-new-key-here",
  secret_key: "SEC-new-key-here"
});

console.log("Wallet keys updated");

Parameters:

• public_key (string, required): New public key
• secret_key (string, required): New secret key

Returns: Update confirmation

manualCreateAdminWallet

Create admin wallet manually (emergency function).

const wallet = await brdzSDK.wallet.manualCreateAdminWallet({
  user_id: 123
});

console.log(`Admin wallet created: ${wallet.wallet_code}`);

Parameters:

• user_id (number, required): User ID for admin wallet

Returns: Created admin wallet details

getWalletsByUserId

Administrative view of all wallets belonging to a specific user.

const userWallets = await brdzSDK.wallet.getWalletsByUserId("123");

userWallets.wallets.forEach(wallet => {
  console.log(`${wallet.currency}: ${wallet.balance}`);
  console.log(`KYC Verified: ${wallet.is_kyc_verified}`);
  console.log(`Limited: ${wallet.is_limited}`);
});

Parameters:

• user_id (string, required): User ID to get wallets for

Returns: User wallet details with KYC status

Prefunded Account Operations

getAllPrefundedAccounts

Get list of all prefunded accounts.

const accounts = await brdzSDK.wallet.getAllPrefundedAccounts();

accounts.data.forEach(account => {
  console.log(`Wallet: ${account.wallet_id}`);
  console.log(`Balance: ${account.total_balance} ${account.currency}`);
});

Returns: List of prefunded accounts

getPrefundedAccountById

Get detailed information for a specific prefunded account.

const account = await brdzSDK.wallet.getPrefundedAccountById("wallet_123");

console.log(`Total Balance: ${account.data.total_balance}`);
console.log(`Currency: ${account.data.currency}`);

Parameters:

• id (string, required): Prefunded account ID

Returns: Prefunded account details

getPrefundedAccountHistory

Get transaction history for a prefunded account.

const history = await brdzSDK.wallet.getPrefundedAccountHistory("wallet_123", {
  limit: 20,
  offset: 0
});

history.data.forEach(tx => {
  console.log(`${tx.type}: ${tx.amount} ${tx.currency}`);
  console.log(`Status: ${tx.status}`);
});

Parameters:

• id (string, required): Prefunded account ID
• params (object, optional): Query parameters (limit, offset)

Returns: Transaction history for prefunded account

Complete Usage Examples

Basic Wallet Setup

// Configure SDK
const config = await brdzSDK.config;
config.setApiKey('your-api-key');
config.setToken('your-jwt-token');

// Create wallet for Indonesian user
const wallet = await brdzSDK.wallet.createWallet({
  user_id: 123,
  country_code: "ID"
});

// Activate wallet in development
if (process.env.NODE_ENV === 'development') {
  await brdzSDK.wallet.mockActivateWallet({
    wallet_id: wallet.wallet_id,
    country_code: "ID"
  });
}

// Check initial balance
const balance = await brdzSDK.wallet.checkBalance();
console.log(`Initial balance: ${balance.wallets[0].balance} ${balance.wallets[0].currency}`);

Mobile Top-Up Flow

// Mobile top-up with Firebase OTP
async function mobileTopUp(walletId, amount, currency, firebaseToken) {
  // Step 1: Request OTP
  const otpRequest = await brdzSDK.wallet.topUpWallet({
    wallet_id: walletId,
    amount: amount,
    currency: currency,
    firebase_token: firebaseToken
  });
  
  console.log('OTP sent via Firebase');
  
  // Step 2: User provides OTP from push notification
  const otpCode = await getUserOTPInput();
  
  // Step 3: Complete top-up
  const result = await brdzSDK.wallet.topUpWallet({
    wallet_id: walletId,
    amount: amount,
    currency: currency,
    otp_code: otpCode
  });
  
  return result;
}

Web Top-Up Flow

// Web top-up with manual OTP
async function webTopUp(walletId, otpCode) {
  // Single step: verify OTP and complete top-up
  const result = await brdzSDK.wallet.verifyTopUpOTP({
    wallet_id: walletId,
    otp_code: otpCode
  });
  
  console.log(`Top-up successful: ${result.transaction.transaction_id}`);
  return result;
}

Cross-Border Payment

// International payment workflow
async function sendInternationalPayment(fromWalletId, amount, targetCurrency, bankAccount) {
  // Get quote first
  const quote = await brdzSDK.wallet.getOfframpQuote({
    wallet_id: fromWalletId,
    amount: amount
  });
  
  console.log(`Total cost: ${quote.total_with_fee}`);
  
  // Execute transfer
  const transfer = await brdzSDK.wallet.crossBorderTransfer({
    from_wallet_id: fromWalletId,
    amount: amount,
    to_currency: targetCurrency,
    bank_account: bankAccount,
    note: "International payment"
  });
  
  console.log(`Transfer completed: ${transfer.bank_transaction_id}`);
  return transfer;
}

Multi-Currency Management

// Manage multiple currency wallets
async function manageMultiCurrency(userId) {
  // Check all balances
  const allBalances = await brdzSDK.wallet.checkAllBalances();
  
  console.log(`User has ${allBalances.wallets.length} wallets`);
  
  // Find richest wallet
  const richestWallet = allBalances.wallets.reduce((prev, current) => 
    prev.balance > current.balance ? prev : current
  );
  
  // Convert part of richest wallet to USD
  if (richestWallet.currency !== 'USD' && richestWallet.balance > 1000) {
    const conversion = await brdzSDK.wallet.convertCurrency({
      user_id: userId,
      amount: richestWallet.balance * 0.1,
      from_currency: richestWallet.currency,
      to_currency: 'USD'
    });
    
    console.log(`Converted ${conversion.data.original_amount} ${conversion.data.from_currency} to ${conversion.data.converted_amount} ${conversion.data.to_currency}`);
  }
  
  return allBalances;
}

Error Handling

// Robust error handling for wallet operations
async function safeWalletOperation(operation) {
  try {
    return await operation();
  } catch (error) {
    if (error.message.includes('Insufficient balance')) {
      return { error: 'insufficient_funds', suggestion: 'topup_required' };
    } else if (error.message.includes('not found')) {
      return { error: 'wallet_not_found', suggestion: 'verify_wallet_id' };
    } else if (error.message.includes('Invalid OTP')) {
      return { error: 'invalid_otp', suggestion: 'request_new_otp' };
    } else if (error.message.includes('PSP')) {
      return { error: 'psp_unavailable', suggestion: 'retry_later' };
    } else {
      console.error('Unexpected wallet error:', error.message);
      throw error;
    }
  }
}

// Usage
const result = await safeWalletOperation(() =>
  brdzSDK.wallet.internalTransfer({
    from_wallet_id: "wallet_123",
    to_wallet_id: "wallet_456",
    amount: 100000
  })
);

Platform-Specific Integration

// Detect platform and use appropriate top-up method
class WalletManager {
  static async topUp(walletId, amount, currency, platform = 'web') {
    if (platform === 'mobile') {
      return this.mobileTopUp(walletId, amount, currency);
    } else {
      return this.webTopUp(walletId, otpCode);
    }
  }
  
  static async mobileTopUp(walletId, amount, currency) {
    // Firebase OTP flow
    const otpRequest = await brdzSDK.wallet.topUpWallet({
      wallet_id: walletId,
      amount,
      currency,
      firebase_token: await getFirebaseToken()
    });
    
    const otpCode = await this.waitForOTPInput();
    
    return await brdzSDK.wallet.topUpWallet({
      wallet_id: walletId,
      amount,
      currency,
      otp_code: otpCode
    });
  }
  
  static async webTopUp(walletId, otpCode) {
    // Direct OTP verification
    return await brdzSDK.wallet.verifyTopUpOTP({
      wallet_id: walletId,
      otp_code: otpCode
    });
  }
}