API Reference
USSD API
The Orchestrator supports interactive USSD sessions for offline field-agent operations. Agents dial a shortcode and navigate a menu-driven interface to trigger payment actions without internet access.
POST /api/v1/ussd
Handles an interactive USSD session. The USSD aggregator forwards each keypress from the user's phone to this endpoint, which returns the next menu screen.
Request Body
{
"sessionId": "session_123",
"phoneNumber": "233501234567",
"text": "1",
"serviceCode": "*203#"
}Request Fields
| Field | Type | Description |
|---|---|---|
| sessionId | string | Unique session identifier from the USSD aggregator |
| phoneNumber | string | Caller's phone number in international format (e.g. 233501234567) |
| text | string | The user's input so far (aggregator concatenates with previous inputs) |
| serviceCode | string | The USSD shortcode that was dialed (e.g. *203#) |
Response Format
Responses use the standard telco USSD format. Return plain text with the appropriate prefix:
| Prefix | Meaning |
|---|---|
| CON | Continue — displays the text and waits for user input |
| END | End — displays the text and terminates the session |
USSD Templates
The Orchestrator includes built-in USSD templates that merchants can enable or disable from their settings.
| Template | Purpose |
|---|---|
| transaction-status | Enter a transaction reference to view amount, status, date, and recipient count |
| agent-collection | Five-step flow: agent ID → customer phone → amount → confirm → record (bypasses STK push) |
| commission-balance | Enter agent phone to see pending commission, paid total, and last payout date |
| transaction-history | View last 5 transactions with status icons; select one for full details |
Session Lifecycle
- User dials the USSD shortcode (e.g. *347*203#). The aggregator initiates a session.
- Aggregator sends initial request to POST /api/v1/ussd with the user's phone and empty text.
- Orchestrator resolves the merchant by shortcode and returns the main menu (CON response).
- User selects an option. Aggregator sends updated text with the accumulated input.
- Orchestrator routes to the appropriate template module based on templateType.
- Session continues (CON) or terminates (END) based on the template flow.
- Sessions expire after 120 seconds of inactivity.
Use Cases
- Field agents collecting payments on behalf of merchants in areas with poor internet connectivity
- Microfinance institutions managing agent networks in rural communities
- Last-mile logistics confirming delivery and triggering payouts from a basic feature phone