Bridge Payments Docs

Appearance

Organizations Guide ​

Organizations allow you to manage team-based billing, shared payment resources, and role-based access control for your payment operations. Perfect for businesses, teams, and multi-user scenarios.

Overview ​

With organizations, you can:

  • Create and manage business entities with multiple team members
  • Share payment resources (subscriptions, payment methods, addresses) across team members
  • Control access with role-based permissions (Owner, Admin, Billing, Member)
  • Track business information (tax ID, business email, phone, address)
  • Manage team members and their roles

How It Works ​

  1. Organization Creation: Any authenticated user can create an organization and becomes the owner
  2. Member Management: Owners and admins can invite team members with specific roles
  3. Resource Sharing: All payment resources can be associated with an organization
  4. Permission Control: Each role has specific permissions for managing resources
  5. Automatic Access: Members can access organization resources based on their role

Organization Roles ​

Owner ​

  • Full Control: Complete access to all organization features
  • Permissions:
    • ✅ Manage payments, subscriptions, payment methods, and addresses
    • ✅ Manage team members (invite, update roles, remove)
    • ✅ Update organization details
    • ✅ Delete organization
  • Limitations: Only one owner per organization (the creator)

Admin ​

  • Management Access: Full access except organization deletion
  • Permissions:
    • ✅ Manage payments, subscriptions, payment methods, and addresses
    • ✅ Manage team members (invite, update roles, remove)
    • ✅ Update organization details
    • ❌ Cannot delete organization
  • Use Case: Trusted team members who need full management capabilities

Billing ​

  • Financial Operations: Can manage all payment-related resources
  • Permissions:
    • ✅ Manage payments, subscriptions, payment methods, and addresses
    • ❌ Cannot manage team members
    • ❌ Cannot update organization details
    • ❌ Cannot delete organization
  • Use Case: Finance team members who handle billing operations

Member ​

  • Read-Only Access: Can view organization resources
  • Permissions:
    • ✅ View payments, subscriptions, payment methods, and addresses
    • ❌ Cannot create, update, or delete resources
    • ❌ Cannot manage team members
    • ❌ Cannot update organization details
  • Use Case: Team members who need visibility but not management access

Permission Matrix ​

PermissionOwnerAdminBillingMember
Manage Payments✅✅✅❌
Manage Subscriptions✅✅✅❌
Manage Payment Methods✅✅✅❌
Manage Addresses✅✅✅❌
Manage Members✅✅❌❌
Update Organization✅✅❌❌
Delete Organization✅❌❌❌

Getting Started ​

1. Create an Organization ​

Use the Create Organization endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Acme Corporation',
      business_email: '[email protected]',
      business_phone: '+1-555-0123',
      tax_id: '12-3456789',
      address: '123 Business St, Suite 100, San Francisco, CA 94105'
    })
  }
);

const { data } = await response.json();
console.log('Organization created:', data.id);

Response:

json
{
  "success": true,
  "data": {
    "id": "org_abc123xyz",
    "name": "Acme Corporation",
    "owner_user_id": "user_xyz789",
    "business_email": "[email protected]",
    "business_phone": "+1-555-0123",
    "tax_id": "12-3456789",
    "address": "123 Business St, Suite 100, San Francisco, CA 94105",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

2. List Your Organizations ​

Use the List Organizations endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations',
  {
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

const { data } = await response.json();
console.log('Your organizations:', data);

Response:

json
{
  "success": true,
  "data": [
    {
      "id": "org_abc123xyz",
      "name": "Acme Corporation",
      "role": "owner",
      "business_email": "[email protected]",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "org_def456uvw",
      "name": "Tech Startup Inc",
      "role": "admin",
      "business_email": "[email protected]",
      "created_at": "2024-02-20T14:15:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "page": 1,
      "pageSize": 20,
      "totalPages": 1
    }
  }
}

3. Invite Team Members ​

Use the Add Organization Member endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz/members',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: '[email protected]',
      role: 'billing'
    })
  }
);

const { data } = await response.json();
console.log('Member added:', data);

Response:

json
{
  "success": true,
  "data": {
    "id": "orguser_xyz123",
    "organization_id": "org_abc123xyz",
    "user_id": "user_john456",
    "role": "billing",
    "created_at": "2024-01-15T11:00:00Z"
  },
  "message": "Member added successfully"
}

Automatic Member Addition

If the user with the provided email exists in the system, they are automatically added to the organization. No email invitation is sent - the member is immediately active.

Owner-Only Permission

Only the organization owner can invite new members. Admins cannot invite members in the current implementation.

Managing Organization Resources ​

Create Organization Subscription ​

When creating resources, include the organization_id to associate them with your organization:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/subscriptions',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123xyz',  // ✅ Associate with organization
      customer_id: 'cust_abc123',
      total_cents: 49999,
      currency: 'USD',
      billing_interval: 'monthly',
      description: 'Team Plan Subscription'
    })
  }
);

Create Organization Payment Method ​

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/payment-methods',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123xyz',  // ✅ Associate with organization
      type: 'card',
      card_token: 'tok_visa_4242',
      is_default: true
    })
  }
);

Access Control ​

All organization members can access organization resources based on their role:

typescript
// Billing role member can create a payment
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/payments/intents',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'billing-member-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123xyz',  // ✅ Has permission
      total_cents: 10000,
      currency: 'USD',
      description: 'Invoice Payment'
    })
  }
);
// ✅ Success - Billing role can manage payments
typescript
// Member role trying to create a payment
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/payments/intents',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'member-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: 'org_abc123xyz',
      total_cents: 10000,
      currency: 'USD'
    })
  }
);
// ❌ 403 Forbidden - Member role cannot manage payments

Team Member Management ​

