Skip to main content

Traditional Transaction API - Complete Transaction Management

The Traditional Transaction API provides comprehensive transaction management capabilities for wallet operations, internal transfers, and administrative oversight. Built for enterprise-grade financial applications with full audit trails and multi-user support.

🎯 What Can You Manage?​

Your complete transaction ecosystem with these powerful tools:

  • Wallet Operations: TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT
  • Transaction History: Detailed pagination and filtering capabilities
  • Administrative Controls: Update, delete, and monitor transactions
  • Internal Transaction Logging: Multi-step transaction process tracking
  • Advanced Filtering: Multi-parameter transaction search
  • Full Detail Views: Complete transaction information with steps

🧩 Your Transaction Building Blocks​

📊 Query & Retrieval Blocks​

  • GET /transactions/transfers - Get transfers with filtering
  • GET /transactions/users/:user_id/transactions - User transaction history
  • GET /transactions/:transactionID - Single transaction details
  • GET /transactions/:id/full-detail - Complete transaction information
  • GET /transactions/all - All transactions (admin view)
  • GET /transactions/filter - Advanced filtering capabilities

✏️ Creation & Management Blocks​

  • POST /transactions/transactions - Create new transactions
  • POST /transactions/transactions/internal - Internal transaction records
  • POST /transactions/transactions/log_steps - Log multi-step processes

🔧 Administrative Blocks​

  • PUT /transactions/transfers/:transferID - Update transfer status
  • DELETE /transactions/transfers/:transferID - Remove transfers

🏗️ Common Management Patterns​

Pattern 1: "I want to view user transaction history"​

User ID → getUserTransactions → Paginated transaction list

Use: /transactions/users/:user_id/transactions

Pattern 2: "I want to track transaction status"​

Transaction query → getTransfers → Filter by status → Monitor progress

Use: /transactions/transfers

Pattern 3: "I want to audit all transactions"​

Admin access → getAllTransactions → Full system view

Use: /transactions/all

Pattern 4: "I want to log transaction steps"​

Multi-step transaction → logTransactionWithSteps → Complete audit trail

Use: /transactions/transactions/log_steps

🔧 Transaction Management Details​

Get All Transfers​

GET/api/transactions/transfers

Retrieve All Transfer Transactions

Get a filtered list of all transfer transactions in the system. Supports pagination and returns transactions filtered by wallet transaction types (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT).

Parameters

limitnumber

Maximum number of records to return (default: 10)

offsetnumber

Number of records to skip for pagination (default: 0)

Response

200Transfer list retrieved successfully
{
  "transfers": [
    {
      "transaction_id": "txn_1234567890",
      "type": "WALLET_TRANSFER",
      "amount": 150000,
      "currency": "IDR",
      "status": "SUCCESS_RECEIVED",
      "reference_id": "ref_abc123",
      "description": "Wallet to wallet transfer",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "transaction_id": "txn_0987654321",
      "type": "TOPUP",
      "amount": 75,
      "currency": "SGD",
      "status": "PENDING",
      "reference_id": "ref_def456",
      "description": "Wallet topup via bank transfer",
      "created_at": "2024-01-15T09:15:00Z"
    }
  ]
}
500Failed to fetch transfers
{
  "error": "Failed to fetch transfers",
  "details": "Database connection error"
}

Get User Transaction History​

GET/api/transactions/users/:user_id/transactions

Get User Transaction History

Retrieve comprehensive transaction history for a specific user with pagination support. Combines wallet transactions and non-wallet transactions with detailed source and destination information.

Parameters

user_idstringrequired

User ID to get transaction history for

pagenumber

Page number for pagination (default: 1)

limitnumber

Records per page (default: 10)

Response

200Transaction history retrieved successfully
{
  "page": 1,
  "limit": 10,
  "count": 25,
  "transactions": [
    {
      "transaction_id": "txn_1234567890",
      "transaction_type": "WALLET_TRANSFER",
      "transaction_date": "2024-01-15T10:30:00Z",
      "wallet_id": "wallet_123",
      "wallet_code": "IDR_MAIN",
      "wallet_from_id": "wallet_123",
      "wallet_to_id": "wallet_456",
      "currency_from": "IDR",
      "currency_to": "IDR",
      "amount": 150000,
      "converted_amount": 150000,
      "trans_wallet_type": "WALLET_TRANSFER",
      "trans_wallet_flow": "WALLET_DEBIT",
      "settlement_status": "SUCCESS_RECEIVED",
      "source": "IDR_MAIN",
      "destination": "IDR_SAVINGS",
      "product": "WALLET_TRANSFER",
      "details": "IDR → IDR",
      "balance_type": "WALLET_DEBIT"
    }
  ]
}
400User ID is required
{
  "error": "User ID is required"
}
500Internal server error
{
  "error": "Internal Server Error"
}

