Bridge Payments

Appearance

Pubflow Integration ​

Bridge Payments seamlessly integrates with the Pubflow ecosystem, particularly with Flowless for authentication and session management.

Overview ​

Bridge Payments validates user sessions with your Flowless instance to ensure secure payment processing. This integration allows:

  • Automatic user authentication
  • Session validation
  • User context in payment records
  • Organization/multi-tenant support
  • Secure guest checkout

Architecture ​

┌─────────────────┐         ┌──────────────────┐
│  Your Frontend  │────────▶│  Bridge Payments │
│  (React/Next)   │         │    Instance      │
└─────────────────┘         └────────┬─────────┘
                                     │
                                     │ Validate Session
                                     │
                            ┌────────▼─────────┐
                            │    Flowless      │
                            │    Instance      │
                            └──────────────────┘

Configuration ​

1. Get Flowless Instance URL ​

Your Flowless instance URL is available in the Pubflow dashboard:

https://your-flowless.pubflow.com

2. Generate Shared Secret ​

The BRIDGE_VALIDATION_SECRET is a shared secret between Bridge Payments and Flowless.

In Flowless Configuration:

bash
BRIDGE_VALIDATION_SECRET=your_shared_secret_here

In Bridge Payments Configuration:

bash
BRIDGE_VALIDATION_SECRET=your_shared_secret_here

Important

The secret must be identical in both instances. Use a strong, random string (minimum 32 characters).

3. Configure Bridge Payments ​

In your Bridge Payments instance configuration (Pubflow dashboard):

bash
# Flowless API URL (required)
FLOWLESS_API_URL=https://your-flowless.pubflow.com

# Bridge validation secret (required)
BRIDGE_VALIDATION_SECRET=your_shared_secret_here

# Authentication timeout (optional, default: 30000ms)
AUTH_TIMEOUT=30000

# Request timeout (optional, default: 60000ms)
REQUEST_TIMEOUT=60000

Session Validation Flow ​

1. Client Sends Request ​

typescript
const response = await fetch(
  'https://your-bridge.pubflow.com/bridge-payment/payments/intents',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Session-ID': sessionId // From Flowless authentication
    },
    body: JSON.stringify({
      total_cents: 2000,
      currency: 'USD'
    })
  }
);

2. Bridge Payments Validates Session ​

1. Extract session_id from X-Session-ID header
2. Call Flowless API: POST /bridge/validate
3. Flowless validates session and returns user data
4. Bridge Payments caches validation result
5. Request proceeds with user context

3. Flowless Returns User Data ​

json
{
  "valid": true,
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "name": "John Doe",
    "organization_id": "org_456"
  }
}

Authentication Methods ​

typescript
headers: {
  'X-Session-ID': sessionId
}

Pros:

  • Clean separation of concerns
  • Standard HTTP header
  • Easy to implement

Method 2: Authorization Bearer Token ​

typescript
headers: {
  'Authorization': `Bearer ${token}`
}

Pros:

  • Standard OAuth 2.0 pattern
  • Compatible with API gateways

Method 3: Query Parameter ​

typescript
const url = `${baseUrl}/payments/intents?session_id=${sessionId}`;

Pros:

  • Simple for testing
  • Works with GET requests

Cons:

  • Less secure (visible in logs)
  • Not recommended for production

Guest Checkout ​

Guest checkout bypasses Flowless authentication:

typescript
const response = await fetch(
  'https://your-bridge.pubflow.com/bridge-payment/payments/intents',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
      // No authentication header
    },
    body: JSON.stringify({
      total_cents: 2000,
      currency: 'USD',
      guest_data: {
        email: '[email protected]',
        name: 'Guest User'
      }
    })
  }
);

Organization Support ​

Bridge Payments supports multi-tenant organizations:

Automatic Organization Detection ​

When a user belongs to an organization, Bridge Payments automatically links payments:

typescript
// User session includes organization_id
{
  "user_id": "user_123",
  "organization_id": "org_456"
}

// Payment automatically linked to organization
{
  "id": "pay_789",
  "user_id": "user_123",
  "organization_id": "org_456"
}

Override Organization ​

You can override the organization for specific payments:

typescript
const response = await fetch(
  'https://your-bridge.pubflow.com/bridge-payment/payments/intents',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': sessionId
    },
    body: JSON.stringify({
      total_cents: 2000,
      currency: 'USD',
      organization_id: 'org_different' // Override
    })
  }
);

Caching ​

Bridge Payments caches session validations for performance:

  • Cache TTL: 5 minutes (default)
  • Cache Key: session_${session_id}
  • Cache Invalidation: Automatic after TTL

Benefits:

  • Reduced Flowless API calls
  • Faster response times
  • Lower latency

Error Handling ​

Invalid Session ​

json
{
  "error": "Invalid session_id",
  "status": 401
}

Client Action:

  • Redirect to login
  • Refresh session token
  • Clear local storage

Flowless Unreachable ​

json
{
  "error": "Authentication service unavailable",
  "status": 503
}

Client Action:

  • Retry request
  • Show error message
  • Use fallback authentication

Expired Session ​

json
{
  "error": "Session expired",
  "status": 401
}

Client Action:

  • Refresh session token
  • Redirect to login

Testing ​

Test Session Validation ​

bash
# Test with valid session
curl -X POST "https://your-bridge.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your_session_id" \
  -d '{
    "total_cents": 2000,
    "currency": "USD"
  }'

# Test with invalid session
curl -X POST "https://your-bridge.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: invalid_session" \
  -d '{
    "total_cents": 2000,
    "currency": "USD"
  }'

Best Practices ​

1. Use X-Session-ID Header ​

Prefer X-Session-ID header over query parameters for security.

2. Handle Session Expiration ​

Implement automatic session refresh or redirect to login.

3. Cache Session Tokens ​

Cache session tokens in secure storage (HttpOnly cookies, AsyncStorage).

4. Validate on Frontend ​

Check session validity before making payment requests.

5. Monitor Authentication Errors ​

Track 401 errors to identify authentication issues.

Troubleshooting ​

"Invalid session_id" ​

Cause: Session not found in Flowless or expired

Solution:

  • Verify session_id is correct
  • Check session hasn't expired
  • Ensure user is logged in

"BRIDGE_VALIDATION_SECRET mismatch" ​

Cause: Secrets don't match between Bridge Payments and Flowless

Solution:

  • Verify secrets are identical
  • Check for extra spaces or characters
  • Update both instances

"Flowless API unreachable" ​

Cause: Network issue or Flowless instance down

Solution:

  • Check Flowless instance status
  • Verify FLOWLESS_API_URL is correct
  • Check network connectivity

Next Steps ​