Bridge Module

The bridge module handles Bridge PSP customer integration and status management for payment service provider operations.

Import

const bridge = await brdzSDK.bridge;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
createBridgeCustomer	Create Bridge customer	✅	POST /bridge/customers
getBridgeStatus	Get Bridge customer status	✅	GET /bridge/status
syncBridgeStatus	Sync Bridge status	✅	GET /bridge/status/sync
getBridgeMode	Get Bridge environment mode	✅	GET /bridge/mode

---

createBridgeCustomer

Create a new Bridge customer for sandbox environment. Builds customer payload from user data and creates customer via Bridge service.

Syntax

const result = await bridge.createBridgeCustomer(data);

Parameters

Parameter	Type	Required	Description
data	object	✅	Customer creation data
data.user_id	number	✅	User ID to create Bridge customer for

Returns

Promise<{
  id: string;
  status: string;
  type: string;
  created_at: string;
  kyc_status: string;
  signed_agreement_id: string;
  capabilities: Array<object>;
  external_accounts: Array<object>;
}>

Example

try {
  const bridgeCustomer = await bridge.createBridgeCustomer({
    user_id: 123
  });
  
  console.log('Bridge Customer ID:', bridgeCustomer.id);
  console.log('Status:', bridgeCustomer.status);
  console.log('KYC Status:', bridgeCustomer.kyc_status);
  console.log('Agreement ID:', bridgeCustomer.signed_agreement_id);
  
  // Store bridge customer ID for future reference
  localStorage.setItem('bridge_customer_id', bridgeCustomer.id);
  
} catch (error) {
  console.error('Bridge customer creation failed:', error.message);
  
  if (error.message.includes('Missing user_id')) {
    console.error('user_id is required in request body');
  }
}

HTTP Endpoint

• Method: POST
• URL: https://api.brdz.link/api/bridge/customers
• Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

---

getBridgeStatus

Check Bridge customer status from database and fetch real-time status from Bridge API.

Syntax

const result = await bridge.getBridgeStatus(params);

Parameters

Parameter	Type	Required	Description
params	object	✅	Query parameters
params.user_id	number	✅	User ID to get Bridge status for

Returns

Promise<{
  id: string;
  status: string;
  type: string;
  kyc_status: string;
  capabilities: Array<{
    id: string;
    status: string;
    supported_currencies: Array<string>;
  }>;
  external_accounts: Array<{
    id: string;
    type: string;
    status: string;
    currency: string;
  }>;
  verification: {
    identity_status: string;
    documents_status: string;
    risk_assessment: string;
  };
  created_at: string;
  updated_at: string;
}>

Example

try {
  const bridgeStatus = await bridge.getBridgeStatus({
    user_id: 123
  });
  
  console.log('Bridge Status:', bridgeStatus.status);
  console.log('KYC Status:', bridgeStatus.kyc_status);
  console.log('Capabilities:', bridgeStatus.capabilities.length);
  
  // Check specific capabilities
  const canSendFunds = bridgeStatus.capabilities.some(cap => 
    cap.id === 'cap_send_funds' && cap.status === 'enabled'
  );
  
  const canReceiveFunds = bridgeStatus.capabilities.some(cap => 
    cap.id === 'cap_receive_funds' && cap.status === 'enabled'
  );
  
  console.log('Can send funds:', canSendFunds);
  console.log('Can receive funds:', canReceiveFunds);
  
  // Display verification status
  if (bridgeStatus.verification) {
    console.log('Identity verified:', bridgeStatus.verification.identity_status === 'verified');
    console.log('Documents verified:', bridgeStatus.verification.documents_status === 'verified');
    console.log('Risk assessment:', bridgeStatus.verification.risk_assessment);
  }
  
} catch (error) {
  console.error('Failed to get Bridge status:', error.message);
  
  if (error.message.includes('User not onboarded to Bridge')) {
    console.error('User needs to create Bridge customer first');
  }
}

HTTP Endpoint

• Method: GET
• URL: https://api.brdz.link/api/bridge/status
• Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

---

syncBridgeStatus

Synchronize Bridge PSP integration status for specific user. Fetches latest status from Bridge API and updates local database.

Syntax

const result = await bridge.syncBridgeStatus(params);

Parameters

Parameter	Type	Required	Description
params	object	✅	Query parameters
params.user_id	number	✅	User ID to sync Bridge status for

Returns

Promise<{
  user_id: number;
  bridge_customer_id: string;
  sync_status: string;
  previous_status: string;
  current_status: string;
  capabilities_updated: boolean;
  changes_detected: Array<{
    field: string;
    from: any;
    to: any;
  }>;
  sync_timestamp: string;
}>

