# Mobile Money Collection ## Overview The currently supported mobile money channels are listed [here](/getting-started/supported-countries.md) (to be updated from time to time). Test mobile money phone numbers are also described in [this](/getting-started/sandbox-test-accounts.md) section. We equally recommend that you go through the [Getting Started](/funds-collection/getting-started.md) section to have a high-level understanding of the funds collection process. ## Step 1: Form the collection request payload The table below describes the request parameters that are used for the collection request. Most will be collected from the paying customer and some are custom configurations based on your wishes (e.g. who bears the transaction charge).
ParameterTypeRequiredDescription
merchant_referenceStringtrueThe unique reference for this request. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API
transaction_methodStringtrueThe transaction method to be used. This will be MOBILE_MONEY for this request
currencyStringtrueThe 3-character ISO currency code for the request currency
amountNumbertrueThe amount being requested
provider_codeStringtrueThe provider code as obtained from the payment options list
msisdnStringtrueThe phone number from which the payment is being requested. This should be sent in international format e.g. 256777000001 for Ugandan numbers
customer_nameStringtrueThe name of the customer
customer_emailStringfalseThe email of the customer
descriptionStringfalseThe description/narration for the transaction
charge_customerBooleanfalseWhether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge
After collecting the necessary mobile money payment information from your customer, prepare your request payload as demonstrated below. ```json { "merchant_reference": "auto", "transaction_method": "MOBILE_MONEY", "currency": "UGX", "amount": 10000, "provider_code": "mtn_momo_ug", "msisdn": "256777000001", "customer_email": "johndoe@gmail.com", "customer_name": "JOHN DOE", "description": "Test Collection", "charge_customer": false } ``` `POST` `https://gwapisdbx.ellypayapp.com/collections/initialize` The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared. ```powershell curl -X POST "https://gwapisdbx.ellypayapp.com/collections/initialize" \ -H 'Content-Type: application/json' \ -H "x-api-version: 1" \ -H "public-key: your-public-key" \ -d '{ "merchant_reference": "auto", "transaction_method": "MOBILE_MONEY", "currency": "UGX", "amount": 10000, "provider_code": "mtn_momo_ug", "msisdn": "256777000001", "customer_email": "johndoe@gmail.com", "customer_name": "JOHN DOE", "description": "Test Collection", "charge_customer": false, }' ``` {% tabs %} {% tab title="202: Accepted - Request acknowledged for processing" %} ```json { "code": 202, "status": "accepted", "message": "Request Accepted", "data": { "internal_reference": "ELPREFA65BGTFR7NGUXM", "merchant_reference": "MCTREFNGKLP5VQCQSBH2" } } ``` {% endtab %} {% tab title="400: Bad Request - Request is not formed as expected" %} ```json { "code": 400, "status": "error", "message": "256752000001 is not a valid MTN Mobile Money Uganda (mtn_momo_ug) phone number", "data": {} } ``` {% endtab %} {% endtabs %} ## Step 2: Handle intermediate notifications - Optional You can optionally handle/listen to the intermediate callbacks that are sent, as some form of tracking the transaction progress. These callbacks/notifications are described in [this](/funds-collection/getting-started.md#handling-other-callbacks-optional) section of the getting-started manual. ## Step 3: Handle final status notification Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out [Handling Notifications](/utility-functions/handling-notifications-callbacks.md) to see how you should verify the signature(s) in the request headers and how to respond. {% tabs %} {% tab title="Successful Mobile Money Collection" %} ```json { "event": "transaction.completed", "payload": { "id": 11832, "merchant_reference": "MCTREFNGKLP5VQCQSBH2", "internal_reference": "ELPREFA65BGTFR7NGUXM", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 100000, "transaction_currency": "UGX", "transaction_charge": 4000, "transaction_account": "256777000001", "charge_customer": false, "total_credit": 96000, "provider_code": "mtn_momo_ug", "request_amount": 100000, "institution_name": "MTN Mobile Money Uganda", "customer_name": "JOHN DOE", "transaction_status": "COMPLETED", "status_message": "Transaction Completed Successfully" } } ``` {% endtab %} {% tab title="Failed Mobile Money Collection" %} ```json { "event": "transaction.failed", "payload": { "id": 11832, "merchant_reference": "MCTREFNGKLP5VQCQSBH2", "internal_reference": "ELPREFA65BGTFR7NGUXM", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 100000, "transaction_currency": "UGX", "transaction_charge": 0, "transaction_account": "256777000001", "charge_customer": false, "total_credit": 0, "provider_code": "mtn_momo_ug", "request_amount": 100000, "institution_name": "MTN Mobile Money Uganda", "customer_name": "JOHN DOE", "transaction_status": "FAILED", "status_message": "Balance Insufficient for the transaction" } } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.ellypayapp.com/funds-collection/mobile-money-collection.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.