Traditional Transactions Module

The transactions module handles comprehensive transaction management for enterprise-grade financial applications. All methods are backend-verified and support complete audit trails, multi-user operations, and administrative controls.

Import

const transactions = await brdzSDK.transactions;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
getTransfers	Get all transfers with filtering	✅	GET /transactions/transfers
getById	Get transaction by ID	✅	GET /transactions/:transactionID
getUserTransactions	Get user transaction history	✅	GET /transactions/users/:user_id/transactions
getAllTransactions	Get all transactions (admin)	✅	GET /transactions/all
getFilteredTransactions	Advanced transaction filtering	✅	GET /transactions/filter
getFullTransactionDetail	Get complete transaction info	✅	GET /transactions/:id/full-detail
createTransaction	Create new transaction	✅	POST /transactions/transactions
createTransactionRecord	Create internal transaction record	✅	POST /transactions/transactions/internal
logTransactionWithSteps	Log multi-step transaction process	✅	POST /transactions/transactions/log_steps
updateTransfer	Update transfer status (admin)	✅	PUT /transactions/transfers/:transferID
deleteTransfer	Delete transfer (admin)	✅	DELETE /transactions/transfers/:transferID

Method Details

getTransfers

Get all transfer transactions with optional filtering and pagination.

const transfers = await transactions.getTransfers({
  limit: 20,
  offset: 0
});

console.log(`Found ${transfers.transfers.length} transfers`);
transfers.transfers.forEach(transfer => {
  console.log(`${transfer.type}: ${transfer.amount} ${transfer.currency} - ${transfer.status}`);
});

Parameters:

• limit (number, optional): Maximum records to return (default: 10)
• offset (number, optional): Records to skip for pagination (default: 0)

Returns: Array of transfer transactions (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)

Authentication: Requires JWT token

getById

Get detailed information for a specific transaction by ID.

const transaction = await transactions.getById("txn_1234567890");

console.log(`Transaction: ${transaction.transaction.transaction_id}`);
console.log(`Type: ${transaction.transaction.transaction_type}`);
console.log(`Status: ${transaction.transaction.status}`);

Parameters:

• transactionID (string, required): Transaction ID to retrieve

Returns: Basic transaction information from main transactions table

Authentication: Requires JWT token

getUserTransactions

Get comprehensive transaction history for a specific user with pagination.

const history = await transactions.getUserTransactions("123", {
  page: 1,
  limit: 20
});

console.log(`Page ${history.page} of user transactions (${history.count} total)`);
history.transactions.forEach(tx => {
  console.log(`${tx.transaction_type}: ${tx.amount} ${tx.currency_from} → ${tx.currency_to}`);
  console.log(`  Status: ${tx.settlement_status}`);
  console.log(`  Flow: ${tx.source} → ${tx.destination}`);
});

Parameters:

• user_id (string, required): User ID to get transaction history for
• page (number, optional): Page number for pagination (default: 1)
• limit (number, optional): Records per page (default: 10)

Returns: Paginated transaction history combining wallet and non-wallet transactions

Authentication: Requires JWT token

getAllTransactions

Get all transactions in the system (admin function).

const allTx = await transactions.getAllTransactions({
  user_id: 123
});

console.log(`Found ${allTx.transactions.length} transactions`);
allTx.transactions.forEach(tx => {
  console.log(`${tx.type}: ${tx.amount} ${tx.asset} - ${tx.status}`);
  console.log(`  ${tx.source} → ${tx.destination}`);
});

Parameters:

• user_id (number, optional): Filter by specific user ID

Returns: All wallet transactions with source/destination details

Authentication: Requires JWT token with admin privileges

getFilteredTransactions

Advanced transaction filtering with multiple parameters.

const filteredTx = await transactions.getFilteredTransactions({
  user_id: 123,
  type: "WALLET_TRANSFER",
  start_date: "2024-01-01T00:00:00Z",
  end_date: "2024-01-31T23:59:59Z"
});

console.log(`Found ${filteredTx.transactions.length} filtered transactions`);
filteredTx.transactions.forEach(tx => {
  console.log(`${tx.type}: ${tx.amount} ${tx.asset} (${tx.country_code})`);
  console.log(`  ${tx.source} → ${tx.destination} - ${tx.status}`);
});

