API Reference@borapesa/clickpesaClasses

Class: ClickPesaProvider

Defined in: providers/clickpesa/src/clickpesa.ts:156

Extends

  • BasePaymentProvider

Constructors

Constructor

new ClickPesaProvider(config): ClickPesaProvider;

Defined in: providers/clickpesa/src/clickpesa.ts:172

Parameters

ParameterType
configClickPesaConfig

Returns

ClickPesaProvider

Overrides

BasePaymentProvider.constructor

Properties

PropertyModifierTypeDefault valueDescriptionOverridesDefined in
namereadonlyProviderName'clickpesa'Unique provider identifier.BasePaymentProvider.nameproviders/clickpesa/src/clickpesa.ts:157

Methods

bulkCreateCustomerNumbers()

bulkCreateCustomerNumbers(controlNumbers): Promise<BillPayBulkResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:847

Bulk-create up to 50 customer control numbers in a single request.

Parameters

ParameterType
controlNumbersRecord<string, unknown>[]

Returns

Promise<BillPayBulkResult>

bulkCreateOrderNumbers()

bulkCreateOrderNumbers(controlNumbers): Promise<BillPayBulkResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:834

Bulk-create up to 50 order control numbers in a single request.

Parameters

ParameterType
controlNumbersRecord<string, unknown>[]

Returns

Promise<BillPayBulkResult>

cancelOrder()?

optional cancelOrder(_orderId): Promise<CancelOrderResult>;

Defined in: packages/pesa/dist/providers/base.d.ts:100

Cancel a pending or in-progress order.

Parameters

ParameterType
_orderIdstring

Returns

Promise<CancelOrderResult>

Throws

PesaUnsupportedError — if the provider does not support cancellation.

Inherited from

BasePaymentProvider.cancelOrder

createChecksum()

createChecksum(payload): string;

Defined in: providers/clickpesa/src/clickpesa.ts:916

Internal

Create a ClickPesa-compatible HMAC-SHA256 checksum for a request body.

Algorithm (per ClickPesa docs):

  1. Canonicalize — recursively sort all object keys alphabetically.
  2. Serialize to compact JSON (no whitespace).
  3. Return hex digest of HMAC-SHA256(key, json_string).

Exposed for testing via the provider instance.

Parameters

ParameterType
payloadRecord<string, unknown>

Returns

string

createCustomerControlNumber()

createCustomerControlNumber(params): Promise<BillPayControlNumber>;

Defined in: providers/clickpesa/src/clickpesa.ts:808

Generate a persistent control number tied to a specific customer. At least one of phone or email must be supplied.

Parameters

ParameterType
params{ amount?: number; billReference?: string; customerName: string; description?: string; email?: string; paymentMode?: "ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"; phone?: string; }
params.amount?number
params.billReference?string
params.customerNamestring
params.description?string
params.email?string
params.paymentMode?"ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"
params.phone?string

Returns

Promise<BillPayControlNumber>

createOrder()

createOrder(payload): Promise<OrderResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:299

Initiate a checkout / USSD push / redirect.

The SDK calls validateCreateOrderPayload() before this, so you can assume amount > 0, reference is non-empty, and customer.phone is in MSISDN format.

Parameters

ParameterType
payloadCreateOrderPayload

Returns

Promise<OrderResult>

Overrides

BasePaymentProvider.createOrder

createOrderControlNumber()

createOrderControlNumber(params?): Promise<BillPayControlNumber>;

Defined in: providers/clickpesa/src/clickpesa.ts:787

Generate a one-time order control number.

Customers pay this number via mobile money, SIM banking, or CRDB Wakala. All fields are optional — the API auto-generates a reference if omitted.

Parameters

ParameterType
params?{ amount?: number; billReference?: string; description?: string; paymentMode?: "ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"; }
params.amount?number
params.billReference?string
params.description?string
params.paymentMode?"ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"

Returns

Promise<BillPayControlNumber>

disburse()

disburse(payload): Promise<DisburseResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:466

B2C / wallet-out disbursement.

The SDK calls validateDisbursePayload() before this.

Parameters

ParameterType
payloadDisbursePayload

Returns

Promise<DisburseResult>

Overrides

BasePaymentProvider.disburse
generatePayoutLink(amount, orderId): Promise<string>;

