USSD API
One endpoint, shaped like an Africa's Talking USSD callback. The simulator uses it, and so can curl or a test runner.
Endpoint
POST https://cinema-test.yomox.app/api/ussd, form-encoded or JSON. No sign-in and no CSRF token are needed. Limit: 120 requests a minute per IP address (then 429).
| Field | Rule | Meaning |
|---|---|---|
sessionId | required, 1-64 of A-Z a-z 0-9 _ - | The network's id for one dialled session |
serviceCode | required, up to 20 characters | Must be *120*3456#; anything else ends the session |
phoneNumber | required, +27 and 9 digits or 0 and 9 digits | Whose bookings to show and save |
text | optional, up to 200 characters | Every reply so far, joined with *; empty on the first request |
Replies
The body is text/plain. It starts with CON when the menu waits for a reply, or END when the session is over. Every screen fits in 182 characters, the USSD limit. A request that breaks a rule gets 422 with a JSON list of errors.
curl -s -X POST https://cinema-test.yomox.app/api/ussd \
-d sessionId=demo-1 -d serviceCode='*120*3456#' \
-d phoneNumber=+27820000000 -d text=
CON Welcome to Marula Picture House
1. Now showing
2. Book tickets
3. My bookings
4. Cinema info
5. Loyalty points
0. Exit# Book 2 Adult tickets for Karoo Nights at 18:15: 2, film 2, time 2, Adult, 2 tickets, confirm
curl -s -X POST https://cinema-test.yomox.app/api/ussd \
-d sessionId=demo-2 -d serviceCode='*120*3456#' \
-d phoneNumber=+27820000000 -d text='2*2*2*1*2*1'
END Booking confirmed. Ref MPH-7KQ2XD
Karoo Nights 18:15
Adult x2, total R190
Pay at the box office before the show.Menu map
- Now showing: pick a film to see its rating, genre, length and times, then 1. Book this film.
- Book tickets: film, then time (with seats left), then ticket type, then the number of tickets (1-10), then 1. Confirm or 2. Cancel.
- My bookings: the latest bookings for this phone number. Pick one to see it, then 1. Cancel booking releases its seats.
- Cinema info: address and opening hours.
- Loyalty points: the points balance for this phone number. Every booking earns 1 point for each R10 spent; cancelling a booking takes its points away again. 100 points = 1 free ticket.
0 is Exit on the main menu and Back everywhere else. 00 goes back to the main menu from anywhere. A choice that is not on the menu shows the same menu again, headed "Invalid choice."
Ticket prices
| Reply | Ticket | Price |
|---|---|---|
| 1 | Adult | R95 |
| 2 | Student | R75 |
| 3 | Child | R60 |
Tickets are paid at the box office: the service never asks for credit card details.
Test data
- Tides of the Wild Coast at 19:45 is sold out: choosing it answers "Sorry, that show is sold out."
- Baobab Boys at 20:30 has 4 seats left: asking for more answers "Only 4 seats left."
- Seats are taken in one database transaction, so two phones can never book the last seat twice.
- Cancelling a booking puts its seats back on sale straight away.