| Parameter | Type | Required | Description |
|---|---|---|---|
| merchant_reference | String | true | The unique reference for this request. It must be at least 8 characters long. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API |
| transaction_method | String | true | The transaction method to be used. This will be MOBILE_MONEY for this request |
| currency | String | true | The 3-character ISO currency code for the request currency |
| amount | Number | true | The amount being requested |
| provider_code | String | true | The provider code as obtained from the payment options list |
| msisdn | String | true | The phone number from which the payment is being requested. This should be sent in international format e.g. 256777000001 for Ugandan numbers |
| customer_name | String | false | The name of the customer |
| customer_email | String | false | The email of the customer |
| description | String | true | The description/narration for the transaction. Between 10-30 characters |
| charge_customer | Boolean | false | Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge |
| allow_final_status_change | Boolean | false | Whether or not the final transaction status can be altered as described here. By default, this is true to mean Elemi will alter the final transaction status under the circumstances described. |
You will receive a prompt on the mobile number 256777000001.
Enter your PIN to authorize your payment of UGX 5,000
Authorize Payment using the OTP sent to 233545503456.
" } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Pay close attention to the `authorization.mode` parameter. When the value is **NONE**, the merchant should simply display the instructions in the `payment_instructions` parameter. In this scenario, the customer should expect a PIN approval prompt from the telecom. If the mode is **OTP**, it means the OTP has been sent to the phone number and the merchant needs to call another endpoint to submit the OTP and authorize the transaction to proceed as described in step 3 below. {% endhint %} ## Step 3: Authorize the transaction (Optional) If the payment instructions webhook in step 2 above is sent, the transaction status being PROCESSING and the authorization mode is OTP, this means the OTP has been set to the customer's phone number. The merchant therefore needs to collect the OTP from the customer and submit it in order to verify the phone number and authorize the transaction to proceed. The parameter `authorization.required_parameters` holds an object array of the parameters the merchant should obtain and submit. In every object, `parameter_name` is the name of the parameter that's going to carry the required value (OTP in this case). Form the payload as demonstrated in the sample request below. `POST` `https://sandbox.elemitech.com/collections/authorize` ```powershell curl -X POST "https://sandbox.elemitech.com/collections/authorize" \ -H 'Content-Type: application/json' \ -H "x-api-version: 1" \ -H "public-key: your-public-key" \ -d '{ "internal_reference": "ELEMISTPDKZ6MLY5WPQ", "otp": "012345" }' ``` If OTP verification is successful, a PIN prompt will be sent to the mobile money phone number in the request for the customer to approve the transaction. If the customer has sufficient balance for the transaction and is eligible to transact, the request will be successful otherwise the API will send an appropriate error message as shared by the telecom. ## Step 4: Handle the final status webhook 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": 20760, "merchant_reference": "MCTREFT2WMNWZ23SBN6Y", "internal_reference": "ELEMIRMGRXNNYBWATKJ", "transaction_type": "COLLECTION", "request_currency": "UGX", "transaction_amount": 2000000, "transaction_currency": "UGX", "transaction_charge": 60000, "transaction_account": "256787008803", "charge_customer": false, "total_credit": 1940000, "provider_code": "mtn_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": "ELEMIWYUF8CR3ZRCGYU", "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_ug", "request_amount": 2000000, "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://docs.elemitech.com/funds-collection/mobile-money-collection/mobile-money-direct-charge.md?ask=