Defined in: providers/clickpesa/src/clickpesa.ts:644

Generate a hosted payout link.

The recipient uses the link to enter their own bank or mobile-money details — you don't need to collect them yourself. Returns a URL you redirect the recipient to.

Parameters

ParameterType
amountnumber
orderIdstring

Returns

Promise<string>

getAccountStatement()

getAccountStatement(
   currency?, 
   startDate?, 
   endDate?): Promise<{
  accountDetails: Record<string, unknown>;
  transactions: Record<string, unknown>[];
}>;

Defined in: providers/clickpesa/src/clickpesa.ts:691

Fetch a transaction statement for a given currency.

Parameters

ParameterTypeDefault valueDescription
currencystring'TZS'— "TZS" (default) or "USD".
startDate?Dateundefined— Optional filter: start date.
endDate?Dateundefined— Optional filter: end date.

Returns

Promise<{ accountDetails: Record<string, unknown>; transactions: Record<string, unknown>[]; }>

getBalance()

getBalance(): Promise<BalanceResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:529

Retrieve available balances across all active currencies.

Useful for dashboards, pre-disbursement checks, and wallet health monitoring. Returns per-currency balance entries with raw provider data for advanced use.

Returns

Promise<BalanceResult>

{ balances: [...] } with per-currency entries.

Throws

PesaUnsupportedError — if the provider does not expose balance data.

Since

0.2.0

Overrides

BasePaymentProvider.getBalance

getBanks()

getBanks(): Promise<{
  bic: string;
  name: string;
  value?: string;
}[]>;

Defined in: providers/clickpesa/src/clickpesa.ts:677

Returns

Promise<{ bic: string; name: string; value?: string; }[]>

getBillPayDetails()

getBillPayDetails(billPayNumber): Promise<BillPayControlNumber>;

Defined in: providers/clickpesa/src/clickpesa.ts:860

Query details of a specific control number.

Parameters

ParameterType
billPayNumberstring

Returns

Promise<BillPayControlNumber>

getExchangeRates()

getExchangeRates(source?, target?): Promise<{
  date: string;
  rate: number;
  source: string;
  target: string;
}[]>;

Defined in: providers/clickpesa/src/clickpesa.ts:664

Fetch the latest exchange rates.

Parameters

ParameterTypeDescription
source?string— ISO 4217 source currency (e.g. "USD"). All sources when omitted.
target?string— ISO 4217 target currency (e.g. "TZS"). All targets when omitted.

Returns

Promise<{ date: string; rate: number; source: string; target: string; }[]>

getNameLookup()

getNameLookup(phoneOrAccount): Promise<NameLookupResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:709

Resolve the account holder name for a phone or account number.

Useful for verifying recipient identity before disbursing.

Parameters

ParameterType
phoneOrAccountstring

Returns

Promise<NameLookupResult>

Throws

PesaUnsupportedError — if the provider does not support name lookup.

Overrides

BasePaymentProvider.getNameLookup

getPaymentStatus()

getPaymentStatus(orderId): Promise<PaymentStatus>;

Defined in: providers/clickpesa/src/clickpesa.ts:392

Poll or fetch the current payment status for an order.

Parameters

ParameterType
orderIdstring

Returns

Promise<PaymentStatus>

Overrides

BasePaymentProvider.getPaymentStatus

handleWebhook()

handleWebhook(rawBody, headers): Promise<PaymentEvent>;

Defined in: providers/clickpesa/src/clickpesa.ts:411

Parse + verify an incoming webhook.

The provider must:

  1. Verify its own cryptographic signature (HMAC, checksum, etc.)
  2. Parse the raw body into structured data
  3. Return a normalized PaymentEvent

The SDK handles UUID assignment, event persistence, plugin hooks, and user-registered handler emission after this method returns.

Parameters

ParameterType
rawBodystring | Buffer<ArrayBufferLike>
headersRecord<string, string>

Returns

Promise<PaymentEvent>

Overrides

BasePaymentProvider.handleWebhook

listOrders()

listOrders(params): Promise<ListOrdersResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:732

List payment orders for a date range.

Parameters

ParameterType
paramsListOrdersParams

Returns

Promise<ListOrdersResult>

