Bridge API

Bridge customer integration and PSP status management. Bridge is a payment service provider that handles customer onboarding and verification processes.

Create Bridge Customer

POST/api/bridge/customers

Create Bridge Customer

Create a new Bridge customer for sandbox environment. Builds customer payload from user data, creates customer via Bridge service, and stores mapping in database.

Parameters

user_idnumberrequired

User ID to create Bridge customer for

Request Body

{
  "user_id": 123
}

Response

201Bridge customer created successfully

{
  "id": "bridge_customer_1234567890",
  "status": "not_started",
  "type": "individual",
  "created_at": "2024-01-15T10:30:00Z",
  "kyc_status": "not_started",
  "signed_agreement_id": "agreement_abc123",
  "capabilities": [],
  "external_accounts": []
}

400Missing user_id

{
  "error": "Missing user_id in request body"
}

500Bridge customer creation failed

{
  "error": "Failed to create Bridge customer",
  "details": "Bridge API error details"
}

curl -X POST https://api.brdz.link/api/bridge/customers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"user_id": 123}'

Get Bridge Status

GET/api/bridge/status

Get Bridge Status

Check Bridge customer status from database and fetch real-time status from Bridge API. Returns current verification and capability status.

Parameters

user_idnumberrequired

User ID to get Bridge status for (query parameter)

Response

200Bridge status retrieved successfully

{
  "id": "bridge_customer_1234567890",
  "status": "verified",
  "type": "individual",
  "kyc_status": "approved",
  "capabilities": [
    {
      "id": "cap_send_funds",
      "status": "enabled",
      "supported_currencies": [
        "USD",
        "EUR"
      ]
    },
    {
      "id": "cap_receive_funds",
      "status": "enabled",
      "supported_currencies": [
        "USD",
        "EUR"
      ]
    }
  ],
  "external_accounts": [
    {
      "id": "ext_acc_123",
      "type": "bank_account",
      "status": "verified",
      "currency": "USD"
    }
  ],
  "verification": {
    "identity_status": "verified",
    "documents_status": "verified",
    "risk_assessment": "low"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z"
}

400Missing user_id parameter

{
  "error": "user_id is required"
}

404User not onboarded to Bridge

{
  "error": "User not onboarded to Bridge"
}

500Failed to fetch Bridge status

{
  "error": "Failed to fetch Bridge status"
}

curl -X GET "https://api.brdz.link/api/bridge/status?user_id=123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Sync Bridge Status

GET/api/bridge/status/sync

Sync Bridge Status

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

Parameters

user_idnumberrequired

User ID to sync Bridge status for (query parameter)

Response

200Bridge status synced successfully

{
  "user_id": 123,
  "bridge_customer_id": "bridge_customer_1234567890",
  "sync_status": "completed",
  "previous_status": "pending_verification",
  "current_status": "verified",
  "capabilities_updated": true,
  "changes_detected": [
    {
      "field": "kyc_status",
      "from": "pending",
      "to": "approved"
    },
    {
      "field": "capabilities",
      "from": [],
      "to": [
        "cap_send_funds",
        "cap_receive_funds"
      ]
    }
  ],
  "sync_timestamp": "2024-01-15T12:00:00Z"
}

400Missing user_id parameter

{
  "error": "user_id is required"
}

500Sync operation failed

{
  "error": "Failed to sync Bridge status"
}

curl -X GET "https://api.brdz.link/api/bridge/status/sync?user_id=123" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get Bridge Mode

GET/api/bridge/mode

Get Bridge Mode

Return current Bridge environment mode (Sandbox or Production). Useful for determining which Bridge API environment is being used.

Response

200Bridge mode retrieved successfully

{
  "mode": "sandbox"
}

500Failed to fetch Bridge mode

{
  "error": "Failed to fetch Bridge mode"
}

200_productionProduction mode

{
  "mode": "production"
}

curl -X GET https://api.brdz.link/api/bridge/mode \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Bridge Integration Flow

Customer Onboarding Process

1. Create Customer: Call /bridge/customers with user_id
2. Monitor Status: Use /bridge/status to check verification progress
3. Sync Updates: Call /bridge/status/sync to refresh status from Bridge
4. Verify Capabilities: Check enabled capabilities for available features

Status Lifecycle

Status	Description	Next Steps
not_started	Customer created, verification not begun	User completes KYC process
pending_verification	Documents submitted, under review	Wait for Bridge review
verified	Customer approved, capabilities enabled	Full Bridge features available
rejected	Verification failed	Review rejection reasons

Capability Types

Capability	Description	Requirements
cap_send_funds	Send money to external accounts	Verified customer status
cap_receive_funds	Receive money from external sources	Verified customer status
cap_card_payments	Process card transactions	Additional business verification
cap_ach_transfers	ACH bank transfers	Bank account verification

Database Schema

bridge_customers Table

Based on controller implementation:

- bridge_customer_id (varchar) - Bridge API customer ID
- local_user_id (integer) - Internal user ID
- ekyc_status (varchar) - KYC status from Bridge
- signed_agreement_id (varchar) - Agreement reference
- created_at (timestamp)
- updated_at (timestamp)

Integration Services

buildBridgeCustomerPayload

Utility function that builds customer payload from user data:

• Extracts user information from database
• Formats data according to Bridge API requirements
• Handles document preparation and validation

BridgeStatusCheckerService

Service for synchronizing Bridge status:

• Fetches latest status from Bridge API
• Compares with local database records
• Updates local status and capabilities
• Tracks changes for audit trail

Environment Configuration

Sandbox Mode

• Purpose: Testing and development
• Data: Test customers and transactions only
• Limitations: No real money movement
• API Endpoint: Bridge Sandbox API

Production Mode

• Purpose: Live customer operations
• Data: Real customer and transaction data
• Compliance: Full regulatory compliance required
• API Endpoint: Bridge Production API

Error Handling

Common Errors

Error	Description	Solution
400: Missing user_id	Required parameter not provided	Include user_id in request
404: User not onboarded	User has no Bridge customer record	Call create customer first
500: Bridge API error	External Bridge service error	Check Bridge API status
500: Database error	Local database operation failed	Retry request

Bridge API Error Handling

try {
  const customer = await bridgeService.createCustomer(customerData);
} catch (error) {
  if (error.response?.data instanceof Buffer) {
    // Handle raw Bridge API errors
    console.error('Bridge API Error:', error.response.data.toString());
  } else {
    // Handle structured errors
    console.error('Error:', error.response?.data || error.message);
  }
}

Security Considerations

Data Protection

• Customer data encrypted in transit and at rest
• PII handling according to Bridge compliance requirements
• Secure API key management for Bridge integration

Access Control

• Admin authentication required for all endpoints
• User-specific data access controls
• Audit logging for all Bridge operations

Compliance

• Bridge handles regulatory compliance (KYC/AML)
• Customer verification according to financial regulations
• Transaction monitoring and reporting

---

Bridge Integration

Bridge handles the complex compliance and verification processes, allowing your application to focus on core business logic.

Sandbox Environment

When in sandbox mode, all operations use test data only. No real money movement occurs.

Status Synchronization

Use the sync endpoint regularly to keep local Bridge status up-to-date with the latest verification states.