Vendor USSD Endpoint

Just-tap calls an endpoint hosted by your application. You choose the path; this guide uses /ussd/webhook.

Request body

| Field | Type | Required | Description | | --- | --- | --- | | newSession | boolean | Yes | true for the first request; false for a response to a previous menu. | | userInput | string | No | Customer entry, normally omitted on a new session. Preserve it as a string. | | msisdn | string | Yes | Customer number in international Zambian format; examples use 260 without +. | | sessionId | string | Yes | Identifier used to retrieve application state. | | shortCode | string | No | Full dialled code, such as *363*10#; it may be empty on continuation. | | menuCode | string | No | Gateway-resolved enrolment routing code retained for existing integrations. | | routingCode | string | No | Original dialled routing code. | | provider | string | No | Network source: mtn, airtel, zamtel, or gateway. |

{
  "newSession": true,
  "msisdn": "260970000000",
  "sessionId": "demo-session-001",
  "shortCode": "*363*10#",
  "menuCode": "10",
  "routingCode": "10",
  "provider": "mtn"
}

Optional fields may be absent. Do not use an optional routing field as a substitute for request authentication.

To confirm before publication: Define when menuCode and routingCode differ, which one new vendors should use, when fields are populated, what provider: "gateway" means, and whether empty userInput is valid on a continuation.

Response body

Return the fields at the top level with Content-Type: application/json:

| Field | Type | Required | Description | | --- | --- | --- | | sessionState | string | Yes | Exact value Continue waits for input; End closes the session. | | message | string | Yes | Customer-visible text. Use \n for menu lines. |

{
  "sessionState": "Continue",
  "message": "Welcome to Demo Store\n1. Opening hours\n2. Store location\n0. Exit"
}

Do not wrap the response in data or response, and do not return CON/END, XML, plain text, or mobile-network-specific headers. Keep messages concise and one numbered option per line. Under 160 characters is a useful target, not a guaranteed cross-network maximum.

Failure behaviour

For a timeout, network error, non-200, invalid JSON, or missing response fields, the gateway ends the session with a generic unavailable message. Error bodies are diagnostics, not customer messages.