Overview & Prerequisites

I had created a Receipt Manager platform that uses a dedicated Bulk SMS subsystem to send instant, automated transactional receipts and payment confirmations to customers. By integrating with BongaTech—a robust, East African bulk SMS gateway—the platform ensures reliable delivery of SMS notifications directly to clients' mobile devices.

This documentation walks through the setup, configuration, and code implementation of the integration.

How It Works

The SMS transactional pipeline operates asynchronously within the platform's backend services:

[ Payment Event ] ---> [ Template Compiler ] ---> [ Number Normalizer ] ----> [ BongaTech API Gateway ] ---> [ Customer Handset ]

1. Trigger Event: A payment is successfully processed or imported into the database.
2. Template Compilation: The system interpolates dynamic transactional fields (such as Customer Name, Amount, and Receipt Number) into a clean corporate template.
3. Number Normalization: Raw phone numbers of varying formats (e.g., 0712..., +254...) are normalized to a strict, standardized E.164-compatible format (254XXXXXXXXX).
4. API Dispatch: The system sends an authenticated secure HTTPS POST payload to the BongaTech Bulk SMS gateway.

Prerequisites

Before configuring or writing any code, ensure you have set up your BongaTech merchant account and obtained the following credentials from the BongaTech Developer Portal:

1. Account Credentials

• API Key / Token: A unique authentication token generated from your BongaTech account dashboard used to authorize HTTP requests.
• Sender ID (Alpha-Numeric Header): A registered brand name or custom sender ID (e.g., GEOHACK, RECEIPTS) approved by BongaTech and local telecommunications regulators.

2. Supported Environments

• Node.js: Runtime environment version v18.x or higher.
• Next.js: Fully compatible with Next.js Server Actions, Route Handlers, or traditional API endpoints.
• Network Access: Outbound HTTPS access allowed to https://bulk.bongatech.co.ke.