# Request Mobile Money Payment ## Overview The currently supported mobile money channels are listed [here](https://apidoc.govbill.ug/getting-started/supported-countries) (to be updated from time to time). Test mobile money phone numbers are also described in [this](https://apidoc.govbill.ug/getting-started/sandbox-test-accounts) section. We equally recommend that you go through the [Getting Started](https://apidoc.govbill.ug/collections/getting-started) section to have a high-level understanding of the funds collection process. ## Step 1: Form payload for collection request 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, whether or not you wish to trigger the confirmation process by yourself).
ParameterTypeRequiredDescription
merchant_referenceStringtrueThe unique reference for this request. Alternatively, the value auto can be passed and a reference will be created for you by the platform
transaction_methodStringtrueThe transaction method to be used. This will be MOBILE_MONEY for this request
provider_codeStringtrueThe provider code as obtained from the payment options list the previous section
currencyStringtrueThe 3 character ISO currency code for the request currency
amountNumbertrueThe amount being requested
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. Defaults to false if the parameter is not set explicitly
require_confirmationBooleanfalseWhether or not the requesting merchant account wishes to explicitly do the second step (confirmation). Currently defaults to true
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.govbill.ug/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.govbill.ug/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 When the request has been acknowledged for processing" %} ```json { "code": 202, "status": "accepted", "message": "Request Accepted", "data": { "internal_reference": "GOVBILEPRRU9UVPDCDP3", "merchant_reference": "MCTREF5VE628T8SE95L9" } } ``` {% endtab %} {% tab title="400: Bad Request When the request is not formed as expected" %} ```javascript { "code": 400, "status": "error", "message": "256752000001 is not a valid MTN Mobile Money Uganda (mtn_momo_ug) phone number", "data": {} } ``` {% endtab %} {% endtabs %} ## Step 2: Transaction confirmation - Optional If in step 1 you chose that you wish to explictly handle the request confirmation, then it becomes mandatory that you send the transaction confirmation API request. If the request in step 1 is successful and responds with an acknowledgement (HTTP code 202), you should listen and handle the transaction charges webhook/callback. This will be sent to the collection callback URL that's configured on your merchant account. The callback is sent as a JSON POST request and we recommend that the confirmation request is done after the arrival of this callback. Below is a sample payload. ```json { "event": "transaction.charges", "payload": { "id": 266, "merchant_reference": "MCTREF4DRQGLN9RZVCYH", "internal_reference": "GOVBILEPRRU9UVPDCDP3", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 40000, "transaction_currency": "UGX", "transaction_charge": 1200, "transaction_account": "256777000001", "charge_customer": false, "total_credit": 38800, "provider_code": "mtn_momo_ug", "request_amount": 40000, "institution_name": "MTN Mobile Money Uganda", "customer_name": "JOHN DOE", "transaction_status": "PENDING", "status_message": "Collection initialized successfully. Confirm charges" } } ``` {% hint style="info" %} This payload allows you a chance to display the charge and final transaction amount to the end user. The **transaction\_amount** is the actual amount to be debited/deducted from the customer's mobile money account. You can then execute the confirmation request as described below. The request takes a single parameter, ***internal\_reference*** {% endhint %} `POST` `https://gwapisdbx.govbill.ug/collections/confirm` ```powershell curl -X POST "https://gwapisdbx.govbill.ug/collections/confirm" \ -H 'Content-Type: application/json' \ -H "x-api-version: 1" \ -H "public-key: your-public-key" \ -d '{ "internal_reference": "GOVBILEPRRU9UVPDCDP3" }' ``` The confirmation request will respond with an acknowledgement just like in Step 1 above. In the background, the platform will go ahead to send a PIN prompt to the user to approve the transaction. ## Step 3: Handle the 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](https://apidoc.govbill.ug/utility-functions/handling-notifications-callbacks) 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": 20760, "merchant_reference": "MCTREFT2WMNWZ23SBN6Y", "internal_reference": "GOVBILEPRRU9UVPDCDP3", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 2000000, "transaction_currency": "UGX", "transaction_charge": 60000, "transaction_account": "256777000001", "charge_customer": false, "total_credit": 1940000, "provider_code": "mtn_momo_ug", "request_amount": 2000000, "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": 26609, "merchant_reference": "MCTREFNRFRTQA6SCWT5X", "internal_reference": "GOVBILEPRRU9UVPDCDP3", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 2000000, "transaction_currency": "UGX", "transaction_charge": 0, "transaction_account": "256777000002", "charge_customer": false, "total_credit": 0, "provider_code": "mtn_momo_ug", "request_amount": 2000000, "customer_name": "JOHN DOE", "transaction_status": "FAILED", "status_message": "Balance Insufficient for the transaction" } } ``` {% endtab %} {% endtabs %}