Integration Examples

Production-Ready REST API

Bridge Payments is a production-ready REST API currently in use across multiple applications. You integrate directly using standard HTTP clients like fetch, axios, or your preferred library.

Official client libraries are on the roadmap! Meanwhile, direct API integration is simple, flexible, and gives you complete control over your implementation.

Quick Start Integration

The following pages show battle-tested integration patterns used in production:

• React Native - Integration guide for React Native / Expo apps
• Next.js - Integration guide for Next.js applications
• React - Integration guide for React web applications

These examples demonstrate best practices for integrating Bridge Payments into your applications using direct API calls.

Why Direct API Integration?

Bridge Payments' REST API provides a clean, straightforward integration path:

• ✅ Production-Ready - Battle-tested in real-world applications
• ✅ Flexibility - Use any HTTP library you prefer (fetch, axios, ky, etc.)
• ✅ No Dependencies - No need to install additional packages
• ✅ Always Up-to-Date - Direct API access means no library version conflicts
• ✅ Framework Agnostic - Works with any JavaScript/TypeScript framework
• ✅ Full Control - Customize requests and responses to your needs

Community Client Libraries

Help Build the Ecosystem

We welcome community contributions for client libraries! Official support for popular frameworks is on our roadmap, but community libraries are encouraged and appreciated.

The following platforms would benefit from community-built client libraries:

Frontend Frameworks

• Vue.js - @bridge-payments/vue
• Angular - @bridge-payments/angular
• Svelte - @bridge-payments/svelte
• Solid.js - @bridge-payments/solid
• Qwik - @bridge-payments/qwik

Mobile Frameworks

• Flutter - bridge_payments_flutter
• Swift (iOS) - BridgePaymentsSwift
• Kotlin (Android) - bridge-payments-kotlin

Backend Languages

• Python - bridge-payments-python
• Go - bridge-payments-go
• Ruby - bridge-payments-ruby
• PHP - bridge-payments-php
• Java - bridge-payments-java
• C#/.NET - BridgePayments.NET
• Rust - bridge-payments-rust

Recommended Structure

Package Structure

@bridge-payments/{platform}/
|-- src/
|   |-- client/
|   |   |-- BridgePaymentClient.{ext}
|   |   +-- types.{ext}
|   |-- api/
|   |   |-- payments.{ext}
|   |   |-- payment-methods.{ext}
|   |   |-- customers.{ext}
|   |   |-- addresses.{ext}
|   |   +-- subscriptions.{ext}
|   |-- utils/
|   |   |-- auth.{ext}
|   |   |-- formatting.{ext}
|   |   +-- validation.{ext}
|   +-- index.{ext}
|-- tests/
|   |-- unit/
|   +-- integration/
|-- docs/
|   |-- README.md
|   |-- API.md
|   +-- EXAMPLES.md
|-- examples/
|-- .gitignore
|-- package.json (or equivalent)
|-- tsconfig.json (if TypeScript)
+-- README.md

Core Features

Every client library should implement:

1. Authentication Handling

// Example: TypeScript/JavaScript
class BridgePaymentClient {
  constructor(config: {
    baseUrl: string;
    sessionId?: string;
    token?: string;
  }) {
    this.baseUrl = config.baseUrl;
    this.sessionId = config.sessionId;
    this.token = config.token;
  }
  
  private getHeaders(): Record<string, string> {
    const headers: Record<string, string> = {
      'Content-Type': 'application/json'
    };
    
    if (this.sessionId) {
      headers['X-Session-ID'] = this.sessionId;
    } else if (this.token) {
      headers['Authorization'] = `Bearer ${this.token}`;
    }
    
    return headers;
  }
}

2. Payment Operations

// Create payment intent
async createPaymentIntent(data: CreatePaymentIntentRequest): Promise<PaymentIntent>

// Update payment intent
async updatePaymentIntent(id: string, data: UpdatePaymentIntentRequest): Promise<PaymentIntent>

// Confirm payment
async confirmPayment(id: string, paymentMethodId?: string): Promise<Payment>

// Sync payment status
async syncPaymentStatus(providerPaymentId: string): Promise<Payment>

// Get payment
async getPayment(id: string): Promise<Payment>

// List payments
async listPayments(): Promise<Payment[]>

// List guest payments
async listGuestPayments(email: string): Promise<Payment[]>

3. Payment Methods

// Create payment method
async createPaymentMethod(data: CreatePaymentMethodRequest): Promise<PaymentMethod>

// List payment methods
async listPaymentMethods(): Promise<PaymentMethod[]>

// Get payment method
async getPaymentMethod(id: string): Promise<PaymentMethod>

// Update payment method
async updatePaymentMethod(id: string, data: UpdatePaymentMethodRequest): Promise<PaymentMethod>

// Delete payment method
async deletePaymentMethod(id: string): Promise<void>

// Set default payment method
async setDefaultPaymentMethod(id: string): Promise<PaymentMethod>

4. Customers

// Create customer
async createCustomer(data: CreateCustomerRequest): Promise<Customer>

// Get customer
async getCustomer(id: string): Promise<Customer>

