Providers & accounts

Owostack is designed to work with multiple payment providers through a single interface. This page explains the abstraction layer and how provider differences are handled.

Supported providers

Different payment providers serve different markets and have different strengths. Paystack dominates in Nigeria and West Africa. Stripe is the global standard for online payments. Dodo Payments and Polar handle global billing flows. Owostack abstracts the differences so your application code stays the same regardless of which provider you choose.

Your app calls attach(), check(), and track(). Owostack figures out which provider to use, translates the request into the provider's API format, and normalizes the webhooks back into a common event model.

The adapter model

Each supported provider has an adapter — an implementation of a shared interface that handles:

• Checkout sessions — creating a payment page for the customer
• Subscriptions — creating, fetching, and canceling recurring billing
• Webhook verification — validating that incoming events are genuine
• Event normalization — translating provider-specific events into Owostack's internal format
• Refunds — reversing charges (e.g. for card setup verification)
• Products/plans — creating the provider-side representation of your plans

The adapter interface is designed so that core billing logic (plan switching, trial management, overage billing) works identically across providers. Provider-specific quirks are isolated inside the adapter.

Currently Supported providers

Provider accounts

A provider account stores the credentials for a specific provider within your organization:

• Secret key — the provider's API key (encrypted at rest)
• Webhook secret — used to verify incoming webhook payloads
• Environment — test or live

Each organization can configure one or more provider accounts for different environments (test or live).

How providers are selected

When a customer starts a checkout, Owostack picks a provider using this priority:

1. Explicit provider parameter — if you pass provider: "dodopayments" to attach()
2. Plan's provider — the provider selected when the plan was created
3. Customer's existing provider — if they've paid before, use the same provider
4. Fallback — the first configured provider account

Owostack routes requests based on the plan's provider, explicit provider parameter, or customer history.

Provider-specific behavior

Some billing features work differently depending on the provider:

Trials:

• Paystack — small verification charge (auto-refunded), Owostack manages trial billing
• Stripe — native trial support via Stripe Billing subscription schedules
• Dodo — native trial period, provider defers first charge automatically
• Polar — native trial support via provider-side subscription lifecycle

Card on file:

• Paystack — stores a reusable authorization code from the first charge
• Stripe — stores customer payment methods; supports off-session payments with SetupIntents
• Dodo — creates an on-demand subscription that can be charged with arbitrary amounts
• Polar — stores provider-managed subscription IDs for recurring lifecycle events

Checkout:

• Paystack — raw amount checkout, no pre-created product needed
• Stripe — flexible checkout with PaymentIntents; supports one-time and subscription payments
• Dodo — product-centric, requires a synced product ID for every checkout
• Polar — product-centric checkout with support for single- or multi-product sessions

Plan upgrades:

• Paystack — no native plan change API. Owostack uses a one-time prorated checkout when an immediate difference is due, then keeps recurring renewal aligned to the next full cycle. If the remaining difference is 0 or below Paystack's transaction minimum, Owostack switches immediately without charging the tiny remainder.
• Stripe — native subscription updates. Owostack applies upgrades with immediate invoicing so proration is billed now instead of being left on a later invoice.
• Dodo — native change-plan flow with provider-managed proration. If Dodo rejects the change, Owostack fails the upgrade instead of falling back to an invalid raw-amount checkout.
• Polar — native subscription updates. Owostack uses the provider's immediate invoice mode for paid upgrades.

These differences are handled internally. Your application code is the same regardless of provider.

Adding a new provider

Owostack's adapter interface is designed to be extended. At a high level:

1. Implement ProviderAdapter in packages/adapters
2. Register it in the provider registry
3. Add credential fields to the dashboard
4. Configure a provider account

Once registered, all billing flows (checkout, plan switching, webhooks, overage billing) work through the new adapter automatically.