Bridge Payments

Appearance

Organizations API ​

Bridge Payments supports organization-level payments, allowing businesses to manage payments, customers, and subscriptions at the organization level.

Organization Support Status ​

APIOrganization SupportStatus
Subscriptions✅ Full SupportComplete
Customers✅ Full SupportComplete
Addresses❌ Not SupportedPending
Payments❌ Not SupportedPending
Payment Methods❌ Not SupportedPending

How Organizations Work ​

Organization Context ​

When a user is authenticated, Bridge Payments automatically detects their organization from the Flowless session:

json
{
  "user": {
    "id": "user_123",
    "email": "user@company.com",
    "organizationId": "org_456789"
  }
}

Organization-Scoped Requests ​

You can explicitly specify an organization ID in requests:

bash
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "X-Session-ID: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_org_123",
    "organization_id": "org_456789",
    "total_cents": 49999,
    "currency": "USD",
    "billing_interval": "yearly",
    "payment_method_id": "pm_org_card"
  }'

Auto-Detection ​

If organization_id is not provided, Bridge Payments uses the user's organization from their session:

bash
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "X-Session-ID: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_org_123",
    "total_cents": 49999,
    "currency": "USD",
    "billing_interval": "yearly",
    "payment_method_id": "pm_org_card"
  }'

Subscriptions (Full Support) ​

Create Organization Subscription ​

bash
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "X-Session-ID: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_org_123",
    "organization_id": "org_456789",
    "total_cents": 49999,
    "currency": "USD",
    "billing_interval": "monthly",
    "payment_method_id": "pm_org_card",
    "concept": "Enterprise Plan"
  }'

Response:

json
{
  "success": true,
  "data": {
    "id": "sub_123",
    "customer_id": "cust_org_123",
    "organization_id": "org_456789",
    "user_id": null,
    "status": "active",
    "total_cents": 49999,
    "currency": "USD",
    "billing_interval": "monthly",
    "concept": "Enterprise Plan",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

List Organization Subscriptions ​

bash
curl -X GET "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "X-Session-ID: session_abc123"

Response:

json
{
  "success": true,
  "data": [
    {
      "id": "sub_123",
      "organization_id": "org_456789",
      "status": "active",
      "total_cents": 49999,
      "billing_interval": "monthly"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Customers (Full Support) ​

Create Organization Customer ​

bash
curl -X POST "https://your-instance.pubflow.com/bridge-payment/customers" \
  -H "X-Session-ID: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "stripe",
    "organization_id": "org_456789",
    "email": "billing@company.com",
    "name": "Company Inc",
    "phone": "+1234567890"
  }'

Response:

json
{
  "success": true,
  "data": {
    "id": "cust_123",
    "organization_id": "org_456789",
    "user_id": null,
    "provider_id": "stripe",
    "provider_customer_id": "cus_stripe_xyz",
    "email": "billing@company.com",
    "name": "Company Inc",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Access Control ​

Organization Access Logic ​

Users can access resources via:

  1. Personal Access: resource.user_id === user.id
  2. Organization Access: resource.organization_id === user.organizationId
typescript
const hasAccess = 
  subscription.user_id === userId || 
  (userOrgId && subscription.organization_id === userOrgId);

Example Access Control ​

bash
# User can access their own subscription
GET /bridge-payment/subscriptions/sub_personal_123

# User can access organization subscription
GET /bridge-payment/subscriptions/sub_org_456

# User CANNOT access other organization's subscription
GET /bridge-payment/subscriptions/sub_other_org_789  # 403 Forbidden

Guest Subscriptions for Organizations ​

Organizations can create guest subscriptions:

bash
curl -X POST "https://your-instance.pubflow.com/bridge-payment/subscriptions" \
  -H "X-Session-ID: session_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_guest_123",
    "organization_id": "org_456789",
    "total_cents": 2000,
    "currency": "USD",
    "billing_interval": "monthly",
    "payment_method_id": "pm_guest_card",
    "is_guest_subscription": true,
    "guest_data": {
      "email": "guest@example.com",
      "name": "Guest User"
    }
  }'

Limitations ​

Not Yet Supported ​

The following APIs do not currently support organizations:

  • Addresses - Cannot save organization addresses
  • Payments - Cannot create organization payments
  • Payment Methods - Cannot save organization payment methods

Workaround ​

Until organization support is added to these APIs, use personal user accounts for:

  • Saving addresses for organization payments
  • Creating payments on behalf of organizations
  • Managing payment methods for organization subscriptions

Next Steps ​