Example

try {
  const syncResult = await bridge.syncBridgeStatus({
    user_id: 123
  });
  
  console.log('Sync Status:', syncResult.sync_status);
  console.log('Status Change:', `${syncResult.previous_status} → ${syncResult.current_status}`);
  console.log('Capabilities Updated:', syncResult.capabilities_updated);
  
  if (syncResult.changes_detected.length > 0) {
    console.log('Changes detected:');
    syncResult.changes_detected.forEach(change => {
      console.log(`  ${change.field}: ${change.from} → ${change.to}`);
    });
    
    // Handle specific changes
    const kycChange = syncResult.changes_detected.find(c => c.field === 'kyc_status');
    if (kycChange && kycChange.to === 'approved') {
      console.log('🎉 KYC has been approved!');
      // Trigger UI update or notification
      notifyKycApproved();
    }
  } else {
    console.log('No changes detected since last sync');
  }
  
} catch (error) {
  console.error('Bridge status sync failed:', error.message);
}

HTTP Endpoint

• Method: GET
• URL: https://api.brdz.link/api/bridge/status/sync
• Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

---

getBridgeMode

Get current Bridge environment mode (Sandbox or Production).

Syntax

const result = await bridge.getBridgeMode();

Parameters

None.

Returns

Promise<{
  mode: string; // "sandbox" | "production"
}>

Example

try {
  const modeResult = await bridge.getBridgeMode();
  
  console.log('Bridge Mode:', modeResult.mode);
  
  // Environment-specific handling
  if (modeResult.mode === 'sandbox') {
    console.log('⚠️ Running in Sandbox mode - test data only');
    showSandboxWarning();
  } else {
    console.log('✅ Running in Production mode - live transactions');
    enableProductionFeatures();
  }
  
  // Store mode for conditional logic
  window.bridgeMode = modeResult.mode;
  
} catch (error) {
  console.error('Failed to get Bridge mode:', error.message);
  // Default to sandbox for safety
  window.bridgeMode = 'sandbox';
}

HTTP Endpoint

• Method: GET
• URL: https://api.brdz.link/api/bridge/mode
• Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

---

Complete Bridge Integration Example

Bridge Customer Management

class BridgeManager {
  constructor(sdk) {
    this.sdk = sdk;
  }

  async onboardCustomer(userId) {
    const bridge = await this.sdk.bridge;
    
    try {
      // Check current mode
      const mode = await bridge.getBridgeMode();
      console.log(`Operating in ${mode.mode} mode`);
      
      // Create Bridge customer
      const customer = await bridge.createBridgeCustomer({
        user_id: userId
      });
      
      console.log('Bridge customer created:', customer.id);
      
      // Initial status check
      const status = await bridge.getBridgeStatus({
        user_id: userId
      });
      
      return {
        customer,
        status,
        mode: mode.mode
      };
    } catch (error) {
      throw new Error(`Bridge onboarding failed: ${error.message}`);
    }
  }

  async monitorCustomerStatus(userId) {
    const bridge = await this.sdk.bridge;
    
    try {
      // Get current status
      const currentStatus = await bridge.getBridgeStatus({
        user_id: userId
      });
      
      // Sync with Bridge API for latest updates
      const syncResult = await bridge.syncBridgeStatus({
        user_id: userId
      });
      
      return {
        current: currentStatus,
        sync: syncResult,
        hasChanges: syncResult.changes_detected.length > 0
      };
    } catch (error) {
      throw new Error(`Status monitoring failed: ${error.message}`);
    }
  }

  async pollStatusUpdates(userId, intervalMs = 30000) {
    const bridge = await this.sdk.bridge;
    
    const poll = async () => {
      try {
        const syncResult = await bridge.syncBridgeStatus({
          user_id: userId
        });
        
        if (syncResult.changes_detected.length > 0) {
          console.log('Bridge status updated:', syncResult.changes_detected);
          
          // Handle specific status changes
          this.handleStatusChanges(syncResult.changes_detected);
        }
        
        // Continue polling if not verified
        if (syncResult.current_status !== 'verified') {
          setTimeout(poll, intervalMs);
        } else {
          console.log('Customer fully verified - stopping polling');
        }
        
      } catch (error) {
        console.error('Polling error:', error.message);
        // Retry in case of temporary error
        setTimeout(poll, intervalMs * 2);
      }
    };
    
    // Start polling
    poll();
  }

