FintechSDK class reference

Complete reference for FintechSDK: constructor options, the pay() method for USSD push payments, and registerIpn() for webhook registration with PesaPal.

FintechSDK is the main class you interact with. It wraps a provider instance created by ProviderFactory and exposes the two core methods: pay() and registerIpn().

Constructor

new FintechSDK(options: { provider: ProviderType | string; config: any })

provider · ProviderType | string · required

The provider to use. Use ProviderType enum values: ProviderType.pesapal or ProviderType.clickpesa. String values ("pesapal", "clickpesa") are also accepted and matched case-insensitively.

config · object · required

Provider-specific configuration object. Must include baseUrl and the required credentials for the chosen provider. See ProviderFactory for the full list of required fields per provider.

Throws: "Invalid configuration: Missing required fields for [Provider]" if any required config fields are absent.

import { FintechSDK } from 'finconnect';

const sdk = new FintechSDK({
  provider: 'pesapal',
  config: {
    baseUrl: process.env.PESAPAL_BASE_URL!,
    PESAPAL_CONSUMER_KEY: process.env.PESAPAL_CONSUMER_KEY!,
    PESAPAL_CONSUMER_SECRET: process.env.PESAPAL_CONSUMER_SECRET!,
  }
});

---

sdk.pay()

async pay(data: any, ipnId?: string): Promise<any>

Initiates a USSD push payment. For PesaPal, the ipnId is merged into the payload as notification_id. For ClickPesa, data is sent directly without modification.

data · any · required

Payment payload. The required fields depend on the provider — see the provider-specific guides for payload structure.

ipnId · string

IPN ID returned by registerIpn(). Required for PesaPal payments. Not used by ClickPesa.

Returns: Provider response object. Shape varies by provider.

Throws: "Payment request failed: ..." on error.

PesaPal

// Register IPN once (e.g. at startup) and reuse the ID
const ipnId = await sdk.registerIpn('https://yourapp.com/ipn', 'GET');

const result = await sdk.pay(
  {
    id: 'ORDER-001',
    currency: 'KES',
    amount: 1500,
    description: 'Order payment',
    callback_url: 'https://yourapp.com/callback',
    billing_address: {
      phone_number: '0712345678',
    },
  },
  ipnId
);

console.log(result);

ClickPesa

const result = await sdk.pay({
  amount: '1500',
  currency: 'TZS',
  externalId: 'ORDER-001',
  phoneNumber: '255712345678',
});

console.log(result);

AzamPay

  const result = await sdk.pay({
      accountNumber: "accountNumber",
      amount: 0,
      currency: "currency",
      externalId: "externalId",
      provider: "Airtel",
      additionalProperties: {
          key: {}
        }
    });
  console.log(result)

---

sdk.registerIpn()

async registerIpn(ipnUrl: string, ipnNotificationType: "GET" | "POST"): Promise<any>

Registers an IPN (Instant Payment Notification) URL with the provider. Currently only supported by PesaPal — calling this method with a ClickPesa instance throws an error.

ipnUrl · string · required

Publicly accessible URL that the provider will call when a payment status changes. Must be HTTPS in production.

ipnNotificationType · "GET" | "POST" · required

HTTP method the provider uses when delivering notifications. Defaults to "GET" in FintechSDK.

Returns: The ipn_id string returned by PesaPal. Pass this value as the second argument to sdk.pay().

Throws: "IPN registration not supported by this provider" when called with a ClickPesa instance.

const ipnId = await sdk.registerIpn('https://yourapp.com/ipn', 'GET');
// ipnId -> "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Register your IPN URL once at application startup and store the returned ipnId. You do not need to re-register on every payment request.