Getting Started

This guide will help you create your first payment with Bridge Payments in under 10 minutes.

Prerequisites

Before you begin, you'll need:

1. Pubflow Account: Sign up at pubflow.com
2. Flowless Instance: Your authentication backend (created from Pubflow dashboard)
3. Bridge Payments Instance: Your payment backend (created from Pubflow dashboard)

Step 1: Create Bridge Payments Instance

1. Log in to Pubflow Platform
2. Navigate to Instances → Create New Instance
3. Select Bridge Payments
4. Choose your deployment region
5. Click Create Instance

Your instance will be deployed automatically and you'll receive your instance URL:

https://your-instance.pubflow.com

Step 2: Configure Payment Provider

Enable Stripe

1. Go to your Bridge Payments instance in Pubflow dashboard
2. Navigate to Configuration → Environment Variables
3. Add your Stripe credentials:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

4. Click Save Configuration

Get Stripe Keys

Get your API keys from Stripe Dashboard

Step 3: Connect to Flowless

Bridge Payments validates user sessions with your Flowless instance:

1. In Pubflow dashboard, go to Bridge Payments → Configuration
2. Add Flowless integration:

FLOWLESS_API_URL=https://your-flowless.pubflow.com
BRIDGE_VALIDATION_SECRET=your_shared_secret

Shared Secret

The BRIDGE_VALIDATION_SECRET must match the secret configured in your Flowless instance.

Step 4: Your First Payment

Option A: Using React Native

Install the client library:

npm install @pubflow/react-native

Create a payment:

import { BridgePaymentClient } from '@pubflow/react-native';

// Initialize client
const client = new BridgePaymentClient({
  baseUrl: 'https://your-instance.pubflow.com',
  sessionId: userSession.id // From Flowless authentication
});

// Create payment intent
const intent = await client.createPaymentIntent({
  subtotal_cents: 1800,
  tax_cents: 200,
  total_cents: 2000,
  currency: 'USD',
  concept: 'Premium Subscription',
  provider_id: 'stripe'
});

// Use client_secret with Stripe Elements
const { client_secret } = intent;

Option B: Using Next.js

// app/api/create-payment/route.ts
export async function POST(request: Request) {
  const { amount } = await request.json();
  
  const response = await fetch(
    'https://your-instance.pubflow.com/bridge-payment/payments/intents',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Session-ID': sessionId // From cookies or headers
      },
      body: JSON.stringify({
        subtotal_cents: amount - 200,
        tax_cents: 200,
        total_cents: amount,
        currency: 'USD',
        concept: 'Product Purchase',
        provider_id: 'stripe'
      })
    }
  );
  
  return response.json();
}

Option C: Direct API Call

# Using X-Session-ID header (recommended)
curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your_session_id" \
  -d '{
    "subtotal_cents": 1800,
    "tax_cents": 200,
    "total_cents": 2000,
    "currency": "USD",
    "concept": "Premium Subscription",
    "provider_id": "stripe"
  }'

# Or using query parameter
curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents?session_id=your_session_id" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal_cents": 1800,
    "tax_cents": 200,
    "total_cents": 2000,
    "currency": "USD",
    "concept": "Premium Subscription",
    "provider_id": "stripe"
  }'

Step 5: Confirm Payment (Frontend)

Use Stripe Elements to collect payment information and confirm:

import { useStripe, useElements, CardElement } from '@stripe/react-stripe-js';

function CheckoutForm({ clientSecret }) {
  const stripe = useStripe();
  const elements = useElements();
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: `${window.location.origin}/success`
      }
    });
    
    if (error) {
      console.error(error.message);
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <CardElement />
      <button type="submit" disabled={!stripe}>
        Pay Now
      </button>
    </form>
  );
}

Step 6: Handle Payment Result

After Stripe redirects back to your app, sync the payment status:

// On return_url page
const paymentIntentId = new URLSearchParams(window.location.search).get('payment_intent');

const response = await fetch(
  `https://your-instance.pubflow.com/bridge-payment/payments/sync/${paymentIntentId}`,
  {
    method: 'POST',
    headers: {
      'X-Session-ID': sessionId
    }
  }
);

const payment = await response.json();

if (payment.status === 'succeeded') {
  // Payment successful!
  console.log('Payment completed:', payment);
}

🎉 Success!

You've successfully created your first payment with Bridge Payments!

Next Steps

• Core Concepts - Understand payment intents, methods, and customers
• Guest Checkout - Accept payments without authentication
• Payment Methods API - Manage saved payment methods
• Subscriptions API - Set up recurring billing
• API Reference - Explore all available endpoints

Common Issues

"Invalid session_id"

Make sure you're passing a valid session ID from Flowless authentication.

"Provider not configured"

Check that your payment provider credentials are correctly set in the Pubflow dashboard.

"CORS error"

Add your frontend domain to the allowed origins in Bridge Payments configuration.