Abstract Class: BasePaymentProvider

Defined in: packages/pesa/src/providers/base.ts:75

Abstract base class every provider adapter must implement.

Since

0.1.0

The SDK calls only these methods — no provider-specific logic ever leaks into application code.

Required methods (must implement)

• createOrder — initiate a checkout / USSD push / redirect
• getPaymentStatus — poll or fetch current payment status
• handleWebhook — parse + verify an incoming webhook
• disburse — B2C / wallet-out disbursement

Optional methods (override to enable)

Default implementations throw PesaUnsupportedError. Applications can feature-detect capability:

if (pesa.getBalance) {
  const { balances } = await pesa.getBalance();
  console.log(`TZS balance: ${balances.find(b => b.currency === 'TZS')?.amount}`);
}

Writing a provider adapter

import { BasePaymentProvider } from '@borapesa/pesa';
import type { ProviderName, CreateOrderPayload, OrderResult } from '@borapesa/pesa';

export class MyProvider extends BasePaymentProvider {
  readonly name: ProviderName = 'selcom';

  async createOrder(payload: CreateOrderPayload): Promise<OrderResult> {
    // Call your provider's API
    const res = await fetch('https://api.provider.com/order', {
      method: 'POST',
      body: JSON.stringify(payload),
    });
    const data = await res.json();
    return {
      orderId:   data.transactionId,
      reference: payload.reference,
      status:    'PENDING',
    };
  }

  async getPaymentStatus(orderId: string): Promise<PaymentStatus> { ... }
  async handleWebhook(rawBody, headers): Promise<PaymentEvent> { ... }
  async disburse(payload): Promise<DisburseResult> { ... }
}

Constructors

Constructor

new BasePaymentProvider(): BasePaymentProvider;

Returns

BasePaymentProvider

Properties

Methods

cancelOrder()?

optional cancelOrder(_orderId): Promise<CancelOrderResult>;

Defined in: packages/pesa/src/providers/base.ts:132

Cancel a pending or in-progress order.

Parameters

Returns

Promise<CancelOrderResult>

Throws

PesaUnsupportedError — if the provider does not support cancellation.

createOrder()

abstract createOrder(payload): Promise<OrderResult>;

Defined in: packages/pesa/src/providers/base.ts:88

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

Returns

Promise<OrderResult>

disburse()

abstract disburse(payload): Promise<DisburseResult>;

Defined in: packages/pesa/src/providers/base.ts:114

B2C / wallet-out disbursement.

The SDK calls validateDisbursePayload() before this.

Parameters

Returns

Promise<DisburseResult>

getBalance()?

optional getBalance(): Promise<BalanceResult>;

Defined in: packages/pesa/src/providers/base.ts:160

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

getNameLookup()?

optional getNameLookup(_phoneOrAccount): Promise<NameLookupResult>;

Defined in: packages/pesa/src/providers/base.ts:191

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

Useful for verifying recipient identity before disbursing.

Parameters

Returns

Promise<NameLookupResult>

Throws

PesaUnsupportedError — if the provider does not support name lookup.

getPaymentStatus()

abstract getPaymentStatus(orderId): Promise<PaymentStatus>;

Defined in: packages/pesa/src/providers/base.ts:91

Poll or fetch the current payment status for an order.

Parameters

Returns

Promise<PaymentStatus>

handleWebhook()

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

Defined in: packages/pesa/src/providers/base.ts:104

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

Returns

Promise<PaymentEvent>

listOrders()?

optional listOrders(_params): Promise<ListOrdersResult>;

Defined in: packages/pesa/src/providers/base.ts:200

List payment orders for a date range.

Parameters

Returns

Promise<ListOrdersResult>

Throws

PesaUnsupportedError — if the provider does not support listing orders.

previewDisburse()?

optional previewDisburse(_payload): Promise<PreviewResult>;

Defined in: packages/pesa/src/providers/base.ts:180

Preview / dry-run a disbursement before committing.

Parameters

Returns

Promise<PreviewResult>

Throws

PesaUnsupportedError — if the provider does not support preview.

previewOrder()?

optional previewOrder(_payload): Promise<PreviewResult>;

Defined in: packages/pesa/src/providers/base.ts:171

Preview / dry-run a payment before committing.

Returns expected fees and validity without charging the customer.

Parameters

Returns

Promise<PreviewResult>

Throws

PesaUnsupportedError — if the provider does not support preview.

refund()?

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

Defined in: packages/pesa/src/providers/base.ts:123

Refund a completed payment.

Parameters

Returns

Promise<RefundResult>

Throws

PesaUnsupportedError — if the provider does not support refunds.

validateCredentials()?

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

Defined in: packages/pesa/src/providers/base.ts:144

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.