USSD gateway

The contract

For every step of a session, the gateway posts to the church's USSD URL and shows the plain-text reply on the handset. It is the Africa's Talking style callback, so most Kenyan gateways (including Mobile Sasa USSD in callback mode) work without changes.

{church} is the church's uuid, shown in the portal under Settings. The same handler also answers /api/v1/process-ussd/{church} and /api/v2/process-ussd/{church}; use whichever the gateway was configured with.

The reply is text/plain and starts with one of:

• CON : show the text and wait for input.
• END : show the text and close the session.

Example session

curl -X POST https://uat-api.mychurch.co.ke/api/process-ussd/00000000-0000-4000-8000-000000000001 \
  -d sessionId=ATUid_7f3a91 -d phoneNumber=+254712345678 \
  -d serviceCode='*657*45#' -d networkCode=63902 -d text=

CON Welcome to Grace Chapel Nairobi
1. My Account
2. Givings
3. Pledge
4. Service Attendance
5. Park Car
6. Today's Services
7: MORE

curl -X POST https://uat-api.mychurch.co.ke/api/process-ussd/00000000-0000-4000-8000-000000000001 \
  -d sessionId=ATUid_7f3a91 -d phoneNumber=+254712345678 \
  -d serviceCode='*657*45#' -d networkCode=63902 -d text=2

Only the last *-separated part of text is the new input; MyChurch keeps the rest of the session's state itself, so a gateway that sends the whole path and one that sends only the latest input both work.

The menu

Unregistered caller                    Registered member
1. Register as Member                  1. My Account (profile, departments, pledge balance,
2. Givings                                children, spouse, stop messages)
3. Service Attendance                  2. Givings (single or multiple accounts)
4. Pledge                              3. Pledge (pledge, edit pledge)
5. Park Car                            4. Service Attendance (check in, child check-in
6. Contact Us                             and checkout, trustees)
7: MORE (prayer request, today's       5. Park Car
   services, feedback, statement)      6. Today's Services
                                       7: MORE (contact us, prayer request, feedback,
                                          statement)

• 00 returns to the main menu from any screen; 0 goes back.
• A choice outside the options answers CON Invalid choice with the screen again.
• Giving ends in an M-Pesa payment prompt on the caller's phone or another number (STK push).
• Service check-in asks for the four-digit service code shown in church that day.
• Registration collects name, address, date of birth, gender, marital status and a PIN. Whether the new member is active at once or waits for approval is a church setting.
• The statement option is hidden for churches that hide statements.

Sessions and errors

• State is kept per sessionId and expires after ten minutes without input.
• An unknown church uuid answers END The church does not exist; a deactivated church END The church has been deactivated.
• A request without sessionId or phoneNumber, or a church not yet moved to the new platform, answers END The application is under maintenance. Try again later.
• USSD requests are never rate limited. Every request is logged.