Skip to main content

Popular articles

MoMo API Common Errors

RESOURCE_ALREADY_EXIST HTTP 409 ACCESS DENIED DUE TO INVALID SUBSCRIPTION KEY 401 RESOURCE NOT FOUND 404 REQUEST REJECTED/ BAD REQUEST FORBIDDEN IP 403 NOT_ALLOWED 500 NOT_ALLOWED_TARGET_ENVIRONMENT 500 INVALID_CALLBACK_URL_HOST 500 INVALID_CURRENCY 500 INTERNAL_PROCESSING_ERROR 500 SERVICE_UNAVAILABLE 503 PAYEE_NOT_FOUND PAYER_NOT_FOUND COULD_NOT_PERFORM_TRANSACTIONRESOURCE_ALREADY_EXIST HTTP 409Duplicated Reference ID.Every request must have a unique reference ID; using an ID of the previous request will result in this error responseAction-Check X-Reference ID used is unique and is in UUID V4 formatACCESS DENIED DUE TO INVALID SUBSCRIPTION KEY 401Authentication failed.Credentials invalid.Header Ocp-APIM-Subscription-Key value is incorrect.Action -  Check the User Profile Section to verify the related product subscription key is used. Collection, Disbursement and Remittance have different subscription keys. If the primary key doesn’t work, try the secondary key. Contact MTN support if both provided keys aren't working. Sandbox subscription key are located in  https://momodeveloper.mtn.com/developer Production subscription key are located in https://momoapi.mtn.com/developer   RESOURCE NOT FOUND 404 Reference ID not found. Requested resource does not exist. Predominantly occurs with Get Status API and implies that the requested reference ID does not exist. This results in the Request to Debit or Transfer transaction being unsuccessful. Action - Check if the original request to pay or the transfer (disbursement) operation was successful with response code 202. REQUEST REJECTED/ BAD REQUEST 400 Bad request. Request does not follow the specification. Action This relates to any of the below scenarios: Incorrect/wrong values in the headers, and/or the X-ref ID does not meet UUID Version 4. Inputting a Body in an API that is not supported e.g. /Token API Having unsupported special characters in the Body request for example an apostrophe ('). Invalid currency – needs to match the target environment currency. More than 160 characters in the note and message; explore utilizing the notification API for increased number of characters. The URL posted to needs to reviewed e.g.  incorrect number of forward slashes (///).   FORBIDDEN IP 403 Authorization failed. IP not authorized to utilize Disbursement API. Action  Share your originating Public IP from which the APIs are called with your MTN Account Manager NOT_ALLOWED 500Authorization failed. User does not have permission.The account authenticated with the Request via Token is restrictedAction - Contact your MTN Account ManagerNOT_ALLOWED_TARGET_ENVIRONMENT 500 Value passed in header X-Target-Environment is incorrect Action -  Use the correct X-targetenvironment corresponding to below country: MTN Uganda= mtnuganda MTN Ghana= mtnghana MTN Ivory Coast= mtnivorycoast MTN Zambia= mtnzambia MTN Cameroon= mtncameroon MTN Benin= mtnbenin MTN Congo= mtncongo MTN Swaziland= mtnswaziland MTN GuineaConakry= mtnguineaconakry MTN SouthAfrica= mtnsouthafrica MTN Liberia= mtnliberia For Test Environment = sandbox INVALID_CALLBACK_URL_HOST 500 Callback URL with different host name to configured for API User. Check the Host of the Call Back URL in the request header; this needs to match what was configured on the partner portal when creating the API user and Key. Action -Host needs to be configured using Hostname and not IP address. INVALID_CURRENCY 500Currency not supported on the requested accountAction - Use Currency Code specific to the Country.INTERNAL_PROCESSING_ERROR 500 Default or Generic error code used when there is no specific error mapping. This predominantly occurs due to insufficient customer funds to complete the transaction. Also related to service denied or Wallet Platform is not reachable Action : Advice customer to ensure they have sufficient funds to complete the transaction. Also request the customer to retry the transaction. If the problem still occurs with sufficient customer funds, please contact your MTN Account Manager for further investigation   SERVICE_UNAVAILABLE 503Service temporary unavailable - please try againAction - Enquire with MTN Support. PAYEE_NOT_FOUND The MSISDN being paid to is invalid. Action -  MSISDN format must include country code. MSISDN is not registered for Mobile Money Service. PAYER_NOT_FOUND MSISDN of the number from whom the money was requested in invalid Action-  MSISDN format must include country code. MSISDN is not registered for Mobile Money Service. COULD_NOT_PERFORM_TRANSACTION This can be attributed to transaction timeout. This predominantly occurs with a delay to approve a transaction within the given time frame (5 minutes). Action- Advise customer to try again and approve transaction within 5 minutes.  

Dynamic Journey USSD

Dynamic Journey Service Programmers Guide

Journey Definition Overview Journey Definition Instructions Instruction Session Data Instructions Argument dynamicarguments User Input Instructions Question Options dynamicoptions Journey Definition OverviewThe journey definition is a structured group of instructions that form an acyclicgraph and is described in XML syntax.During execution of the journey, this graph is traversed based on chosen optionsand input data retrieved from user interaction. The journey execution ends whena response instruction is reached. This will give the result of the journey.The chapters below describe the different entities of the XML syntax used tospecify a journey for execution on EWP.Journey Definition InstructionsJourneyJourney is the root element of a journey definition.Table 1 ElementsName Type Description journey list<instruction> The list of top-level instructions for a journey. Execution starts with the first instruction of this list.  Instructionare the building blocks for a journey definition that specify the behavior duringjourney execution.Some instructions may refer to other instructions, creating a parent-childrelationship.Once an instruction is executed, its children instructions will be executedrecursively in a depth first strategy, and then another instruction in the same levelas the parent instruction will execute.The following instruction types are defined:— argument— dynamicargument— question— options— dynamicoptions— exists— matches— switch— response— responsematchingThe available set of instructions is below grouped into instructions for user input,session data, control flow and session finalization. The following chaptersdescribe each of the listed instruction types in detail.Session Data InstructionsThe instructions in this section can be used to store data for the ongoing session.Any data that is captured during journey execution is stored as key value pairscalled arguments.These arguments can be referred to from all instructions, the syntax ${argument-key} is during execution resolved to the argument-value stored forthe given argument-key.ArgumentPurposeThe argument instruction is used to add data to the user session so it can beretrieved later by other instructionsThe data to be stored is a key and avalue pair, see Table 2.Any previous value that was associated to the same key will be overwritten.Table 2 ElementName Type Description Key argumentkey The key of the argument. Value textformat The value to be set for the given argument.  <argument><key>yearofbirth</key><value>1990</value></argument><argument><key>yearssincebirth</key><value>${age}</value></argument>Example ExplanationThe argument with key yearofbirth will be added to the user session, with thevalue of 1990.The argument with key yearssincebirth will be added to the user session, withthe value contained in the argument with key ${age}.If no argument is found an error will be thrown.dynamicargumentsPurposeTo get arguments from a service provider to be added to the user session.This instruction causes a request with a set of arguments being sent to a givenURL. In response a set with arguments is received that will be added to the usersession.The request is synchronous and journey execution will halt until response isreceived or time-out.With this construction, it is possible to pass user input onto the service providerfor further processing.The arguments sent in response could be used to control the execution path ofthe journey or they could be used in response to the end user.Table 3 ElementsName Type Description url uniformResourceLo cator The URL to which the request should be sent. arguments list<argument> Arguments (key, value) that are to be sent as payload to the specified URL. <dynamicarguments><url>https://provider-gateway.com/djs/dynamicarguments?get</url →><arguments><argument><key>username</key><value>Walden</value></argument><argument><key>age</key><value>${age}</value></argument><arguments></dynamicarguments>Example ExplanationA request with the arguments username and age will be sent to https://providergateway.com/djs/dynamicarguments?get.The Username has value Walden, and age has the value of age argument fromthe user session.All data received in the response from the service provider will be added to thesession. If no argument with the key age is found, an error will be thrown.User Input InstructionsThis set of instructions allows for gathering input data from the user.The journey execution proceeds until a user input instruction is reached, then ithalts and returns a response to be used by the client application to prompt theuser for input data.The client should enter the required user input to continue the execution of thejourney.QuestionTo present a question to the user and to retrieve a corresponding answer.When a question instruction is encountered, the journey execution is paused, andthe question is prompted to the user.The client should then resume the journey execution by sending an answer to thequestion in a new request.Note: It is important to flag questions as confidential if the expected answermay contain confidential data, otherwise the received answer could beexposed in log files.Name Type M/O Description  Key argumentkey M Key of the argument that will hold the answer. retries long O The maximum number of retry attempts in case an invalid answer was given. Maximum value: 5 confidential boolean M A flag indicating whether the answer contains confidential data (confidential data will not be exposed in logs). display display M The question to be presented to the user (display, consisting of text and language code). validation validation O Pattern given as regular expression to be applied on the answer (optional) answers not following the pattern will be rejected with error message. transform transform O Transformation pattern to be applied on the answer (optional), for example, can be used to apply a prefix to the answer. <question><key>username</key><retries>3</retries><confidential>false</confidential><display><texts><text><languagecode>en</languagecode><textmessage>Please enter your name</textmessage></text></texts></display><validation><pattern>[a-zA-Z]+</pattern><errormessage><texts><text><languagecode>en</languagecode><textmessage>Only letters allowed.</textmessage></text></texts></errormessage></validation><transform><format>Name: ${username}</format></transform></question>Example ExplanationA question will be prompted to the user, its answer will be stored in an argumentwith the key username. The question is not confidential, so the answer willappear in the audit logs.The text Please enter your name will be displayed to the user case itspreferred language is English, or DJS will prompt an error stating that there is notext for the user's language, and the session will be terminated.The answer will be validated against the [a-zA-Z]+ regular expression.If the answer is valid, its value will be transformed into the string: Name: ${username}, and ${username} is the placeholder that will be replaced with thevalue which has been just entered by the user.After the transformation, which is optional, the value will be stored as anargument in the session with the key username.If the answer is invalid, the user will have three others retry attempts. If all theretry attempts fail, the session will be terminated, and an error will be promptedto the user.In every retry attempt, an error message with the text Only letters allowed.is displayed to the user if it has preferred language as English, or DJS will promptan error stating that there is no text for the user's language, and the session willbe terminated.OptionsA list of options to be presented to the user, who may select only one choice. Thisis kind of a (sub)-menu presented to the user.When a choice is selected, the set of instructions associated to it will be executed.This set of instructions can include any instruction, including other optionsinstruction.When an options instruction is encountered, the journey execution is paused, andthe available options are prompted to the user.The client should then resume the execution by sending an answer containing thechosen option in a new request.This is explained in detail in the API section of this document.Name Type M/O Description  header  display O A header to be displayed on top of the list of options. footer display O A footer to be displayed at the bottom of the list of options. option list<option> M The list of options to choose from.  Name Type M/O Description display display M Text presented to the user to describe an option instructions list<instruction> M The instructions to be executed if this choice is made. Mandatory, but the list can be empty.  <options><header><texts><text><languagecode>en</languagecode><textmessage>Final Confirmation</textmessage></text></texts></header><optionslist><option><display><texts><text><languagecode>en</languagecode><textmessage>Purchase product</textmessage></text></texts></display><instructions><response><texts><text><languagecode>en</languagecode><textmessage>Your order has been placed</textmessage></text></texts></response></instructions></option><option><display><texts><text><languagecode>en</languagecode><textmessage>Cancel</textmessage></text></texts></display><instructions><response><texts><text><languagecode>en</languagecode><textmessage>Order cancelled</textmessage></text></texts></response></instructions></option></optionlist></options>Example ExplanationA set of options will be prompted to the user.There is a header to explain what the options are, and if the user has English aspreferred language, the text will be Final Confirmation.Two options will be displayed, one called Purchase product, the other one calledCancel.If the first option is chosen, a response instruction will run and show the textYour order has been placed to the user.If the second option is chosen, a response instruction will run and show the textOrder cancelled to the user.dynamicoptionsDynamic options work in an analogous way as options, but instead of havingpre-defined options written in the journey definition, the options can bedynamically fetched during the journey execution. This makes it possible tocustomize the options for each user based on either provided user input or otheruser preferences.When this instruction is encountered, a list of set of arguments is retrieved fromthe specified URL. Each option is comprised by a set of arguments, and youreceive a list of options, thus a list of set of arguments. An option in the dynamicoptions can only contain the argument instruction. Except for the default option,which can contain any instruction and it is pre-defined in the journey definition.The default option will be chosen automatically if no options are given by theservice provider. If no options are received and there is no default option, an errorwill be thrown.Analogous to dynamic arguments, you can specify arguments in the request,enabling the service provider to customize the response.There is only one display text in dynamic options, and this will be used to renderevery option. This display text should contain placeholders that will besubstituted by the set of arguments that exists for each option.When a dynamic options instruction is encountered, the journey execution ispaused, and the available options are prompted to the user. The client shouldthen resume the execution by sending an answer containing the chosen option ina new request. This is explained in detail in the API section of this document.When the option is chosen, each argument in the option's set of arguments isstored in the session.Name Type M/O Description  header display O A header displayed on top of the list of options. footer display O A footer displayed at the bottom of the list of options url uniformResourceLoca tor M The URL to which the request should be sent. display display M Text presented to the user to describe an option this serves as a template for each option and will be rendered with the arguments retrieved from URL.   arguments list<argument> M A list of arguments (key, value) that are to be sent to the specified URL. defaultoption option O A default option to be applied in case no options were received <dynamicoptions><header><texts><text><languagecode>en</languagecode><textmessage>Special Offers</textmessage></text></texts></header><footer><texts><text><languagecode>en</language><textmessage>Please select one of the options above</textmessage></text></texts></footer><url>https://provider-gateway.com/djs/dynamicoptions?get</url><display><texts><text><languagecode>en</languagecode><textmessage>Your bonus of ${amount} with validity of ${validity}</textmessage></text></texts></display><arguments><argument><key>campaign</key><value>summerspecial</value></argument><argument><key>code</key><value>${customkey}</value></argument></arguments></dynamicoptions>Example ExplanationA list of options will be retrieved from https://provider-gateway.com/djs/dynamicoptions?getTwo arguments will be sent to the provider: campaign, with the valuesummerspecial, and code, with the value contained in the argument with keycustomkey.If no options are received, an error will be thrown, since there is no default option.A header will be displayed with the text Special Offers, and a footer with the textPlease select one of the options above.A list of options will be displayed, substituting the argument templates for theones received in the response. One example of the list could be:— Your bonus of 10USD with validity of 1 month— Your bonus of 50USD with validity of 3 months

Terms & ConditionsCookie settingsAccessibility statement