Interface: PesaInstance

Defined in: packages/pesa/src/pesa.ts:89

Fully configured payments SDK instance — returned by createPesa.

Since

0.1.0

Core operations

// Initiate a payment
const order = await pesa.createOrder({
  amount:    15000,
  currency:  'TZS',
  reference: 'order_abc',
  customer:  { name: 'Juma Ali', phone: '255712345678' },
});

// Poll status
const status = await pesa.getPaymentStatus(order.orderId);

// Send money to a customer
await pesa.disburse({
  amount:    50000,
  currency:  'TZS',
  reference: 'payout_xyz',
  recipient: { phone: '255754321098', network: 'MPESA' },
});

Events

// React to verified + persisted payment events
pesa.on('PAYMENT_SUCCESS', async (event) => {
  await db.orders.update({
    id:     event.reference,
    status: 'paid',
  });
});

Optional operations (feature detection)

// Not all providers support these. Check before calling.
if (pesa.getBalance)   await pesa.getBalance();
if (pesa.refund)       await pesa.refund('order_123', 5000);
if (pesa.previewOrder) await pesa.previewOrder({ ... });
if (pesa.validateCredentials) await pesa.validateCredentials();

HTTP mount

// Mount the webhook handler — the one route that must be public
Bun.serve({ fetch: pesa.mountWebhook });
// For orders/status, use pesa.createOrder() and pesa.getPaymentStatus()
// in your own routes behind your own auth middleware.

Properties

Methods

cancelOrder()?

optional cancelOrder(orderId): Promise<CancelOrderResult>;

Defined in: packages/pesa/src/pesa.ts:150

Cancel a pending or in-progress order. undefined if unsupported.

Parameters

Returns

Promise<CancelOrderResult>

createOrder()

createOrder(payload): Promise<OrderResult>;

Defined in: packages/pesa/src/pesa.ts:102

Initiate a checkout / USSD push / redirect.

The SDK validates the payload before forwarding to the provider (amount > 0, valid MSISDN phone, non-empty reference).

Parameters

Returns

Promise<OrderResult>

Throws

PesaValidationError — if the payload is invalid.

PesaNetworkError — if the provider is unreachable.

PesaProviderError — if the provider returns an error.

disburse()

disburse(payload): Promise<DisburseResult>;

Defined in: packages/pesa/src/pesa.ts:124

B2C / wallet-out disbursement.

The SDK validates the payload before forwarding to the provider.

Returns a DisburseResult whose status is 'QUEUED' (processing — poll for updates), 'SUCCESS', or 'FAILED'.

Parameters

Returns

Promise<DisburseResult>

Throws

PesaValidationError — if the payload is invalid.

PesaNetworkError — if the provider is unreachable.

PesaProviderError — if the provider returns an error.

getBalance()?

optional getBalance(): Promise<BalanceResult>;

Defined in: packages/pesa/src/pesa.ts:156

Retrieve wallet balances across currencies. undefined if unsupported.

Returns

Promise<BalanceResult>

getNameLookup()?

optional getNameLookup(phoneOrAccount): Promise<NameLookupResult>;

Defined in: packages/pesa/src/pesa.ts:165

Resolve account holder name. undefined if unsupported.

Parameters

Returns

Promise<NameLookupResult>

getPaymentStatus()

getPaymentStatus(orderId): Promise<PaymentStatus>;

Defined in: packages/pesa/src/pesa.ts:110

Poll or fetch current payment status.

Parameters

Returns

Promise<PaymentStatus>

Throws

PesaNetworkError — if the provider is unreachable.

PesaProviderError — if the provider returns an error.

handleWebhook()

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

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

Handle an incoming webhook. Called by framework adapters.

Flow: provider verification → UUID assignment → plugin hooks → event persistence → user-registered handler emission.

Parameters

Returns

Promise<void>

listOrders()?

optional listOrders(params): Promise<ListOrdersResult>;

Defined in: packages/pesa/src/pesa.ts:168

List payment orders. undefined if unsupported.

Parameters

Returns

Promise<ListOrdersResult>

on()

on(event, handler): void;

Defined in: packages/pesa/src/pesa.ts:142

Register a handler for a payment event type.

Handlers fire after the event is verified and persisted. Multiple handlers can be registered for the same event type.

Parameters

Returns

void

previewDisburse()?

optional previewDisburse(payload): Promise<PreviewResult>;

Defined in: packages/pesa/src/pesa.ts:162

Preview / dry-run a disbursement. undefined if unsupported.

Parameters

Returns

Promise<PreviewResult>

previewOrder()?

optional previewOrder(payload): Promise<PreviewResult>;

Defined in: packages/pesa/src/pesa.ts:159

Preview / dry-run a payment. undefined if unsupported.

Parameters

Returns

Promise<PreviewResult>

refund()?

optional refund(orderId, amount?): Promise<RefundResult>;

Defined in: packages/pesa/src/pesa.ts:147

Refund a completed payment. undefined if unsupported.

Parameters

Returns

Promise<RefundResult>

validateCredentials()?

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

Defined in: packages/pesa/src/pesa.ts:153

Validate provider credentials (health check). undefined if unsupported.

Returns

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