Payment providers in FinConnect

Understand how FinConnect abstracts PesaPal ,ClickPesa and Azampay behind one interface, and learn what config each provider requires and how provider selection works.

FinConnect uses a provider model where each supported payment platform (PesaPal, ClickPesa,Azampay) is wrapped in a provider class that implements a common interface. You pick a provider at initialization and the SDK handles the rest — authentication, request formatting, and response parsing all happen under the hood.

How providers work

FinConnect exposes a ProviderType enum-like values for each supported provider. When you construct a FintechSDK instance, it passes your chosen provider type and config to ProviderFactory.createProvider(), which validates your config and returns the appropriate provider instance. FintechSDK stores this internally as gateway and delegates all method calls to it.

export const ProviderType = {
  clickpesa: 'clickpesa',
  pesapal: 'pesapal',
  azampay: 'azampay',
} as const;

export type ProviderType = typeof ProviderType[keyof typeof ProviderType];

ProviderFactory.createProvider() validates that all required config fields are present before instantiating a provider. If you pass an unrecognized provider string, it throws:

Unsupported provider type: <your value>

Provider comparison

Provider	Auth mechanism	Push payment	IPN support	Region
PesaPal	OAuth2 (Bearer token)	USSD push	Yes	East Africa
ClickPesa	JWT	USSD push	No (throws error)	East Africa
AzamPay	JWT	USSD push	No(throws error)	Tanzania

registerIpn() on ClickPesa (and any provider that does not override the base implementation) throws "IPN registration not supported by this provider".

Selecting a provider

Pass a ProviderType value and the matching config object to FintechSDK:

import { FintechSDK } from 'finconnect';

// Use PesaPal
const pesapalSDK = new FintechSDK({
  provider: 'pesapal',
  config: { /* PesaPal config */ }
});

// Use ClickPesa
const clickpesaSDK = new FintechSDK({
  provider: 'clickpesa',
  config: { /* ClickPesa config */ }
});

// Use Azampay
const azampaySDK = new FintechSDK({
  provider: 'azampay',
  config: { /* Azampay config */ }
});

Required config fields

Each provider validates its own required fields at construction time and throws if any are missing.

PesaPal

Field	Description
baseUrl	Base URL for the PesaPal API (sandbox or production)
PESAPAL_CONSUMER_KEY	Your PesaPal consumer key
PESAPAL_CONSUMER_SECRET	Your PesaPal consumer secret

const sdk = new FintechSDK({
  provider: 'pesapal',
  config: {
    baseUrl: 'https://cybqa.pesapal.com/pesapalv3',
    PESAPAL_CONSUMER_KEY: process.env.PESAPAL_CONSUMER_KEY!,
    PESAPAL_CONSUMER_SECRET: process.env.PESAPAL_CONSUMER_SECRET!,
  }
});

ClickPesa

Field	Description
baseUrl	Base URL for the ClickPesa API
CLICKPESA_CLIENT_ID	Your ClickPesa client ID
CLICKPESA_API_KEY	Your ClickPesa API key

const sdk = new FintechSDK({
  provider: 'clickpesa',
  config: {
    baseUrl: 'https://api.clickpesa.com',
    CLICKPESA_CLIENT_ID: process.env.CLICKPESA_CLIENT_ID!,
    CLICKPESA_API_KEY: process.env.CLICKPESA_API_KEY!,
  }
});

AzamPay

Field	Description
baseUrl	Base URL for the azampay API
AZAMPAY_APPNAME	Your Azamapay appName
AZAMPAY_CONSUMER_KEY	Your Azampay clientId
AZAMPAY_CONSUMER_SECRET	Your Azamapay clientSecret

const sdk = new FintechSDK({
  provider: 'azampay',
  config: {
    baseUrl: process.env.AZAMPAY_BASE_URL,
    AZAMPAY_APP_NAME: process.env.AZAMPAY_APP_NAME,
    AZAMPAY_CONSUMER_KEY: process.env.AZAMPAY_CLIENT_ID,
    AZAMPAY_CONSUMER_SECRET: process.env.AZAMPAY_API_KEY
  }
});