Payment Providers

Openfront uses a two-tier system for processing payments: Payment Provider Platforms (templates) and Payment Providers (instances). Understanding this distinction is crucial for setting up your payment integrations correctly.

Payment Provider Platforms vs Payment Providers

Payment Provider Platforms (Templates)

A Payment Provider Platform is a reusable template that defines how Openfront integrates with a specific payment gateway. Think of it as a blueprint or configuration preset.

What Payment Provider Platforms contain:

Integration function mappings (which code to run for different operations)
API credentials configuration structure
Webhook handling templates
Regional availability settings

Examples of Payment Provider Platforms:

Stripe Platform - Template for all Stripe integrations
PayPal Platform - Template for all PayPal integrations
Manual Platform - Template for offline payment methods
Custom Platform - Template with HTTP endpoints for custom integrations

Payment Providers (Instances)

A Payment Provider is an actual connection to a specific payment gateway account. It uses a Payment Provider Platform template but contains the unique credentials and settings for that particular account.

What Payment Providers contain:

Reference to which Payment Provider Platform to use
Account-specific credentials (API keys, merchant IDs)
Provider name and configuration
Regional and currency settings

How Payment Works

Create Payment Provider (Template)

First, you create a Payment Provider that defines the integration method:

Payment Provider: "Stripe Provider"
├── createPaymentFunction: "stripe"
├── capturePaymentFunction: "stripe" 
├── refundPaymentFunction: "stripe"
├── getPaymentStatusFunction: "stripe"
├── generatePaymentLinkFunction: "stripe"
└── handleWebhookFunction: "stripe"

All function values point to the built-in Stripe integration (/integrations/payment/stripe.ts).

Configure Regional Availability

Payment providers are assigned to regions where they should be available:

Stripe Provider
├── Regions: [North America, Europe]
├── Credentials: { publishableKey, secretKey }
└── Webhook Secret: whsec_...

PayPal Provider  
├── Regions: [Global]
├── Credentials: { clientId, clientSecret }
└── Webhook ID: 8JR59343...

Payment Session Creation

When customers reach checkout, Openfront creates payment sessions for all available providers:

Customer starts checkout in North America region
System finds providers → Stripe, PayPal (both available in NA)
Creates payment sessions for each provider
Customer selects preferred payment method
Initiates payment using selected provider

Function Execution

When Openfront needs to create a payment:

Lookup: Find provider's functions → "Stripe Provider"
Check function: createPaymentFunction = "stripe"
Import: Load /integrations/payment/stripe.ts
Execute: Call createPaymentFunction() with cart data
Connect: Make API calls to Stripe using provider's credentials

Supported Payment Provider Platforms

Openfront comes with built-in platform presets for popular payment gateways:

Stripe

Full integration with Stripe payment processing

Credit/debit card payments
Payment intents and confirmations
Automatic capture or manual authorization
Webhooks for real-time status updates
Refunds and partial refunds

PayPal

Complete PayPal integration featuring:

PayPal checkout experience
PayPal account payments
Order authorization and capture
Webhook verification
Refund processing

Manual Payments

Simple manual payment tracking for:

Cash payments
Bank transfers
Check payments
Other offline payment methods

Custom HTTP Platforms

For integrating with other payment gateways through HTTP endpoints.

Custom Payment Providers

Option 1: File-based Integration

Create a new adapter file in /features/integrations/payment/:

// /features/integrations/payment/custom-gateway.ts

export async function createPaymentFunction({ cart, amount, currency, provider }) {
  // Your custom payment creation logic
  const paymentIntent = await yourGateway.createPayment({
    amount,
    currency,
    credentials: provider.credentials
  });
  
  return {
    sessionData: paymentIntent,
    paymentId: paymentIntent.id
  };
}

export async function capturePaymentFunction({ paymentId, amount, provider }) {
  // Capture payment logic
  return await yourGateway.capturePayment(paymentId, amount);
}

// Implement other required functions...

Option 2: HTTP Endpoint Integration

Configure your provider to use HTTP endpoints:

Payment Provider: "My Custom Gateway"
├── createPaymentFunction: "https://my-gateway.com/api/create-payment"
├── capturePaymentFunction: "https://my-gateway.com/api/capture-payment"
├── refundPaymentFunction: "https://my-gateway.com/api/refund-payment"
├── getPaymentStatusFunction: "https://my-gateway.com/api/payment-status"
├── generatePaymentLinkFunction: "https://my-gateway.com/api/payment-link"
└── handleWebhookFunction: "https://my-gateway.com/api/webhook"

Your endpoints receive standardized payloads:

{
  "provider": {
    "name": "My Custom Gateway",
    "credentials": { "apiKey": "...", "merchantId": "..." }
  },
  "cart": { "id": "cart_123", "total": 5000, "currency": "USD" },
  "amount": 5000,
  "currency": "USD"
}

Required Functions Interface

Every payment provider must implement these functions:

createPaymentFunction

Creates a payment session/intent for the given cart.

async function createPaymentFunction({ cart, amount, currency, provider }) {
  // Return: { sessionData, paymentId }
}

capturePaymentFunction

Captures an authorized payment.

async function capturePaymentFunction({ paymentId, amount, provider }) {
  // Return: { success: boolean, transactionId?: string }
}

refundPaymentFunction

Processes refunds for captured payments.

async function refundPaymentFunction({ paymentId, amount, provider }) {
  // Return: { success: boolean, refundId?: string }
}

getPaymentStatusFunction

Checks the current status of a payment.

async function getPaymentStatusFunction({ paymentId, provider }) {
  // Return: { status: 'pending' | 'authorized' | 'captured' | 'failed' }
}

generatePaymentLinkFunction

Generates management/dashboard links for payments.

async function generatePaymentLinkFunction({ paymentId, provider }) {
  // Return: { url: string }
}

handleWebhookFunction

Processes webhooks from the payment provider.

async function handleWebhookFunction({ event, headers, provider }) {
  // Return: { verified: boolean, eventType?: string, paymentId?: string }
}

Regional Configuration

Payment providers are region-specific, allowing different payment methods for different markets:

Providers are assigned to one or more regions
Checkout only shows providers available in the cart's region
Supports multi-currency and geo-specific payment requirements
Enables compliance with local payment regulations

Webhook Handling

Openfront provides centralized webhook processing:

Webhook endpoint: /api/webhooks/payment/[providerId]
Signature verification: Using provider's webhook handling function
Event processing: Automatic payment status updates
Order updates: Status changes trigger order processing

Getting Started

For Built-in Platform Presets

Create a payment provider platform using Stripe, PayPal, or Manual preset
Configure API credentials in platform settings
Create payment provider instances for each account
Assign to regions where the provider should be available
Test payments in development mode

For Custom Payment Provider Platforms

Create a custom payment provider platform following our guides
Implement required payment functions for your gateway
Set up webhook endpoints for real-time updates
Test integration thoroughly before going live

For HTTP-based Integrations

Deploy HTTP endpoints matching Openfront's interface
Create payment provider platform with endpoint URLs
Implement webhook signature verification
Test with Openfront's standardized payloads

How-to Guides

Ready to set up your payment integrations? Follow these step-by-step guides:

Create Custom Payment Provider - Build your own payment gateway integration
Create Payment Integration - Connect to existing payment platforms

The payment provider system gives you complete flexibility to integrate any payment gateway while maintaining a consistent checkout experience for your customers.

openfront