List Organization Members ​

Use the List Organization Members endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz/members',
  {
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

const { data } = await response.json();
console.log('Team members:', data);

Response:

json
{
  "success": true,
  "data": [
    {
      "id": "orguser_owner123",
      "user_id": "user_xyz789",
      "user_name": "Jane Smith",
      "user_email": "[email protected]",
      "role": "owner",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "orguser_billing456",
      "user_id": "user_john456",
      "user_name": "John Doe",
      "user_email": "[email protected]",
      "role": "billing",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "page": 1,
      "pageSize": 20,
      "totalPages": 1
    }
  }
}

Update Member Role ​

Use the Update Organization Member Role endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz/members/orguser_billing456',
  {
    method: 'PUT',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      role: 'admin'
    })
  }
);

const { data } = await response.json();
console.log('Member role updated:', data);

Role Update Restrictions

  • Cannot change the owner's role
  • Cannot change your own role
  • Only owner can update member roles

Remove Team Member ​

Use the Remove Organization Member endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz/members/orguser_billing456',
  {
    method: 'DELETE',
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

const { success, message } = await response.json();
console.log(message); // "Member removed successfully"

Removal Restrictions

  • Cannot remove the owner
  • Cannot remove yourself (use leave endpoint instead)
  • Only owner can remove members

Leave Organization ​

Use the Leave Organization endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz/leave',
  {
    method: 'POST',
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

const { success, message } = await response.json();
console.log(message); // "You have left the organization"

Owner Cannot Leave

The organization owner cannot leave the organization. To stop being the owner, you must either:

  • Delete the organization (if you want to remove it completely)
  • Transfer ownership to another member (future feature)

Organization Management ​

Update Organization Details ​

Use the Update Organization endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz',
  {
    method: 'PUT',
    headers: {
      'X-Session-ID': 'your-session-id',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Acme Corporation Ltd',
      business_email: '[email protected]',
      business_phone: '+1-555-0199',
      tax_id: '12-3456789',
      address: '456 New Office Blvd, San Francisco, CA 94105'
    })
  }
);

const { data } = await response.json();
console.log('Organization updated:', data);

Who Can Update

Only Owner and Admin roles can update organization details.

Delete Organization ​

Use the Delete Organization endpoint:

typescript
const response = await fetch(
  'https://your-instance.pubflow.com/bridge-payment/organizations/org_abc123xyz',
  {
    method: 'DELETE',
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

const { success, message } = await response.json();
console.log(message); // "Organization deleted successfully"

Owner-Only Operation

Only the organization owner can delete the organization. This action:

  • Removes all organization members
  • Removes all organization associations from resources
  • Cannot be undone

Best Practices ​

1. Organization Structure ​

Recommended Setup:

  • 1 Owner: The business owner or primary administrator
  • 1-2 Admins: Trusted team members who need full management access
  • 2-5 Billing: Finance team members who handle payments
  • Unlimited Members: Team members who need visibility

2. Role Assignment ​

Choose roles based on responsibility:

  • Owner: CEO, Founder, Business Owner
  • Admin: CTO, Operations Manager, Senior Team Lead
  • Billing: CFO, Finance Manager, Accountant
  • Member: Developers, Support Staff, Analysts

3. Security ​

Protect your organization:

  • ✅ Regularly review team members
  • ✅ Remove members who leave the company immediately
  • ✅ Use billing role for finance team (not admin)
  • ✅ Keep owner credentials secure
  • ❌ Don't share owner account credentials

4. Resource Organization ​

Keep resources organized:

  • ✅ Use organization_id for all team-related resources
  • ✅ Use personal resources (no organization_id) for individual purchases
  • ✅ Create separate organizations for different business entities
  • ✅ Use descriptive organization names

Common Use Cases ​

Multi-Team Company ​

typescript
// Create separate organizations for different teams
const engineering = await createOrganization({
  name: 'Acme - Engineering Team',
  business_email: '[email protected]'
});

const marketing = await createOrganization({
  name: 'Acme - Marketing Team',
  business_email: '[email protected]'
});

// Each team manages their own subscriptions and payments

Agency with Multiple Clients ​

typescript
// Create organization per client
const clientA = await createOrganization({
  name: 'Client A - Managed Services',
  business_email: '[email protected]',
  tax_id: 'client-a-tax-id'
});

// Invite client's finance team as billing members
await addMember(clientA.id, {
  email: '[email protected]',
  role: 'billing'
});

Startup with Growing Team ​

typescript
// Start with owner
const startup = await createOrganization({
  name: 'Tech Startup Inc',
  business_email: '[email protected]'
});

// Add CTO as admin
await addMember(startup.id, {
  email: '[email protected]',
  role: 'admin'
});

// Add finance manager as billing
await addMember(startup.id, {
  email: '[email protected]',
  role: 'billing'
});

// Add developers as members (read-only)
await addMember(startup.id, {
  email: '[email protected]',
  role: 'member'
});

Troubleshooting ​

"You don't have permission to perform this action" ​

Cause: Your role doesn't have the required permission.

Solution: Check the Permission Matrix and ask an owner or admin to:

  • Update your role to one with the required permission
  • Perform the action on your behalf

"User not found with email" ​

Cause: The email you're trying to invite doesn't exist in the system.

Solution: The user must create an account first before they can be added to an organization.

"User is already a member of this organization" ​

Cause: The user is already part of the organization.

Solution: Check the member list or update their existing role instead.

"Cannot remove organization owner" ​

Cause: Trying to remove the owner from the organization.

Solution: The owner cannot be removed. To change ownership:

  • Delete the organization (owner only)
  • Wait for ownership transfer feature (coming soon)

API Reference ​

For detailed API documentation, see:

Next Steps ​