Parameters:

• user_id (number, optional): Filter by user ID
• type (string, optional): Filter by transaction type (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)
• wallet_code (string, optional): Filter by wallet code
• start_date (string, optional): Filter from start date (ISO format)
• end_date (string, optional): Filter to end date (ISO format)

Returns: Filtered transactions with country information

Authentication: Requires JWT token

getFullTransactionDetail

Get comprehensive transaction details including steps and platform fees.

const fullDetail = await transactions.getFullTransactionDetail("txn_1234567890");

console.log(`Transaction: ${fullDetail.transaction.transaction_id}`);
console.log(`Source: ${fullDetail.source}`);
console.log(`Amount: ${fullDetail.details.amount} ${fullDetail.details.currency_from}`);
console.log(`Converted: ${fullDetail.details.converted_amount} ${fullDetail.details.currency_to}`);
console.log(`Platform Fee: ${fullDetail.details.platform_fee}`);

// Show transaction steps
console.log("Transaction steps:");
fullDetail.steps.forEach(step => {
  console.log(`  Step ${step.step}: ${step.description}`);
});

Parameters:

• id (string, required): Transaction ID to get full details for

Returns: Complete transaction information with wallet details, steps, and fees

Authentication: Requires JWT token

createTransaction

Create a new transaction record in the system.

const newTransaction = await transactions.createTransaction({
  user_id: 123,
  type: "WALLET_TRANSFER",
  amount: 75000.00,
  currency: "IDR",
  reference_id: "ref_transfer_20240115_001",
  description: "Wallet to wallet transfer"
});

console.log(`Created transaction: ${newTransaction.transaction.transaction_id}`);
console.log(`Status: ${newTransaction.transaction.status}`);
console.log(`Reference: ${newTransaction.transaction.reference_id}`);

Parameters:

• user_id (number, required): User ID creating the transaction
• type (string, required): Transaction type (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)
• amount (number, required): Transaction amount
• currency (string, required): Currency code (IDR, SGD, AUD, VND, INR, USD)
• reference_id (string, required): Unique reference identifier
• description (string, optional): Transaction description

Returns: Created transaction with unique ID and PENDING status

Authentication: Requires JWT token

createTransactionRecord

Create transaction record for internal use with custom status.

const internalTx = await transactions.createTransactionRecord({
  user_id: 123,
  type: "TOPUP",
  amount: 150000.00,
  currency: "IDR",
  reference_id: "internal_ref_001",
  description: "System-generated topup",
  status: "SUCCESS_RECEIVED"
});

console.log(`Internal transaction created: ${internalTx.transaction_id}`);

Parameters:

• user_id (number, required): User ID
• type (string, required): Transaction type (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)
• amount (number, required): Transaction amount
• currency (string, required): Currency code
• reference_id (string, required): Unique reference identifier
• description (string, optional): Transaction description
• status (string, optional): Transaction status (default: PENDING)

Returns: Created transaction record with specified status

Authentication: Requires JWT token

logTransactionWithSteps

Log detailed steps for multi-phase transactions like currency conversions.

const stepLogs = [
  {
    step: 1,
    description: "Debit 150000 IDR from wallet IDR_MAIN",
    rate: null,
    converted_amount: 150000.00
  },
  {
    step: 2,
    description: "Convert IDR to SGD at rate 1111.11",
    rate: 1111.11,
    converted_amount: 135.00
  },
  {
    step: 3,
    description: "Credit 135 SGD to wallet SGD_SAVINGS",
    rate: null,
    converted_amount: 135.00
  }
];

await transactions.logTransactionWithSteps({
  reference_id: "convert_ref_001",
  log_steps: stepLogs
});

console.log(`Logged ${stepLogs.length} steps for transaction audit trail`);

Parameters:

• reference_id (string, required): Transaction reference ID
• log_steps (array, required): Array of step objects with step number, description, rate, and converted amount

Returns: Confirmation of logged steps for audit trail

Authentication: Requires JWT token

updateTransfer

Update transfer status (admin only operation).

const updateResult = await transactions.updateTransfer("txn_1234567890", {
  status: "SUCCESS_RECEIVED"
});

console.log(`${updateResult.message}`);
console.log(`Transfer ${updateResult.transfer.transaction_id} is now ${updateResult.transfer.status}`);

