> ## Documentation Index
> Fetch the complete documentation index at: https://finconnect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
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:

```text theme={null}
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    |

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

## Selecting a provider

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

```typescript theme={null}
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.

<Tabs>
  <Tab title="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                         |

    ```typescript theme={null}
    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!,
      }
    });
    ```
  </Tab>

  <Tab title="ClickPesa">
    | Field                 | Description                    |
    | --------------------- | ------------------------------ |
    | `baseUrl`             | Base URL for the ClickPesa API |
    | `CLICKPESA_CLIENT_ID` | Your ClickPesa client ID       |
    | `CLICKPESA_API_KEY`   | Your ClickPesa API key         |

    ```typescript theme={null}
    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!,
      }
    });
    ```
  </Tab>

  <Tab title="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  |

    ```typescript theme={null}
    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
      }
    });
    ```
  </Tab>
</Tabs>