USSD Web Service
iNoti's USSD service lets you handle interactive user journeys over short codes without needing internet access. Build a page on your own infrastructure, receive the incoming parameters, and shape the flow exactly as your business requires.
Sending and receiving data
Your handler page is invoked with three GET parameters (call, sessionid, and mobile). Use them to design the next step in the flow.
- mobile: the caller's phone number
- sessionid: the current session identifier
- call: the dialed sequence including user input
After saving the full URL of your page in the USSD editor, every request will be routed to you. Inspect call, perform the desired business logic, and return a plain-text response.
Displaying the response text
Respond with raw text only—no HTML, BOM, or extra characters. In ASP.NET use Response.Write; in PHP use echo.
Sample lightweight web service
The following snippets greet the user, capture a registration code, and confirm it. Adapt the logic to integrate with your own data store.
function save_regcode() { $inputArr = explode('*', $_GET['call']); if (is_null($_GET['mobile']) || is_null($_GET['sessionid']) || is_null($_GET['call'])) { echo 'http://www.mySite.com[end]'; return; } elseif ($_GET['call'] == "*6655*123") { echo "Please enter your registration code"; } elseif (($inputArr[0] == "6655") && ($inputArr[1] == "123")) { $regCode = $inputArr[2]; echo "Your registration code has been stored successfully"; } } protected void Page_Load(object sender, EventArgs e) { if ((Request["mobile"] == null) || (Request["sessionid"] == null) || (Request["call"] == null)) { Response.Write("http://www.mySite.com"); return; } if (Request["call"] == "*6655*123") { Response.Write("Please enter your registration code"); } else if (Request["call"].StartsWith("*6655*123*")) { string regCode = Request["call"].Remove(0, 10); Response.Write("Your registration code was recorded successfully"); } } Accepting payments through USSD
To trigger a payment, return a pipe-separated string in the format 9900|YourFactorId|Price.
- 9900: instructs the platform to start the payment flow.
- YourFactorId: your internal invoice identifier.
- Price: the amount in IRR.
iNoti sends an SMS with the payment link. After a successful transaction, your endpoint is called again with the usual parameters plus RRN and both invoice numbers.
http://yoursite/page.aspx?mobile=0912xxxxxxx&sessionid=123&call=*6655*yourcode*...*yourfactorid*inotifactorid&RRN=12345...
Payment verification web services
Always verify the payment result before fulfilling the order. Use the SOAP endpoint below—PHP developers can rely on the provided NuSOAP sample.
GetPayments web service
Endpoint: http://login.inoti.com/_services/ExternalUssdPay.asmx
Input parameters:
| Field | Type | Description |
|---|---|---|
| Username | string | Your iNoti username |
| Password | string | Your iNoti password |
| CodeName | string | Purchased USSD code |
| IsAll | bool | Return both successful and failed transactions |
| DateFrom | string | Start date (yyyy/MM/dd) |
| DateTo | string | End date (yyyy/MM/dd) |
| SessionID | string | Returned session ID |
| PriceFrom | string | Minimum amount |
| PriceTo | string | Maximum amount |
| Mobile | string | Customer mobile number |
| RefKey | string | Digital receipt |
| iNotiFactorID | string | iNoti invoice number |
| YourFactorID | string | Your invoice number |
| RRN | string | Bank tracking number |
| NullResult | string | Optional fallback string if validation fails |
The web service responds with JSON describing the transactions:
| Field | Type |
|---|---|
| PayID | long |
| SessionID | string |
| RefKeyBank | string |
| Mobile | string |
| Price | double |
| Result | string |
| PayDateTime | DateTime |
| InotiFactorID | long |
| YourFactorID | string |
| RRN | long |
