USSD application

Build the main menuCopy Anchor Link

Open the Start node (the Main menu every session begins at). In the structured editor, set Menu Message to Kijani Bank and add two options: Check balance and Pay a bill.

Add the other nodes from the table below before you connect anything, so the destination pickers can find them.

Point option 1 of Start at Get balance and option 2 at Bill account. Connect Bill account to Bill amount, and Bill amount to Valid amount?.

Fetch the balanceCopy Anchor Link

Open Get balance:

1. Set the method to GET and the URL to https://api.example.com/accounts/{{state.currentUserSessionSystemContext.phoneNumber}}/balance. That variable holds the caller's number in the format your aggregator sends.
2. Under Auth or the headers, send your key as Bearer ${CREDENTIALS.BANK_API_KEY}.
3. Set Output variable to balance. The response body is saved there, so the amount is {{state.balance.amount}}.
4. Turn on Retry with 1 or 2 attempts and a short delay. The caller is waiting on the line.
5. Leave Failure path on. Connect success to Balance and failure to Unavailable.

Set the Balance message to Your balance is KES {{state.balance.amount}}. Thank you for banking with us.

Check the amountCopy Anchor Link

Open Valid amount? and add a path where state.billAmount is greater or equal 1 and less or equal 100000. Turn on the Fallback path, which catches anything else, including text that is not a number.

Connect the first path to Confirm and the fallback path to Invalid amount.

Set the Confirm message to Pay KES {{state.billAmount}} to account {{state.billAccount}}?, then point option 1 (Pay) at Pay bill and option 2 (Cancel) at Cancelled.

Make the paymentCopy Anchor Link

Open Pay bill:

1. Set the method to POST and the URL to https://api.example.com/payments, with the same authorization header as before.
2. Set a JSON body:

{
  "phone": "{{state.currentUserSessionSystemContext.phoneNumber}}",
  "account": "{{state.billAccount}}",
  "amount": "{{state.billAmount}}"
}

3. Set Output variable to payment.
4. Leave Retry off unless your API accepts an idempotency key. Retrying a payment request can charge the customer twice.
5. Connect success to Receipt and failure to Unavailable.

Text a receiptCopy Anchor Link

Open Receipt (a Messaging node):

1. Choose your provider under Medium and its credential under Credentials to connect with.
2. Set Resource to SMS and Operation to Send.
3. Set From to your sender ID, To to {{state.currentUserSessionSystemContext.phoneNumber}}, and Message to Paid KES {{state.billAmount}} to {{state.billAccount}}. Ref {{state.payment.reference}}.
4. Connect it to Paid, and set the Paid message to Payment successful. Ref {{state.payment.reference}}. An SMS receipt is on its way.

See Messaging for provider details. The SMS is sent before the closing screen appears, so keep the flow short.

Test in the simulatorCopy Anchor Link

Save the project, select Simulate and dial. Try both menu options, an amount of 0, a non-number, and Cancel on the confirmation. To test the failure path, point Get balance at a URL that returns an error and check you land on Unavailable.

Go liveCopy Anchor Link

Publish the project and paste its Callback URL into your aggregator's dashboard. See Going live.