Payment Provider Integration

secure.checkout.best features an extensible payment provider framework that allows multiple payment methods per store, with support for adding new providers.

Overview

The payment provider framework supports:

• Multiple payment methods per store - Merchants can enable Stripe, manual payments, and more
• Per-merchant credentials - Each store uses their own API keys
• Priority ordering - Control which payment method appears first
• Extensible architecture - New providers can be added without modifying existing code

Available Providers

API Endpoints

List Available Providers

Returns all registered payment providers with their capabilities and required credentials.

{
  "providers": [
    {
      "key": "stripe",
      "name": "Credit/Debit Card",
      "description": "Pay securely with your credit or debit card via Stripe",
      "capabilities": {
        "supports_redirect": false,
        "supports_webhook": true,
        "supports_refund": true,
        "requires_client_side": true,
        "supported_currencies": ["usd", "eur", "gbp", "cad", "aud"]
      },
      "required_credentials": [
        {"key": "publishable_key", "label": "Stripe Publishable Key", "required": true},
        {"key": "secret_key", "label": "Stripe Secret Key", "required": true, "encrypted": true}
      ]
    },
    {
      "key": "manual",
      "name": "Check / Money Order",
      "description": "Pay by check or money order mailed to the merchant",
      "capabilities": {
        "supports_redirect": false,
        "supports_webhook": false,
        "supports_refund": false,
        "requires_client_side": false,
        "supported_currencies": ["usd"]
      }
    }
  ]
}

Get Store Payment Options

Returns the enabled payment options for a specific store, ordered by priority.

{
  "payment_options": [
    {"key": "stripe", "name": "Credit/Debit Card", "description": "...", "priority": 0},
    {"key": "manual", "name": "Check / Money Order", "description": "...", "priority": 10}
  ]
}

Create Payment Intent

Initiates a payment for an order using the specified provider.

// Request
{
  "order_id": "uuid-of-order",
  "provider": "stripe"  // optional, defaults to "stripe"
}

// Response (Stripe)
{
  "provider": "stripe",
  "amount": 4000,
  "currency": "usd",
  "client_secret": "pi_xxx_secret_xxx",
  "payment_intent_id": "pi_xxx",
  "publishable_key": "pk_live_xxx"
}

// Response (Manual)
{
  "provider": "manual",
  "amount": 4000,
  "currency": "usd",
  "payment_instructions": "Make checks payable to..."
}

Provider Configuration

Payment providers are configured per-store via the Merchant Portal or Internal API.

Database Model

PaymentProviderConfig:
  - store_id: UUID (foreign key to stores)
  - provider_key: string ("stripe", "manual", etc.)
  - is_enabled: boolean
  - priority: integer (lower = shown first)
  - credentials_json: encrypted JSONB
  - settings_json: JSONB

Adding New Providers

New payment providers can be added by implementing the PaymentProvider interface:

from src.services.payment_providers import PaymentProvider, register_provider

@register_provider
class MyProvider(PaymentProvider):
    provider_key = "my_provider"
    display_name = "My Payment Method"
    description = "Description shown to customers"
    
    @classmethod
    def get_capabilities(cls):
        return ProviderCapabilities(
            supports_redirect=True,
            supports_webhook=True,
            supports_refund=False,
            supported_currencies=['usd']
        )
    
    @classmethod
    def get_required_credentials(cls):
        return [
            {"key": "api_key", "label": "API Key", "required": True, "encrypted": True}
        ]
    
    def initiate_payment(self, order_id, amount_cents, currency, ...):
        # Implement payment initiation
        return PaymentResult(success=True, status=PaymentStatus.PENDING, ...)
    
    def confirm_payment(self, order_id, external_reference, ...):
        # Implement payment confirmation
        return PaymentResult(success=True, status=PaymentStatus.SUCCEEDED, ...)

Once registered, the provider is automatically available via API endpoints and can be enabled for stores.

Roadmap

Provider	Status	Target
Stripe	Live	-
Manual Payment	Live	-
Coinbase Commerce	Planned	Q1 2025
BitPay	Planned	Q1 2025
PayPal	Considering	TBD

Related Documentation

• API Documentation
• Stripe Integration Guide