Bridge Payments

Appearance

Core Concepts ​

Understanding these core concepts will help you build robust payment integrations with Bridge Payments.

Payment Intents ​

A Payment Intent represents a single payment transaction. It tracks the payment through its entire lifecycle from creation to completion.

Payment Intent Lifecycle ​

created → processing → succeeded
                    ↓
                  failed

Key Properties ​

  • client_secret: Used by frontend to confirm payment (sensitive, auto-deleted after 24h)
  • status: Current payment state (created, processing, succeeded, failed)
  • amount_cents: Total amount in cents (e.g., 2000 = $20.00)
  • provider_id: Payment provider (stripe, paypal, authorize_net)
  • provider_payment_id: Provider's payment ID for tracking

Payment Flow ​

  1. Create Intent: Backend creates payment intent with amount and details
  2. Confirm Payment: Frontend uses client_secret to collect payment info
  3. Process: Provider processes the payment
  4. Sync Status: Backend syncs final status from provider
  5. Complete: Payment marked as succeeded or failed

Best Practice

Always sync payment status after frontend confirmation to ensure your database reflects the actual payment state.

Payment Methods ​

A Payment Method represents a saved payment instrument (credit card, bank account, etc.) that can be reused for future payments.

typescript
{
  "provider_id": "stripe",
  "provider_payment_method_token": "pm_1234567890",
  "type": "card",
  "card_brand": "visa",
  "card_last_four": "4242"
}

Benefits:

  • ✅ PCI compliant (no raw card data)
  • ✅ Secure tokenization by provider
  • ✅ Recommended for production

Direct Card Data (Development Only) ​

typescript
{
  "provider_id": "stripe",
  "card_number": "4242424242424242",
  "card_exp_month": "12",
  "card_exp_year": "2025",
  "card_cvc": "123"
}

Warning:

  • ⚠️ Requires PCI compliance
  • ⚠️ Only for development/testing
  • ⚠️ Use tokenization in production

Saving Payment Methods ​

Set setup_future_usage: "off_session" when creating payment intent:

typescript
{
  "total_cents": 2000,
  "currency": "USD",
  "setup_future_usage": "off_session", // Save for future use
  "provider_id": "stripe"
}

Customers ​

A Customer represents a person or organization that makes payments.

Customer Types ​

1. Authenticated Users ​

Linked to Flowless user accounts:

typescript
{
  "user_id": "user_123",
  "email": "john@example.com",
  "name": "John Doe",
  "is_guest": false
}

2. Guest Customers ​

No account required:

typescript
{
  "guest_data": {
    "email": "guest@example.com",
    "name": "Guest User",
    "phone": "+1234567890"
  }
}

3. Organization Customers ​

For business accounts:

typescript
{
  "organization_id": "org_456",
  "email": "billing@company.com",
  "name": "Company Inc"
}

Subscriptions ​

A Subscription represents recurring payments at regular intervals.

Subscription States ​

  • active: Currently active, billing normally
  • trialing: In trial period, no charges yet
  • past_due: Payment failed, retrying
  • canceled: Subscription ended
  • paused: Temporarily suspended

Billing Intervals ​

  • daily - Every day
  • weekly - Every week
  • monthly - Every month
  • quarterly - Every 3 months
  • yearly - Every year

Trial Periods ​

typescript
{
  "product_id": "prod_premium",
  "payment_method_id": "pm_123",
  "trial_days": 14 // 14-day free trial
}

Webhooks ​

Webhooks notify your application about payment events in real-time.

Provider Webhooks ​

Receive events from payment providers (Stripe, PayPal):

Stripe → Bridge Payments → Database Update

Common Events:

  • payment_intent.succeeded - Payment completed
  • payment_intent.payment_failed - Payment failed
  • customer.subscription.created - New subscription
  • invoice.payment_failed - Subscription payment failed

External Webhooks ​

Send events to your own services:

Bridge Payments → Your API / Discord / Slack

Use Cases:

  • Send Discord notifications for failed payments
  • Update analytics platforms
  • Trigger custom business logic
  • Send Slack alerts for new subscriptions

Authentication ​

Bridge Payments supports multiple authentication methods:

1. Session ID (Recommended) ​

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

2. Bearer Token ​

typescript
headers: {
  'Authorization': 'Bearer token_xyz789'
}

3. Guest Token ​

For guest checkout:

typescript
{
  "guest_data": {
    "email": "guest@example.com",
    "name": "Guest User"
  }
}

Response Formats ​

Standard Format (Default) ​

json
{
  "id": "pay_123",
  "amount_cents": 2000,
  "status": "succeeded"
}

Row Mode ​

Set ROW_MODE=true in environment:

json
{
  "pay_123": {
    "amount_cents": 2000,
    "status": "succeeded"
  }
}

Next Steps ​