Provider architecture

Providers are independently published packages. The application chooses which ones to install and configures them explicitly:

import { esewa } from '@payments-sdk/esewa';
import { fonepay } from '@payments-sdk/fonepay';
import { createPayments } from '@payments-sdk/payments';

const payments = createPayments({
  providers: [
    esewa({ productCode, secretKey, environment: 'sandbox' }),
    fonepay({ merchantCode, secretKey, username, password }),
  ],
});

@payments-sdk/payments does not import, register, or maintain a list of providers. A future provider package can implement the core protocol without changing the runtime package.

Capabilities

Provider capabilities are optional and meaningful:

Capability	Purpose
`checkout`	Creates a redirect, form, or QR payment action.
`verify`	Queries the provider's authoritative payment state.
`returns`	Parses a browser return request.
`webhooks`	Parses a server-to-server event.
`refund`	Requests a refund when the provider supports it.
`cancel`	Cancels a payment when the provider supports it.

The initial provider packages expose these capabilities:

Provider	Checkout	Verify	Returns	Webhooks
eSewa	Form POST	Yes	Signed return	No
FonePay	QR payload	Yes	No	No
Khalti	Redirect	Yes	Informational return	No

Provider options and result data remain specific to each provider, while the runtime normalizes the common status and action shapes. This keeps the shared surface predictable without hiding gateway-specific details in providerData.

For provider authoring contracts, install @payments-sdk/core as a development dependency and use type-only imports. Provider code receives the runtime fetch and now context from the application runtime, which keeps it testable and avoids taking ownership of global infrastructure.

Capabilities

Provider-specific types

On this page