# Bora Pesa

> A unified, open-source TypeScript payments SDK for Tanzania. One factory function, createPesa(), wires a payment provider (Selcom, AzamPay, ClickPesa, Snippe, or a built-in test provider), optional plugins (retry, idempotency, logging), and an event store behind a single consistent interface.

Key conventions: amounts are whole TZS integers (15000 = TZS 15,000, never floats), phone numbers use MSISDN format (255XXXXXXXXX), and all provider API calls happen server-side. Packages are published under the @borapesa npm scope.

Every documentation page is available as plain markdown at https://borapesa.dev/llms/<path>/index.md. AI agents can also install the MCP server: npx -y @borapesa/mcp

## Documentation

- [Overview](https://borapesa.dev/llms/index/index.md): A unified, open-source payments SDK for Tanzania — one API, all providers.
- [Getting Started](https://borapesa.dev/llms/getting-started/index.md): Install Bora Pesa and process your first payment in under 5 minutes.
- [Architecture](https://borapesa.dev/llms/architecture/index.md): How Bora Pesa is designed — factory pattern, provider abstraction, plugin pipeline, and event store.
- [Providers](https://borapesa.dev/llms/providers/index.md): Available payment providers — Selcom, ClickPesa, AzamPay, Snippe — and their capabilities.
- [Adapters](https://borapesa.dev/llms/adapters/index.md): Database adapters for the event store — SQLite, in-memory, and custom.
- [Integrations](https://borapesa.dev/llms/integrations/index.md): Mount pesa.mountWebhook on any server or framework — one-liners for all major runtimes.
- [Event System](https://borapesa.dev/llms/events/index.md): Webhooks, event persistence, and typed event handlers in Bora Pesa.
- [Plugins](https://borapesa.dev/llms/plugins/index.md): Retry, idempotency, logging, and writing custom plugins.
- [Testing](https://borapesa.dev/llms/testing/index.md): BogusPaymentProvider — a deterministic test double for local development and integration tests.
- [Error Handling](https://borapesa.dev/llms/errors/index.md): Understanding PesaError, when to retry, and how to handle provider errors.
- [AI Tools](https://borapesa.dev/llms/ai-tools/index.md): MCP server, llms.txt, and markdown endpoints that let AI agents read, search, and integrate Bora Pesa.

## API Reference

- [Class: AzamPayPaymentProvider](https://borapesa.dev/llms/api/azampay/classes/AzamPayPaymentProvider/index.md)
- [@borapesa/azampay](https://borapesa.dev/llms/api/azampay/index/index.md)
- [Interface: AzamPayConfig](https://borapesa.dev/llms/api/azampay/interfaces/AzamPayConfig/index.md)
- [Class: ClickPesaProvider](https://borapesa.dev/llms/api/clickpesa/classes/ClickPesaProvider/index.md)
- [@borapesa/clickpesa](https://borapesa.dev/llms/api/clickpesa/index/index.md)
- [Interface: ClickPesaConfig](https://borapesa.dev/llms/api/clickpesa/interfaces/ClickPesaConfig/index.md)
- [Function: isAvailable()](https://borapesa.dev/llms/api/devtools/functions/isAvailable/index.md)
- [Function: startTunnel()](https://borapesa.dev/llms/api/devtools/functions/startTunnel/index.md)
- [Function: tunnelPlugin()](https://borapesa.dev/llms/api/devtools/functions/tunnelPlugin/index.md)
- [@borapesa/devtools](https://borapesa.dev/llms/api/devtools/index/index.md)
- [Interface: Tunnel](https://borapesa.dev/llms/api/devtools/interfaces/Tunnel/index.md)
- [Interface: TunnelPluginOptions](https://borapesa.dev/llms/api/devtools/interfaces/TunnelPluginOptions/index.md)
- [API Reference](https://borapesa.dev/llms/api/index/index.md)
- [Function: buildIndex()](https://borapesa.dev/llms/api/mcp/functions/buildIndex/index.md)
- [Function: createBorapesaMcpServer()](https://borapesa.dev/llms/api/mcp/functions/createBorapesaMcpServer/index.md)
- [Function: exampleTopics()](https://borapesa.dev/llms/api/mcp/functions/exampleTopics/index.md)
- [Function: getExample()](https://borapesa.dev/llms/api/mcp/functions/getExample/index.md)
- [Function: getProvider()](https://borapesa.dev/llms/api/mcp/functions/getProvider/index.md)
- [Function: loadDocStore()](https://borapesa.dev/llms/api/mcp/functions/loadDocStore/index.md)
- [Function: search()](https://borapesa.dev/llms/api/mcp/functions/search/index.md)
- [Function: tokenize()](https://borapesa.dev/llms/api/mcp/functions/tokenize/index.md)
- [@borapesa/mcp](https://borapesa.dev/llms/api/mcp/index/index.md)
- [Interface: ConfigField](https://borapesa.dev/llms/api/mcp/interfaces/ConfigField/index.md)
- [Interface: CreateServerOptions](https://borapesa.dev/llms/api/mcp/interfaces/CreateServerOptions/index.md)
- [Interface: Doc](https://borapesa.dev/llms/api/mcp/interfaces/Doc/index.md)
- [Interface: DocEntry](https://borapesa.dev/llms/api/mcp/interfaces/DocEntry/index.md)
- [Interface: DocStore](https://borapesa.dev/llms/api/mcp/interfaces/DocStore/index.md)
- [Interface: Example](https://borapesa.dev/llms/api/mcp/interfaces/Example/index.md)
- [Interface: ProviderInfo](https://borapesa.dev/llms/api/mcp/interfaces/ProviderInfo/index.md)
- [Interface: SearchIndex](https://borapesa.dev/llms/api/mcp/interfaces/SearchIndex/index.md)
- [Interface: SearchResult](https://borapesa.dev/llms/api/mcp/interfaces/SearchResult/index.md)
- [Variable: EXAMPLES](https://borapesa.dev/llms/api/mcp/variables/EXAMPLES/index.md)
- [Variable: PROVIDERS](https://borapesa.dev/llms/api/mcp/variables/PROVIDERS/index.md)
- [Abstract Class: BasePaymentProvider](https://borapesa.dev/llms/api/pesa/classes/BasePaymentProvider/index.md)
- [Class: MemoryAdapter](https://borapesa.dev/llms/api/pesa/classes/MemoryAdapter/index.md)
- [Class: PesaError](https://borapesa.dev/llms/api/pesa/classes/PesaError/index.md)
- [Class: PesaNetworkError](https://borapesa.dev/llms/api/pesa/classes/PesaNetworkError/index.md)
- [Class: PesaProviderError](https://borapesa.dev/llms/api/pesa/classes/PesaProviderError/index.md)
- [Class: PesaUnsupportedError](https://borapesa.dev/llms/api/pesa/classes/PesaUnsupportedError/index.md)
- [Class: PesaValidationError](https://borapesa.dev/llms/api/pesa/classes/PesaValidationError/index.md)
- [Class: PesaWebhookError](https://borapesa.dev/llms/api/pesa/classes/PesaWebhookError/index.md)
- [Function: createPesa()](https://borapesa.dev/llms/api/pesa/functions/createPesa/index.md)
- [Function: createPesaWebhookHandler()](https://borapesa.dev/llms/api/pesa/functions/createPesaWebhookHandler/index.md)
- [Function: normalisePhone()](https://borapesa.dev/llms/api/pesa/functions/normalisePhone/index.md)
- [Function: validateCreateOrderPayload()](https://borapesa.dev/llms/api/pesa/functions/validateCreateOrderPayload/index.md)
- [Function: validateDisbursePayload()](https://borapesa.dev/llms/api/pesa/functions/validateDisbursePayload/index.md)
- [@borapesa/pesa](https://borapesa.dev/llms/api/pesa/index/index.md)
- [Interface: BalanceEntry](https://borapesa.dev/llms/api/pesa/interfaces/BalanceEntry/index.md)
- [Interface: BalanceResult](https://borapesa.dev/llms/api/pesa/interfaces/BalanceResult/index.md)
- [Interface: CancelOrderPayload](https://borapesa.dev/llms/api/pesa/interfaces/CancelOrderPayload/index.md)
- [Interface: CancelOrderResult](https://borapesa.dev/llms/api/pesa/interfaces/CancelOrderResult/index.md)
- [Interface: CreateOrderPayload](https://borapesa.dev/llms/api/pesa/interfaces/CreateOrderPayload/index.md)
- [Interface: DisbursePayload](https://borapesa.dev/llms/api/pesa/interfaces/DisbursePayload/index.md)
- [Interface: DisburseResult](https://borapesa.dev/llms/api/pesa/interfaces/DisburseResult/index.md)
- [Interface: ListOrdersParams](https://borapesa.dev/llms/api/pesa/interfaces/ListOrdersParams/index.md)
- [Interface: ListOrdersResult](https://borapesa.dev/llms/api/pesa/interfaces/ListOrdersResult/index.md)
- [Interface: NameLookupResult](https://borapesa.dev/llms/api/pesa/interfaces/NameLookupResult/index.md)
- [Interface: OrderResult](https://borapesa.dev/llms/api/pesa/interfaces/OrderResult/index.md)
- [Interface: PaymentEvent](https://borapesa.dev/llms/api/pesa/interfaces/PaymentEvent/index.md)
- [Interface: PesaConfig](https://borapesa.dev/llms/api/pesa/interfaces/PesaConfig/index.md)
- [Interface: PesaDatabaseAdapter](https://borapesa.dev/llms/api/pesa/interfaces/PesaDatabaseAdapter/index.md)
- [Interface: PesaHandlerTarget](https://borapesa.dev/llms/api/pesa/interfaces/PesaHandlerTarget/index.md)
- [Interface: PesaInstance](https://borapesa.dev/llms/api/pesa/interfaces/PesaInstance/index.md)
- [Interface: PesaPlugin](https://borapesa.dev/llms/api/pesa/interfaces/PesaPlugin/index.md)
- [Interface: PreviewResult](https://borapesa.dev/llms/api/pesa/interfaces/PreviewResult/index.md)
- [Interface: RefundResult](https://borapesa.dev/llms/api/pesa/interfaces/RefundResult/index.md)
- [Interface: RequestContext](https://borapesa.dev/llms/api/pesa/interfaces/RequestContext/index.md)
- [Interface: ResponseContext](https://borapesa.dev/llms/api/pesa/interfaces/ResponseContext/index.md)
- [Type Alias: Currency](https://borapesa.dev/llms/api/pesa/type-aliases/Currency/index.md)
- [Type Alias: MobileNetwork](https://borapesa.dev/llms/api/pesa/type-aliases/MobileNetwork/index.md)
- [Type Alias: PaymentEventType](https://borapesa.dev/llms/api/pesa/type-aliases/PaymentEventType/index.md)
- [Type Alias: PaymentStatus](https://borapesa.dev/llms/api/pesa/type-aliases/PaymentStatus/index.md)
- [Type Alias: ProviderName](https://borapesa.dev/llms/api/pesa/type-aliases/ProviderName/index.md)
- [Type Alias: TZSAmount](https://borapesa.dev/llms/api/pesa/type-aliases/TZSAmount/index.md)
- [Class: SelcomPaymentProvider](https://borapesa.dev/llms/api/selcom/classes/SelcomPaymentProvider/index.md)
- [@borapesa/selcom](https://borapesa.dev/llms/api/selcom/index/index.md)
- [Interface: SelcomConfig](https://borapesa.dev/llms/api/selcom/interfaces/SelcomConfig/index.md)
- [Class: SnippePaymentProvider](https://borapesa.dev/llms/api/snippe/classes/SnippePaymentProvider/index.md)
- [@borapesa/snippe](https://borapesa.dev/llms/api/snippe/index/index.md)
- [Interface: SnippeConfig](https://borapesa.dev/llms/api/snippe/interfaces/SnippeConfig/index.md)
- [Class: SQLiteAdapter](https://borapesa.dev/llms/api/sqlite/classes/SQLiteAdapter/index.md)
- [@borapesa/sqlite](https://borapesa.dev/llms/api/sqlite/index/index.md)

## Optional

- [llms-full.txt](https://borapesa.dev/llms-full.txt): the entire documentation in a single file
- [AI tools guide](https://borapesa.dev/docs/ai-tools/): MCP server setup for Claude Code, Cursor, VS Code, and Windsurf
- [GitHub repository](https://github.com/borapesa/pesa)