Parameters:

• transferID (string, required): Transfer ID to update
• status (string, required): New status (PENDING, SUCCESS_RECEIVED, or FAILED)

Returns: Update confirmation with new status

Authentication: Requires JWT token with admin role

deleteTransfer

Delete transfer (admin only operation with restrictions).

try {
  await transactions.deleteTransfer("txn_1234567890");
  console.log("Transfer deleted successfully");
} catch (error) {
  if (error.message.includes('Cannot delete a successful transfer')) {
    console.log("Cannot delete completed transfers");
  }
}

Parameters:

• transferID (string, required): Transfer ID to delete

Returns: 204 status on successful deletion

Authentication: Requires JWT token with admin role

Note: Cannot delete transfers with SUCCESS_RECEIVED status

Complete Usage Examples

Basic Transaction Management

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

// Get user transaction history
const userHistory = await transactions.getUserTransactions("123", {
  page: 1,
  limit: 10
});

// Create a new transaction
const newTx = await transactions.createTransaction({
  user_id: 123,
  type: "WALLET_TRANSFER",
  amount: 75000.00,
  currency: "IDR",
  reference_id: "unique_ref_001",
  description: "Test transaction"
});

// Get detailed transaction information
const details = await transactions.getFullTransactionDetail(newTx.transaction.transaction_id);

Administrative Operations

// Get all transfers for admin review
const transfers = await transactions.getTransfers({
  limit: 50,
  offset: 0
});

// Update transfer status (admin only)
const updateResult = await transactions.updateTransfer("txn_123", {
  status: "SUCCESS_RECEIVED"
});

// Advanced filtering for analysis
const filteredTx = await transactions.getFilteredTransactions({
  type: "CONVERT",
  start_date: "2024-01-01T00:00:00Z",
  end_date: "2024-01-31T23:59:59Z"
});

Currency Conversion Tracking

// Create transaction with detailed step logging
const conversionRef = "convert_idr_sgd_001";

// Log each step of the conversion process
await transactions.logTransactionWithSteps({
  reference_id: conversionRef,
  log_steps: [
    {
      step: 1,
      description: "Debit 150000 IDR from IDR_MAIN wallet",
      rate: null,
      converted_amount: 150000.00
    },
    {
      step: 2,
      description: "Currency conversion IDR to SGD at rate 1111.11",
      rate: 1111.11,
      converted_amount: 135.00
    },
    {
      step: 3,
      description: "Credit 135 SGD to SGD_SAVINGS wallet",
      rate: null,
      converted_amount: 135.00
    }
  ]
});

// Verify conversion completion
const fullDetails = await transactions.getFullTransactionDetail(conversionRef);
console.log(`Conversion completed with ${fullDetails.steps.length} logged steps`);

Supported Transaction Types

Transaction Categories (Based on Backend Model)

• TOPUP - Credit funds to wallet (trans_wallet_flow: WALLET_CREDIT)
• WITHDRAW - Debit funds from wallet (trans_wallet_flow: WALLET_DEBIT)
• WALLET_TRANSFER - Transfer funds from wallet (trans_wallet_flow: WALLET_DEBIT)
• WALLET_RECEIVE - Receive funds to wallet (trans_wallet_flow: WALLET_CREDIT)
• CONVERT - Currency conversion (trans_wallet_flow: WALLET_DEBIT)

Settlement Status Options

• PENDING - Transaction initiated, awaiting processing
• SUCCESS_RECEIVED - Transaction completed and settled
• FAILED - Transaction failed, requires attention
• SETTLED - Transaction settled and finalized

Currency & Country Support

Multiple fiat currencies based on user country:

• IDR (Indonesia) - Primary currency, country code: ID
• SGD (Singapore) - Regional currency, country code: SG
• AUD (Australia) - Regional currency, country code: AU
• VND (Vietnam) - Regional currency, country code: VN
• INR (India) - Regional currency, country code: IN
• USD (United States) - International standard, country code: US

Error Handling

try {
  const result = await transactions.createTransaction({
    user_id: 123,
    type: "WALLET_TRANSFER",
    amount: 75000.00,
    currency: "IDR",
    reference_id: "test_ref"
  });
} catch (error) {
  if (error.message.includes('Missing required fields')) {
    console.error('Invalid parameters provided');
  } else if (error.message.includes('Unauthorized')) {
    console.error('Admin permissions required');
  } else {
    console.error('Transaction operation failed:', error.message);
  }
}

