MoMo Open API Channel as a Service (Dynamic Journey Service)
MoMo Open API Channel as a Service that empowers businesses to
showcase and control a secondary menu on
the MoMo USSD and App platforms. This feature allows businesses to increase.
their reach and attract more customers by presenting their products and services.
to MoMo consumers and partners across Africa.
How do the MoMo Dynamic Journey Service work?
- The partner defines and designs their customer journey in an XML file with the MoMo standardized format.
- The Journey XML file is submitted by the partner for approval through the MTN Partner Portal.
- The MoMo team reviews and approves the Partner Journey, if not approved the partner makes necessary revisions based on the advice of the MoMo team and resubmits it.
- Once approved, the partner publishes their journey to be displayed on the MoMo USSD menu, allowing MoMo customers to access their products and services.
How does the DJS interact with the Service Provider’s system?
The MoMo Channel as a Service communicates with the Partners' platform through the utilization of a Rest Web API that has been implemented on the Partners' side. The requests and responses of this Rest Web API must adhere to the MoMo Channel as a service standards, as outlined in the details to follow. In order to ensure that their endpoints are secure, the partner will need to provide a verified certificate for their HTTPS connections.
Steps for coming up with a DJS XML File
- Create a Customer Journey diagram using a simulated tool like Figma.
- Determine the appropriate DJS tags for each element in the journey, in case you need customer input or display options.
- Construct the dynamic file from the diagram adhering to the MoMo Channel as a service standard.
- Test and validate the Rest Web API requests and responses from the Partners platform.
- Submit the completed journey for approval by the MoMo team.
How to develop an XML Dynamic Journey file using MoMo Channel as a service standard.
(Use case used customer paying for TV subscription)
Run Collection In Postman
- Dynamic Journey Syntax – Root Tag
<?xml version="1.0" encoding="UTF-8"?>
<op:journeydefinition xmlns:op="http://www.ericsson.com/em/djs/journey/v1_0/common/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<instructions>
</instructions>
</op:journeydefinition>
-
Dynamic Journey Syntax – Common Tags
| Use Case | DJS Tag / Instruction Type |
|---|---|
| List Menu Items - Static | <options> |
| List Menu Items - Dynamic | <dynamicoptions> |
| Input Field | <question> |
| Make Call to Server | <dynamicarguments> |
| Make Decision | <matches>, <exists>, <switch> |
| End Journey | <response>, <responsematching> |
- List Menu Items – Static
This use case represents a static list of options presented to a user for selection.
| Use case | DJS Tag | |
|---|---|---|
| List Menu Items – Static | <options> | 
|
- List Menu Items – Dynamic
This use case represents a dynamic list of options presented to a user for selection. The list of options fetched using an API call from the service provider’s system.
| Use case | DJS Tag | |
|---|---|---|
| List Menu Items – Dynamic | <dynamicoptions> | 
|
- Input Field
This use case represents a field used to capture custom text from the user. E.g request a user for their name.
| Use case | DJS Tag | |
|---|---|---|
| Input Field | <question> | 
|
- Make Call to Server
This use case represents a scenario where the interaction is required between the MoMo DJS system and the providers system. Examples include, passing a given customer reference to the provider to fetch customer details, passing other aggregated journey information to the provider for further processing.
- Make Decision
This use case represents scenarios in the journey where a decision needs to be taken on the given on certain conditions being meant.
Sample Journey Design
| 
| 
|
| 
|
Figure 1 - <dynamicoptions
-
XML
<dynamicoptions>
<!-- Header Text-->
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Welcome to MoMo Pay TV Services</textmessage>
</text>
</texts>
</header>
<!-- Template for displaying the different options returned -->
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>${provider_name}</textmessage>
</text>
</texts>
</display>
<!-- URL on service provider system for returning the dynamic option argument values -->
<url>https://api.serviceprovider.com/providers</url>
<!-- Arguments to be sent in the API call to service provider system to fetch the values -->
<arguments>
<argument>
<key>all</key>
<value>provider_category</value>
</argument>
</arguments>
</dynamicoptions>
- JSON Request
{
"arguments": >
{
"key": {
"value": "provider_category"
},
"value": {
"value": "all"
}
},
{
"key": {
"value": "ACCOUNT_HOLDER_MSISDN"
},
"value": {
"value": "256772123312"
}
}
],
"languageCode": "EN",
"sessionIdentifier": "3bbbed98-ee5f-4c05-ac40-ac8b8db8cbb6",
"journeyIdentifier": "1489dbe9-8838-4783-93dc-20e0221ab3fd"
}
-
JSON Response
{
"argumentsList": u
{
"arguments": "
{
"key": {
"value": "provider_code"
},
"value": {
"value": "10001"
}
},
{
"key": {
"value": "provider_name"
},
"value": {
"value": "PayTV Provider 1"
}
}
]
},
{
"arguments":
{
"key": {
"value": "provider_code"
},
"value": {
"value": "10002"
}
},
{
"key": {
"value": "provider_name"
},
"value": {
"value": "PayTV Provider 2"
}
}
]
}
]
}
Figure 2 - <question> + <dynamicargument>
-
XML
<!-- Prompt user to enter Card Number -->
<question>
<key>card_number</key>
<retries>2</retries>
<confidential>false</confidential>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Enter ${provider_name} Card Number</textmessage>
</text>
</texts>
</display>
<validation>
<pattern>\d+</pattern>
<errormessage>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Enter Valid Card Number.</textmessage>
</text>
</texts>
</errormessage>
</validation>
</question>
<!-- Send request with details of card
number for validation on provider API -->
<dynamicarguments>
<url>https://api.serviceprovider.com/card-validation</url>
<arguments>
<argument>
<key>provider_code</key>
<value>${provider_code}</value>
</argument>
<argument>
<key>card_number</key>
<value>${card_number}</value>
</argument>
</arguments>
</dynamicarguments>
-
JSON Request
{
"arguments": /
{
"key": {
"value": "card_number"
},
"value": {
"value": "10"
}
},
{
"key": {
"value": "provider_code"
},
"value": {
"value": "10001"
}
},
{
"key": {
"value": "ACCOUNT_HOLDER_MSISDN"
},
"value": {
"value": "256772123312"
}
}
],
"languageCode": "EN",
"sessionIdentifier": "3bbbed98-ee5f-4c05-ac40-ac8b8db8cbb6",
"journeyIdentifier": "1489dbe9-8838-4783-93dc-20e0221ab3fd"
}
-
JSON Response
{
"arguments": <
{
"key": {
"value": "card_number"
},
"value": {
"value": "10"
}
},
{
"key": {
"value": "card_owner"
},
"value": {
"value": "John Doe"
}
},
{
"key": {
"value": "card_profile"
},
"value": {
"value": "Premium"
}
},
{
"key": {
"value": "card_provider_code"
},
"value": {
"value": "10001"
}
}
]
}
Figure 3 - <question>
-
XML
<!-- Prompt user to enter amount to pay -->
<question>
<key>amount</key>
<retries>2</retries>
<confidential>false</confidential>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Payment for Card Number ${card_number} Name ${card_owner} Enter Amount to Pay</textmessage>
</text>
</texts>
</display>
<validation>
<pattern>\d+</pattern>
<errormessage>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Invalid Amount.</textmessage>
</text>
</texts>
</errormessage>
</validation>
</question>
Figure 4 - <option> + <dynamicargument>
-
XML
<options>
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Payment request of amount UGX ${amount} for ${card_number} Name ${card_owner}</textmessage>
</text>
</texts>
</header>
<optionslist>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Confirm</textmessage>
</text>
</texts>
</display>
<instructions>
<dynamicarguments> <!-- Send confirm details to server for processing -->
<url>https://api.serviceprovider.com/post-payment</url>
<arguments>
<argument>
<key>card_number</key>
<value>${card_number}</value>
</argument>
<argument>
<key>card_provider_code</key>
<value>${card_provider_code}</value>
</argument>
<argument>
<key>amount</key>
<value>${amount}</value>
</argument>
</arguments>
</dynamicarguments>
<matches> <!-- handle response from server for post payment -->
<key>payment_request_status</key>
<pattern>initiated</pattern>
<yes>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Thank for you for using our Services. Please approve the transaction when prompted to complete the payment
</textmessage>
</text>
</texts>
</response>
</instructions>
</yes>
<no>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Could not process Txn. Please tryagain.</textmessage>
</text>
</texts>
</response>
</instructions>
</no>
</matches>
</instructions>
</option>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Cancel</textmessage>
</text>
</texts>
</display>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Thank you for using MoMo PayTV.</textmessage>
</text>
</texts>
</response>
</instructions>
</option>
</optionslist>
</options>
-
JSON Request
{
"arguments": p
{
"key": {
"value": "card_number"
},
"value": {
"value": "10"
}
},
{
"key": {
"value": "card_provider_code"
},
"value": {
"value": "10001"
}
},
{
"key": {
"value": "amount"
},
"value": {
"value": "20000"
}
},
{
"key": {
"value": "ACCOUNT_HOLDER_MSISDN"
},
"value": {
"value": "256772123312"
}
}
],
"languageCode": "EN",
"sessionIdentifier": "3bbbed98-ee5f-4c05-ac40-ac8b8db8cbb6",
"journeyIdentifier": "1489dbe9-8838-4783-93dc-20e0221ab3fd"
}
-
JSON Response
{
"arguments": /
{
"key": {
"value": "payment_request_status"
},
"value": {
"value": "initiated"
}
}
]
}
Complete Journey
<?xml version="1.0" encoding="UTF-8"?>
<op:journeydefinition xmlns:op="http://www.ericsson.com/em/djs/journey/v1_0/common/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<instructions>
<!-- STEP 1: Show dynamic options of available Pay TV Providers-->
<dynamicoptions>
<!-- Header Text-->
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Welcome to MoMo Pay TV Services</textmessage>
</text>
</texts>
</header>
<!-- Template for displaying the different options returned -->
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>${provider_name}</textmessage>
</text>
</texts>
</display>
<!-- URL on service provider system for returning the dynamic option argument values -->
<url>https://api.serviceprovider.com/providers</url>
<!-- Arguments to be sent in the API call to service provider system to fetch the values -->
<arguments>
<argument>
<key>all</key>
<value>provider_category</value>
</argument>
</arguments>
</dynamicoptions>
<!-- STEP 2: After selecting the Provider, Prompt user to enter Card Number -->
<question>
<key>card_number</key>
<retries>2</retries>
<confidential>false</confidential>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Enter ${provider_name} Card Number</textmessage>
</text>
</texts>
</display>
<validation>
<pattern>\d+</pattern>
<errormessage>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Enter Valid Card Number.</textmessage>
</text>
</texts>
</errormessage>
</validation>
</question>
<!-- STEP 3 -->
<!-- Step 3: Send request with details of card number for validation on provider API-->
<dynamicarguments>
<url>https://api.serviceprovider.com/card-validation</url>
<arguments>
<argument>
<key>provider_code</key>
<value>${provider_code}</value>
</argument>
<argument>
<key>card_number</key>
<value>${card_number}</value>
</argument>
</arguments>
</dynamicarguments>
<!-- STEP 4: Display returned card details and Prompt user to enter amount to pay -->
<question>
<key>amount</key>
<retries>2</retries>
<confidential>false</confidential>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Payment for Card Number ${card_number} Name ${card_owner} Enter Amount to Pay</textmessage>
</text>
</texts>
</display>
<validation>
<pattern>\d+</pattern>
<errormessage>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Invalid Amount.</textmessage>
</text>
</texts>
</errormessage>
</validation>
</question>
<!-- STEP 5: Display confirmation message and Prompt user to confirm action -->
<options>
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Payment request of amount UGX ${amount} for ${card_number} Name ${card_owner}</textmessage>
</text>
</texts>
</header>
<optionslist>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Confirm</textmessage>
</text>
</texts>
</display>
<instructions>
<dynamicarguments>
<!-- Send confirm details to server for processing -->
<url>https://api.serviceprovider.com/post-payment</url>
<arguments>
<argument>
<key>card_number</key>
<value>${card_number}</value>
</argument>
<argument>
<key>card_provider_code</key>
<value>${card_provider_code}</value>
</argument>
<argument>
<key>amount</key>
<value>${amount}</value>
</argument>
</arguments>
</dynamicarguments>
<matches>
<!-- handle response from server for post payment -->
<key>payment_request_status</key>
<pattern>initiated</pattern>
<yes>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Thank for you for using our Services. Please approve the transaction when prompted to complete the payment
</textmessage>
</text>
</texts>
</response>
</instructions>
</yes>
<no>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Could not process Txn. Please tryagain.</textmessage>
</text>
</texts>
</response>
</instructions>
</no>
</matches>
</instructions>
</option>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Cancel</textmessage>
</text>
</texts>
</display>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Thank you for using MoMo PayTV.</textmessage>
</text>
</texts>
</response>
</instructions>
</option>
</optionslist>
</options>
</instructions>
</op:journeydefinition>