  handleStatusChanges(changes) {
    changes.forEach(change => {
      switch (change.field) {
        case 'kyc_status':
          if (change.to === 'approved') {
            this.notifyKycApproved();
          } else if (change.to === 'rejected') {
            this.notifyKycRejected();
          }
          break;
          
        case 'capabilities':
          if (change.to.includes('cap_send_funds')) {
            this.enableSendFunds();
          }
          if (change.to.includes('cap_receive_funds')) {
            this.enableReceiveFunds();
          }
          break;
          
        default:
          console.log(`Status change: ${change.field} = ${change.to}`);
      }
    });
  }

  notifyKycApproved() {
    console.log('🎉 KYC Approved - Full Bridge features available');
    // Update UI, send notification, etc.
  }

  notifyKycRejected() {
    console.log('❌ KYC Rejected - Review required');
    // Show rejection reason, guide user to resubmit
  }

  enableSendFunds() {
    console.log('✅ Send funds capability enabled');
    // Enable send money features in UI
  }

  enableReceiveFunds() {
    console.log('✅ Receive funds capability enabled');
    // Enable receive money features in UI
  }
}

// Usage Example
const bridgeManager = new BridgeManager(brdzSDK);

// Onboard new customer
bridgeManager.onboardCustomer(123)
  .then(result => {
    console.log('Onboarding complete:', result);
    
    // Start monitoring status
    bridgeManager.pollStatusUpdates(123);
  })
  .catch(error => {
    console.error('Onboarding failed:', error.message);
  });

// Manual status check
bridgeManager.monitorCustomerStatus(123)
  .then(result => {
    console.log('Current status:', result.current.status);
    console.log('Has changes:', result.hasChanges);
  })
  .catch(error => {
    console.error('Status check failed:', error.message);
  });

Environment-Aware Integration

// Environment detection and handling
async function initializeBridge() {
  const bridge = await brdzSDK.bridge;
  
  try {
    const mode = await bridge.getBridgeMode();
    
    // Configure app based on mode
    const config = {
      sandbox: {
        showTestWarnings: true,
        enableDebugLogging: true,
        mockData: true
      },
      production: {
        showTestWarnings: false,
        enableDebugLogging: false,
        mockData: false
      }
    };
    
    const appConfig = config[mode.mode] || config.sandbox;
    
    // Apply configuration
    window.bridgeConfig = {
      mode: mode.mode,
      ...appConfig
    };
    
    if (appConfig.showTestWarnings) {
      showBanner('⚠️ Sandbox Mode - Test Environment Only');
    }
    
    return appConfig;
  } catch (error) {
    console.error('Bridge initialization failed:', error.message);
    // Default to sandbox for safety
    return config.sandbox;
  }
}

// Initialize on app start
initializeBridge().then(config => {
  console.log('Bridge initialized with config:', config);
});

Bridge Status Lifecycle

Customer Status Flow

1. not_started → Customer created, verification not begun
2. pending_verification → Documents submitted, under review
3. verified → Customer approved, capabilities enabled
4. rejected → Verification failed, review required

Capability Management

Capabilities are enabled as verification progresses:

• cap_send_funds: Send money to external accounts
• cap_receive_funds: Receive money from external sources
• cap_card_payments: Process card transactions
• cap_ach_transfers: ACH bank transfers

Error Handling

Common Errors

Error	Description	Solution
400: Missing user_id	Required parameter missing	Include user_id in request
404: User not onboarded	No Bridge customer record	Create customer first
500: Bridge API error	External service error	Check Bridge API status
500: Database error	Local database failure	Retry operation

Error Handling Pattern

try {
  const result = await bridge.createBridgeCustomer({ user_id: 123 });
} catch (error) {
  if (error.message.includes('Missing user_id')) {
    // Handle validation error
    showValidationError('User ID is required');
  } else if (error.message.includes('User not onboarded')) {
    // Handle onboarding requirement
    redirectToOnboarding();
  } else if (error.message.includes('Bridge API error')) {
    // Handle external service error
    showServiceError('Bridge service temporarily unavailable');
  } else {
    // Handle generic error
    showGenericError(error.message);
  }
}

Integration Notes

Database Integration

• bridge_customers: Maps local users to Bridge customer IDs
• Activity Logging: Bridge operations logged for audit
• Status Sync: Regular synchronization with Bridge API

PSP Features

• Customer Onboarding: Automated KYC/AML verification
• Capability Management: Progressive feature enablement
• Compliance: Regulatory compliance handled by Bridge
• Transaction Processing: Payment capabilities via Bridge

---

Bridge Integration

Bridge handles complex PSP compliance and verification, allowing focus on core business features.

Sandbox Mode

Sandbox mode uses test data only. No real money movement or actual verification occurs.

Status Monitoring

Use regular status sync to keep local records current with Bridge verification progress.