// Update customer
async updateCustomer(id: string, data: UpdateCustomerRequest): Promise<Customer>

// List customers
async listCustomers(): Promise<Customer[]>

5. Addresses

// Create address
async createAddress(data: CreateAddressRequest): Promise<Address>

// List addresses
async listAddresses(): Promise<Address[]>

// Update address
async updateAddress(id: string, data: UpdateAddressRequest): Promise<Address>

// Delete address
async deleteAddress(id: string): Promise<void>

6. Subscriptions

// Create subscription
async createSubscription(data: CreateSubscriptionRequest): Promise<Subscription>

// Get subscription
async getSubscription(id: string): Promise<Subscription>

// List subscriptions
async listSubscriptions(): Promise<Subscription[]>

// Update subscription
async updateSubscription(id: string, data: UpdateSubscriptionRequest): Promise<Subscription>

// Cancel subscription
async cancelSubscription(id: string): Promise<Subscription>

// Reactivate subscription
async reactivateSubscription(id: string): Promise<Subscription>

7. Error Handling

class BridgePaymentError extends Error {
  constructor(
    message: string,
    public statusCode?: number,
    public response?: any
  ) {
    super(message);
    this.name = 'BridgePaymentError';
  }
}

// Usage
try {
  const payment = await client.createPaymentIntent(data);
} catch (error) {
  if (error instanceof BridgePaymentError) {
    if (error.statusCode === 401) {
      // Handle authentication error
    } else if (error.statusCode === 400) {
      // Handle validation error
    }
  }
}

8. Type Definitions

Provide complete type definitions for all API requests and responses:

// Types
export interface PaymentIntent {
  id: string;
  provider_payment_id: string;
  client_secret: string;
  status: 'created' | 'processing' | 'succeeded' | 'failed';
  total_cents: number;
  currency: string;
  concept?: string;
  description?: string;
  created_at: string;
}

export interface CreatePaymentIntentRequest {
  subtotal_cents?: number;
  tax_cents?: number;
  discount_cents?: number;
  total_cents: number;
  currency: string;
  provider_id?: 'stripe' | 'paypal' | 'authorize_net';
  concept?: string;
  description?: string;
  setup_future_usage?: 'off_session';
  payment_method_id?: string;
  guest_data?: {
    email: string;
    name: string;
    phone?: string;
  };
}

Best Practices

1. Configuration

Support multiple configuration methods:

// Environment variables
const client = new BridgePaymentClient({
  baseUrl: process.env.BRIDGE_PAYMENTS_URL
});

// Direct configuration
const client = new BridgePaymentClient({
  baseUrl: 'https://your-instance.pubflow.com',
  sessionId: 'session_123'
});

2. Caching

Implement optional caching for performance:

const client = new BridgePaymentClient({
  baseUrl: 'https://your-instance.pubflow.com',
  cache: {
    enabled: true,
    ttl: 300000 // 5 minutes
  }
});

3. Retry Logic

Implement automatic retries for network errors:

const client = new BridgePaymentClient({
  baseUrl: 'https://your-instance.pubflow.com',
  retry: {
    enabled: true,
    maxRetries: 3,
    backoff: 'exponential'
  }
});

4. Logging

Support debug logging:

const client = new BridgePaymentClient({
  baseUrl: 'https://your-instance.pubflow.com',
  debug: true
});

5. TypeScript Support

Provide full TypeScript support even for JavaScript libraries:

// Include .d.ts files for type definitions
export * from './types';

Testing

Include comprehensive tests:

// Unit tests
describe('BridgePaymentClient', () => {
  it('should create payment intent', async () => {
    const client = new BridgePaymentClient({ baseUrl: 'https://test.com' });
    const intent = await client.createPaymentIntent({
      total_cents: 2000,
      currency: 'USD'
    });
    expect(intent.total_cents).toBe(2000);
  });
});

// Integration tests
describe('Integration Tests', () => {
  it('should complete full payment flow', async () => {
    // Test complete payment flow
  });
});

Documentation

Include comprehensive documentation:

• README.md: Installation, quick start, basic usage
• API.md: Complete API reference
• EXAMPLES.md: Code examples for common use cases
• CONTRIBUTING.md: Contribution guidelines

Publishing

NPM (JavaScript/TypeScript)

{
  "name": "@bridge-payments/vue",
  "version": "1.0.0",
  "description": "Vue.js client for Bridge Payments",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "keywords": ["bridge-payments", "pubflow", "payments", "vue"]
}

PyPI (Python)

setup(
    name='bridge-payments-python',
    version='1.0.0',
    description='Python client for Bridge Payments',
    keywords=['bridge-payments', 'pubflow', 'payments']
)

Submit Your Library

Once your library is ready:

1. Test thoroughly with real Bridge Payments instance
2. Document all features and usage examples
3. Publish to appropriate package registry
4. Submit to community showcase:
   • Create PR to add your library to this page
   • Include: name, description, installation, basic example
   • Link to repository and documentation

Community Showcase

Submit your library to be featured here! Create a pull request with:

• Library name and description
• Installation instructions
• Basic usage example
• Links to repository and documentation

---

Questions? Join our community discussions or open an issue on GitHub.