Get Transaction Detail​

GET/api/transactions/:transactionID

Get Single Transaction Detail

Retrieve detailed information for a specific transaction by its ID. Returns basic transaction information from the main transactions table.

Parameters

transactionIDstringrequired

Transaction ID to retrieve details for

Response

200Transaction details retrieved successfully
{
  "transaction": {
    "transaction_id": "txn_1234567890",
    "user_id": 123,
    "transaction_type": "WALLET_TRANSFER",
    "transaction_date": "2024-01-15T10:30:00Z",
    "status": "SUCCESS_RECEIVED",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}
404Transaction not found
{
  "error": "Transaction not found"
}
500Failed to fetch transaction detail
{
  "error": "Failed to fetch transaction detail"
}

Get Full Transaction Detail​

GET/api/transactions/:id/full-detail

Get Complete Transaction Information

Retrieve comprehensive transaction details including wallet information, steps, and platform fees. Supports both wallet transactions and non-wallet transactions with complete audit trail.

Parameters

idstringrequired

Transaction ID to get full details for

Response

200Full transaction details retrieved successfully
{
  "transaction": {
    "transaction_id": "txn_1234567890",
    "user_id": 123,
    "transaction_type": "CONVERT",
    "transaction_date": "2024-01-15T10:30:00Z",
    "status": "SUCCESS_RECEIVED"
  },
  "source": "wallet",
  "details": {
    "wallet_id": "wallet_123",
    "wallet_from_id": "wallet_123",
    "wallet_to_id": "wallet_456",
    "amount": 150000,
    "currency_from": "IDR",
    "currency_to": "SGD",
    "converted_amount": 135,
    "platform_fee": 7500,
    "settlement_status": "SUCCESS_RECEIVED",
    "from_wallet_code": "IDR_MAIN",
    "to_wallet_code": "SGD_SAVINGS",
    "trans_wallet_type": "CONVERT",
    "trans_wallet_flow": "WALLET_DEBIT",
    "card_last4": null
  },
  "steps": [
    {
      "step": 1,
      "description": "Debit 150000 IDR from wallet IDR_MAIN"
    },
    {
      "step": 2,
      "description": "Convert IDR to SGD at rate 1111.11"
    },
    {
      "step": 3,
      "description": "Credit 135 SGD to wallet SGD_SAVINGS"
    }
  ]
}
404Transaction not found
{
  "error": "No transaction detail found for this ID"
}
500Internal server error
{
  "error": "Internal Server Error",
  "details": "Database query failed"
}

Create New Transaction​

POST/api/transactions/transactions

Create New Transaction

Create a new transaction record in the system. Requires user authentication and returns the created transaction with a unique ID.

Parameters

user_idnumberrequired

User ID creating the transaction

typestringrequired

Transaction type (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)

amountnumberrequired

Transaction amount

currencystringrequired

Currency code (IDR, SGD, AUD, VND, INR, USD)

reference_idstringrequired

Unique reference identifier for the transaction

descriptionstring

Optional transaction description

Request Body

{
  "user_id": 123,
  "type": "WALLET_TRANSFER",
  "amount": 75000,
  "currency": "IDR",
  "reference_id": "ref_transfer_20240115_001",
  "description": "Wallet to wallet transfer"
}

Response

201Transaction created successfully
{
  "message": "Transaction created successfully!",
  "transaction": {
    "transaction_id": "txn_new_1234567890",
    "user_id": 123,
    "type": "WALLET_TRANSFER",
    "amount": 75000,
    "currency": "IDR",
    "status": "PENDING",
    "reference_id": "ref_transfer_20240115_001",
    "description": "Wallet to wallet transfer",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
400Missing required fields
{
  "error": "Missing required fields: user_id, type, amount, currency, reference_id"
}
500Transaction creation failed
{
  "error": "Failed to create transaction",
  "details": "Database constraint violation"
}

Update Transfer Status​

PUT/api/transactions/transfers/:transferID

Update Transfer Status (Admin Only)

Update the status of an existing transfer. Restricted to admin users only. Allows changing transfer status for administrative oversight and transaction management.

Parameters

transferIDstringrequired

Transfer ID to update

statusstringrequired

New status: PENDING, SUCCESS_RECEIVED, or FAILED

Request Body

{
  "status": "SUCCESS_RECEIVED"
}

Response

200Transfer updated successfully
{
  "message": "Transfer updated successfully",
  "transfer": {
    "transaction_id": "txn_1234567890",
    "status": "SUCCESS_RECEIVED"
  }
}
400Invalid status provided
{
  "error": "Invalid status. Allowed: PENDING, SUCCESS_RECEIVED, FAILED"
}
403Unauthorized access
{
  "error": "Unauthorized access. Only admins can update transfers."
}
404Transfer not found
{
  "error": "Transfer with ID txn_1234567890 not found."
}
500Update failed
{
  "error": "Failed to update transfer",
  "details": "Database update error"
}

Advanced Transaction Filtering​

GET/api/transactions/filter

Get Filtered Transactions

Advanced transaction filtering with multiple parameters. Supports filtering by user, transaction type, wallet, date range, and includes country information for comprehensive transaction analysis.

Parameters

user_idnumber

Filter by specific user ID

typestring

Filter by transaction type (TOPUP, WITHDRAW, WALLET_TRANSFER, WALLET_RECEIVE, CONVERT)

wallet_codestring

Filter by wallet code

start_datestring

Filter from start date (ISO format)

end_datestring

Filter to end date (ISO format)

Response

200Filtered transactions retrieved successfully
{
  "transactions": [
    {
      "transaction_id": "txn_1234567890",
      "created_at": "2024-01-15T10:30:00Z",
      "amount": 100000,
      "asset": "IDR",
      "type": "WALLET_TRANSFER",
      "status": "SUCCESS_RECEIVED",
      "source": "IDR_MAIN",
      "destination": "IDR_SAVINGS",
      "tx_id": "txn_1234567890",
      "country_code": "ID"
    }
  ]
}
404Wallet code not found
{
  "error": "Wallet code not found."
}
500Filter operation failed
{
  "error": "Internal Server Error"
}

🚀 Complete Transaction Management Workflows​

Workflow 1: User Transaction Monitoring​

// Monitor user transaction activity
async function monitorUserActivity(userId) {
  console.log('📊 Monitoring user transaction activity...');
  
  // Get recent transaction history
  const history = await transactions.getUserTransactions(userId, {
    page: 1,
    limit: 10
  });
  
  console.log(`📈 User has ${history.count} total transactions`);
  
  // Check for pending transactions
  const pendingTx = history.transactions.filter(tx => 
    tx.settlement_status === 'PENDING'
  );
  
  if (pendingTx.length > 0) {
    console.log(`⏳ ${pendingTx.length} pending transactions found`);
    
    // Get full details for pending transactions
    for (const tx of pendingTx) {
      const fullDetail = await transactions.getFullTransactionDetail(tx.transaction_id);
      console.log(`🔍 Transaction ${tx.transaction_id}:`);
      console.log(`   Amount: ${fullDetail.details.amount} ${fullDetail.details.currency_from}`);
      console.log(`   Steps: ${fullDetail.steps.length} steps logged`);
    }
  }
  
  return { total: history.count, pending: pendingTx.length };
}

Workflow 2: Administrative Transfer Management​

// Admin transfer oversight and management
async function adminTransferManagement() {
  console.log('🔧 Administrative transfer management...');
  
  // Get all transfers for review
  const transfers = await transactions.getTransfers({
    limit: 50,
    offset: 0
  });
  
  console.log(`📋 Found ${transfers.transfers.length} transfers to review`);
  
  // Find failed transfers that need attention
  const failedTransfers = transfers.transfers.filter(tx => 
    tx.status === 'FAILED'
  );
  
  if (failedTransfers.length > 0) {
    console.log(`❌ ${failedTransfers.length} failed transfers need attention`);
    
    // Review and potentially retry failed transfers
    for (const transfer of failedTransfers) {
      console.log(`🔍 Reviewing failed transfer: ${transfer.transaction_id}`);
      console.log(`   Amount: ${transfer.amount} ${transfer.currency}`);
      console.log(`   Reference: ${transfer.reference_id}`);
      
      // Admin decision to retry (update to PENDING) or keep failed
      const shouldRetry = transfer.description.includes('network_timeout');
      
      if (shouldRetry) {
        const retryResult = await transactions.updateTransfer(transfer.transaction_id, {
          status: 'PENDING'
        });
        console.log(`🔄 Retrying transfer: ${retryResult.message}`);
      }
    }
  }
  
  return { total: transfers.transfers.length, failed: failedTransfers.length };
}

Workflow 3: Currency Conversion Tracking​

// Track currency conversion transactions
async function trackCurrencyConversions(referenceId) {
  console.log('💱 Tracking currency conversion...');
  
  // Create transaction with steps logging
  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
    }
  ];
  
  // Log all steps for audit trail
  await transactions.logTransactionWithSteps({
    reference_id: referenceId,
    log_steps: stepLogs
  });
  
  console.log(`📝 Logged ${stepLogs.length} steps for reference ${referenceId}`);
  
  // Verify transaction completion
  const filteredTx = await transactions.getFilteredTransactions({
    type: 'CONVERT'
  });
  
  const ourConversion = filteredTx.transactions.find(tx => 
    tx.tx_id === referenceId
  );
  
  if (ourConversion) {
    console.log(`✅ Currency conversion completed:`);
    console.log(`   ${ourConversion.amount} ${ourConversion.asset}`);
    console.log(`   ${ourConversion.source} → ${ourConversion.destination}`);
    console.log(`   Status: ${ourConversion.status}`);
    console.log(`   Country: ${ourConversion.country_code}`);
  }
  
  return { reference: referenceId, steps: stepLogs.length };
}

Workflow 4: Transaction Analytics and Reporting​

// Generate transaction analytics and reports
async function generateTransactionAnalytics(userId, dateRange) {
  console.log('📊 Generating transaction analytics...');
  
  // Get filtered transactions for analysis
  const transactionsData = await transactions.getFilteredTransactions({
    user_id: userId,
    start_date: dateRange.start,
    end_date: dateRange.end
  });
  
  // Analyze transaction patterns
  const analytics = {
    totalTransactions: transactionsData.transactions.length,
    totalAmount: 0,
    currencies: new Set(),
    countries: new Set(),
    statusBreakdown: {},
    typeBreakdown: {}
  };
  
  transactionsData.transactions.forEach(tx => {
    analytics.totalAmount += parseFloat(tx.amount);
    analytics.currencies.add(tx.asset);
    if (tx.country_code) analytics.countries.add(tx.country_code);
    
    // Count by status
    analytics.statusBreakdown[tx.status] = 
      (analytics.statusBreakdown[tx.status] || 0) + 1;
    
    // Count by type
    analytics.typeBreakdown[tx.type] = 
      (analytics.typeBreakdown[tx.type] || 0) + 1;
  });
  
  console.log(`📈 Transaction Analytics:`);
  console.log(`   Total Transactions: ${analytics.totalTransactions}`);
  console.log(`   Total Amount: ${analytics.totalAmount.toFixed(2)}`);
  console.log(`   Currencies: ${Array.from(analytics.currencies).join(', ')}`);
  console.log(`   Countries: ${Array.from(analytics.countries).join(', ')}`);
  console.log(`   Status Breakdown:`, analytics.statusBreakdown);
  console.log(`   Type Breakdown:`, analytics.typeBreakdown);
  
  return analytics;
}

🎯 When to Use Which API​

Transaction Monitoring​

  • User history: GET /transactions/users/:user_id/transactions
  • Transfer overview: GET /transactions/transfers
  • System-wide view: GET /transactions/all

Detailed Investigation​

  • Basic details: GET /transactions/:transactionID
  • Complete information: GET /transactions/:id/full-detail
  • Advanced filtering: GET /transactions/filter

Transaction Creation​

  • Standard transactions: POST /transactions/transactions
  • Internal records: POST /transactions/transactions/internal
  • Multi-step logging: POST /transactions/transactions/log_steps

Administrative Control​

  • Status updates: PUT /transactions/transfers/:transferID
  • Transfer removal: DELETE /transactions/transfers/:transferID

💡 Pro Tips for Transaction Management​

Pagination Strategy​

// Efficient pagination for large datasets
async function getAllUserTransactions(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;
}

Error Handling​

// Robust error handling for transaction operations
async function safeTransactionOperation(operation) {
  try {
    return await operation();
  } catch (error) {
    if (error.message.includes('not found')) {
      console.log('Transaction not found - may have been deleted');
      return null;
    } else if (error.message.includes('Unauthorized')) {
      console.log('Admin permissions required for this operation');
      throw new Error('Insufficient permissions');
    } else {
      console.error('Transaction operation failed:', error.message);
      throw error;
    }
  }
}

// Usage
const result = await safeTransactionOperation(() =>
  transactions.updateTransfer("txn_123", { status: "SUCCESS_RECEIVED" })
);

Audit Trail Management​

// Comprehensive audit trail for compliance
async function createAuditTrail(transactionId) {
  const fullDetail = await transactions.getFullTransactionDetail(transactionId);
  
  const auditRecord = {
    transaction_id: transactionId,
    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_count: fullDetail.steps.length,
    platform_fee: fullDetail.details.platform_fee,
    source_wallet: fullDetail.details.from_wallet_code,
    destination_wallet: fullDetail.details.to_wallet_code
  };
  
  console.log('📋 Audit record created:', auditRecord);
  return auditRecord;
}

🔐 Authentication & Authorization​

All transaction endpoints require authentication:

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

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

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

🌍 Supported Transaction Types & Countries​

Transaction Types (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​

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
Transaction Management Best Practices

Always use pagination for large datasets, implement proper error handling for admin operations, and maintain audit trails for compliance. Use filtered queries to optimize performance and leverage full-detail endpoints for comprehensive investigation.

Admin Operations

Update and delete operations are restricted to admin users only. These operations are logged and monitored for security. Always verify transaction status before performing administrative actions.

Multi-Step Transaction Support

Complex transactions like currency conversions support step-by-step logging for complete audit trails. Use the step logging functionality to track multi-phase operations and provide transparency for regulatory compliance.