Throws

PesaUnsupportedError — if the provider does not support listing orders.

Overrides

BasePaymentProvider.listOrders

previewDisburse()

previewDisburse(payload): Promise<PreviewResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:591

Preview / dry-run a disbursement before committing.

Parameters

ParameterType
payloadDisbursePayload

Returns

Promise<PreviewResult>

Throws

PesaUnsupportedError — if the provider does not support preview.

Overrides

BasePaymentProvider.previewDisburse

previewOrder()

previewOrder(payload): Promise<PreviewResult>;

Defined in: providers/clickpesa/src/clickpesa.ts:544

Preview / dry-run a payment before committing.

Returns expected fees and validity without charging the customer.

Parameters

ParameterType
payloadCreateOrderPayload

Returns

Promise<PreviewResult>

Throws

PesaUnsupportedError — if the provider does not support preview.

Overrides

BasePaymentProvider.previewOrder

refund()?

optional refund(_orderId, _amount?): Promise<RefundResult>;

Defined in: packages/pesa/dist/providers/base.d.ts:94

Refund a completed payment.

Parameters

ParameterType
_orderIdstring
_amount?number

Returns

Promise<RefundResult>

Throws

PesaUnsupportedError — if the provider does not support refunds.

Inherited from

BasePaymentProvider.refund

updateBillPayReference()

updateBillPayReference(billPayNumber, params): Promise<BillPayControlNumber>;

Defined in: providers/clickpesa/src/clickpesa.ts:870

Partially update a BillPay reference. At least one field besides billPayNumber must be provided.

Parameters

ParameterType
billPayNumberstring
params{ amount?: number; description?: string; paymentMode?: "ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"; status?: "ACTIVE" | "INACTIVE"; }
params.amount?number
params.description?string
params.paymentMode?"ALLOW_PARTIAL_AND_OVER_PAYMENT" | "EXACT"
params.status?"ACTIVE" | "INACTIVE"

Returns

Promise<BillPayControlNumber>

updateBillPayStatus()

updateBillPayStatus(billPayNumber, status): Promise<BillPayControlNumber>;

Defined in: providers/clickpesa/src/clickpesa.ts:894

Activate or deactivate a control number (convenience wrapper).

Parameters

ParameterType
billPayNumberstring
status"ACTIVE" | "INACTIVE"

Returns

Promise<BillPayControlNumber>

validateCredentials()

validateCredentials(): Promise<{
  message?: string;
  valid: boolean;
}>;

Defined in: providers/clickpesa/src/clickpesa.ts:520

Validate that a provider config works (health check).

Useful for startup checks or /health endpoints.

Returns

Promise<{ message?: string; valid: boolean; }>

{ valid: true } if credentials are correct.

Throws

PesaUnsupportedError — if the provider does not support validation.

Overrides

BasePaymentProvider.validateCredentials

@borapesa/clickpesa

Previous Page

Interface: ClickPesaConfig

Next Page

On this page

ExtendsConstructorsConstructorParametersReturnsOverridesPropertiesMethodsbulkCreateCustomerNumbers()ParametersReturnsbulkCreateOrderNumbers()ParametersReturnscancelOrder()?ParametersReturnsThrowsInherited fromcreateChecksum()ParametersReturnscreateCustomerControlNumber()ParametersReturnscreateOrder()ParametersReturnsOverridescreateOrderControlNumber()ParametersReturnsdisburse()ParametersReturnsOverridesgeneratePayoutLink()ParametersReturnsgetAccountStatement()ParametersReturnsgetBalance()ReturnsThrowsSinceOverridesgetBanks()ReturnsgetBillPayDetails()ParametersReturnsgetExchangeRates()ParametersReturnsgetNameLookup()ParametersReturnsThrowsOverridesgetPaymentStatus()ParametersReturnsOverrideshandleWebhook()ParametersReturnsOverrideslistOrders()ParametersReturnsThrowsOverridespreviewDisburse()ParametersReturnsThrowsOverridespreviewOrder()ParametersReturnsThrowsOverridesrefund()?ParametersReturnsThrowsInherited fromupdateBillPayReference()ParametersReturnsupdateBillPayStatus()ParametersReturnsvalidateCredentials()ReturnsThrowsOverrides