Authentication Requirements

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

// User-level operations
await transactions.getUserTransactions("123");
await transactions.createTransaction(data);
await transactions.getById("txn_123");

// Admin-level operations (requires admin role)
await transactions.updateTransfer("txn_123", { status: "SUCCESS_RECEIVED" });
await transactions.deleteTransfer("txn_123");
await transactions.getAllTransactions();

Development Tips

Pagination Best Practices

// Efficient pagination for large datasets
async function getAllUserData(userId) {
  const allTransactions = [];
  let page = 1;
  const limit = 50;
  
  while (true) {
    const result = await transactions.getUserTransactions(userId, {
      page,
      limit
    });
    
    allTransactions.push(...result.transactions);
    
    if (result.transactions.length < limit) {
      break; // No more pages
    }
    
    page++;
  }
  
  return allTransactions;
}

Audit Trail Management

// Create comprehensive audit trail
async function createTransactionAudit(transactionId) {
  const fullDetail = await transactions.getFullTransactionDetail(transactionId);
  
  return {
    transaction_id: transactionId,
    audit_timestamp: new Date().toISOString(),
    transaction_type: fullDetail.transaction.transaction_type,
    amount: fullDetail.details.amount,
    currency: fullDetail.details.currency_from,
    status: fullDetail.details.settlement_status,
    steps_logged: fullDetail.steps.length,
    platform_fee: fullDetail.details.platform_fee,
    source_wallet: fullDetail.details.from_wallet_code,
    destination_wallet: fullDetail.details.to_wallet_code
  };
}

Advanced Filtering

// Complex filtering for analytics
async function getTransactionAnalytics(filters) {
  const transactionsData = await transactions.getFilteredTransactions(filters);
  
  return {
    total_transactions: transactionsData.transactions.length,
    total_amount: transactionsData.transactions.reduce((sum, tx) => 
      sum + parseFloat(tx.amount), 0),
    status_breakdown: transactionsData.transactions.reduce((acc, tx) => {
      acc[tx.status] = (acc[tx.status] || 0) + 1;
      return acc;
    }, {}),
    currency_distribution: [...new Set(transactionsData.transactions.map(tx => tx.asset))]
  };
}

Currency Conversion Examples

// Example: IDR to SGD conversion
async function performCurrencyConversion(userId, fromAmount, fromCurrency, toCurrency) {
  // Create conversion transaction
  const conversion = await transactions.createTransaction({
    user_id: userId,
    type: "CONVERT",
    amount: fromAmount,
    currency: fromCurrency,
    reference_id: `convert_${fromCurrency}_${toCurrency}_${Date.now()}`,
    description: `Convert ${fromAmount} ${fromCurrency} to ${toCurrency}`
  });
  
  // Log conversion steps
  const conversionRate = fromCurrency === 'IDR' && toCurrency === 'SGD' ? 1111.11 : 1;
  const convertedAmount = fromAmount / conversionRate;
  
  await transactions.logTransactionWithSteps({
    reference_id: conversion.transaction.reference_id,
    log_steps: [
      {
        step: 1,
        description: `Debit ${fromAmount} ${fromCurrency} from wallet`,
        rate: null,
        converted_amount: fromAmount
      },
      {
        step: 2,
        description: `Convert ${fromCurrency} to ${toCurrency} at rate ${conversionRate}`,
        rate: conversionRate,
        converted_amount: convertedAmount
      },
      {
        step: 3,
        description: `Credit ${convertedAmount} ${toCurrency} to wallet`,
        rate: null,
        converted_amount: convertedAmount
      }
    ]
  });
  
  return {
    transaction_id: conversion.transaction.transaction_id,
    from_amount: fromAmount,
    from_currency: fromCurrency,
    to_amount: convertedAmount,
    to_currency: toCurrency,
    conversion_rate: conversionRate
  };
}

// Usage example
const conversionResult = await performCurrencyConversion(123, 150000, 'IDR', 'SGD');
console.log(`Converted ${conversionResult.from_amount} ${conversionResult.from_currency} to ${conversionResult.to_amount} ${conversionResult.to_currency}`);