# Request Mobile Money Payment

Expand the following section to view how the mobile money request is set up to debit funds from the customer's mobile money account. When the request is valid, the API responds with an acknowledgement; details of the transaction e.g. the charges together with a unique reference from the platform, which will subsequently be used for the confirmation.

<mark style="color:green;">`POST`</mark> `https://sandbox-api.govbill.ug/v1/collections/initialize`

The operation initiates a funds request from the customer's mobile money wallet. The request is sent as a JSON body

#### Headers

| Name                                           | Type   | Description                                        |
| ---------------------------------------------- | ------ | -------------------------------------------------- |
| public-key<mark style="color:red;">\*</mark>   | String | The Public Key as obtained from the approval email |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json                                   |

#### Request Body

| Name                                                  | Type   | Description                                                                                                                                                                                                      |
| ----------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| merchant\_reference<mark style="color:red;">\*</mark> | String | The unique reference for this request. It should be unique for every single request. Alternatively, the value **auto** can be passed and a reference will be created for you by the platform                     |
| currency<mark style="color:red;">\*</mark>            | String | The 3 character ISO currency code for the request currency                                                                                                                                                       |
| amount<mark style="color:red;">\*</mark>              | float  | The amount being requested                                                                                                                                                                                       |
| provider\_code<mark style="color:red;">\*</mark>      | String | The provider code as obtained from the payment options [list](/utility-functions/payment-options.md#get-payment-options-list) the previous section                                                               |
| msisdn<mark style="color:red;">\*</mark>              | String | The phone number from which the payment is being requested. This should be sent in international format e.g. 256777000001 for Ugandan numbers                                                                    |
| description                                           | String | The description/narration for the transaction                                                                                                                                                                    |
| customer\_name<mark style="color:red;">\*</mark>      | String | The name of the customer                                                                                                                                                                                         |
| transaction\_method<mark style="color:red;">\*</mark> | String | The transaction method to be used. Allowed values are those returned for the **transaction\_method** parameter in the payment options [response](/utility-functions/payment-options.md#get-payment-options-list) |

{% tabs %}
{% tab title="202: Accepted When the request has been acknowledged for processing" %}

```json
{
	"code": 202,
	"status": "accepted",
	"message": "Transaction Initiated. Pending Customer Confirmation",
	"data": {
		"id": 5742,
		"merchant_reference": "CSTREFYSCJBGSCSSMN2N",
		"internal_reference": "GOVBILGBHCVVGFZ6VFRFYJ",
		"transaction_type": "COLLECTION",
		"request_currency": "UGX",
		"request_amount": 80000,
		"transaction_currency": "UGX",
		"transaction_amount": 80000,
		"transaction_fee": 2000,
		"charge_customer": false,
		"total_credit": 78000,
		"provider_code": "mtn_momo_ug",
		"transaction_status": "PENDING",
		"status_message": "Transaction Initiated"
	}
}
```

{% 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": {
    "internal_reference": "GOVNETQJ7CA7ESLZCRBXSX"
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On acknowledgement, the **internal\_reference** returned as part of the data is crucial for the next step of the process. This 1st step 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.
{% endhint %}


---

# 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://docs.govbill.ug/collections/request-mobile-money-payment.md?ask=<question>
```

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.