Skip to content

USSD Services Module

Overview

This module handles USSD onboarding and session bootstrap operations for feature-phone banking flows.

Base route: - /api/v1/ussd

Primary sources scanned: - app/api/v1/endpoints/ussd.py - app/services/ussd.py - app/services/integration.py

Canonical references: - API Route Live Reference - API Route Documentation TODO

Verified Endpoints

Route Method Controller Service/Integration Path
/subscription/check POST check_subscription get_customer_by_phone_number + customer_search_cbs
/subscription/register POST subscribe account_details_cbs + register_ussd_customer
/account/register POST subscribe customer_search_cbs + register_account_cbs
/translations/fetch POST fetch_ussd_translations fetch_translations_ussd

USSD Subscription and Registration Workflows

1. Subscription Check

  1. Query platform customer by phone using get_customer_by_phone_number.
  2. Resolve linked user and language preference when already subscribed.
  3. If not found locally, call customer_search_cbs to determine external customer existence.
  4. Return subscription/existence signal for next USSD step.

2. Subscription Register (Existing CBS Customer)

  1. Fetch account details from CBS using account_details_cbs.
  2. Verify date-of-birth match between request and CBS response.
  3. Register platform-side user and customer linkage via register_ussd_customer.
  4. Assign USSD policy/role and stage approval flow.

3. Account Register (New Customer from USSD)

  1. Check phone existence on CBS using customer_search_cbs.
  2. Reject if customer already exists on CBS.
  3. Open account on CBS via account_open_cbs (through register_account_cbs).
  4. Create platform customer/profile/account records.
  5. Stage customer changes and send account-opening notification.

Service Layer Responsibilities

get_customer_by_phone_number

  • Resolves customer identity by primary phone and supported identity types.

register_ussd_customer

  • Applies USSD access policy and role.
  • Creates/stages user identity and customer identity linkage.
  • Backfills contact/profile data from CBS account-holder payload when needed.

register_account_cbs

  • Opens account on CBS.
  • Registers customer and account in platform DB.
  • Stages customer changes.
  • Emits dashboard socket event and SMS template notification.

Integration Dependencies

USSD service depends on CBS integration for identity and account operations: - customer_search_cbs - account_details_cbs - account_open_cbs

Controller pattern includes _release_request_transaction(request) before outbound CBS calls.

Operational Notes

  • Date-of-birth verification is a strict gate in /subscription/register.
  • USSD registration uses role/policy bootstrap (USSD Role, USSD Customers policy).
  • Account opening path sends notification side effects (socket + SMS) on completion.