Interface: PesaInstance

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

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.refund)     await pesa.refund('order_123', 5000);
if (pesa.previewOrder)  await pesa.previewOrder({ ... });
if (pesa.validateCredentials) await pesa.validateCredentials();

HTTP mount

// Mount directly on any fetch-compatible server
Bun.serve({ fetch: pesa.mount });
// Or use a framework adapter:
// - @borapesa/nextjs → export const { GET, POST } = toNextJsHandler(pesa);
// - @borapesa/express → app.use('/api/pesa', toPesaRouter(pesa));

Properties

Methods

cancelOrder()?

optional cancelOrder(orderId): Promise<CancelOrderResult>;

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

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:101

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:120

B2C / wallet-out disbursement.

The SDK validates the payload before forwarding to the provider.

Parameters

Returns

Promise<DisburseResult>

Throws

PesaValidationError — if the payload is invalid.

PesaNetworkError — if the provider is unreachable.

PesaProviderError — if the provider returns an error.

getNameLookup()?

optional getNameLookup(phoneOrAccount): Promise<NameLookupResult>;

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

Resolve account holder name. undefined if unsupported.

Parameters

Returns

Promise<NameLookupResult>

getPaymentStatus()

getPaymentStatus(orderId): Promise<PaymentStatus>;

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

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:128

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:161

List payment orders. undefined if unsupported.

Parameters

Returns

Promise<ListOrdersResult>

on()

on(event, handler): void;

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

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:155

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:152

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:143

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:149

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

Returns

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