The MTN MoMo Payment Gateway add-on accepts mobile money payments from MTN Mobile Money users across Africa — integrating with the MTN MoMo Collections API to create “Request to Pay” transactions, enabling customers to approve payments directly from their phones.
Pricing: This is a paid add-on, available from the Larapen Marketplace.
Key Features
- Request to Pay — Initiate payment requests that customers approve via USSD prompt on their MTN phone. No credit card required.
- Sandbox provisioning — One-click generation of sandbox API credentials (API User ID and API Key) directly from the admin panel. Only the Subscription Key is needed to start.
- Real-time polling — Automatic payment status polling with progress bar while the customer approves on their phone. Webhook support for production environments.
- Encrypted credentials — All API credentials (Subscription Key, API User ID, API Key) are encrypted at rest using Laravel’s Crypt facade. Never stored in plain text.
- Country-specific environments — Supports Uganda, Ghana, Cameroon, Ivory Coast, Benin, Congo, and Liberia with country-specific target environments and currencies.
- Connection testing — Test Key button performs a diagnostic API call to verify the Subscription Key is valid before saving.
- Polymorphic payables — Works with any model implementing the
Payablecontract, not limited to shop orders. - Payment gateway contract — Implements the Larapen
PaymentGatewayInterface, integrating seamlessly with the E-Shop checkout flow.
Admin Panel
| Section | Description |
|---|---|
| Settings | Configure API credentials (Subscription Key, API User ID, API Key), environment (sandbox/production), target environment, currency, and callback host. All sensitive keys stored encrypted. |
Payment Flow
- Customer selects “MTN Mobile Money” at checkout and enters their MoMo phone number.
- The gateway obtains an OAuth2 Bearer token from MTN and sends a “Request to Pay”.
- Customer receives a USSD prompt on their MTN phone and enters their PIN to approve.
- Frontend polls payment status every 5 seconds with a progress bar.
- On success, the order is confirmed and marked as paid. In production, webhooks provide a reliable backup.
Country Environments
| Country | Target Environment | Currency |
|---|---|---|
| Uganda | mtnuganda | UGX |
| Ghana | mtnghana | GHS |
| Cameroon | mtncameroon | XAF |
| Ivory Coast | mtnivorycoast | XOF |
| Benin | mtnbenin | XOF |
| Congo | mtncongo | XAF |
| Liberia | mtnliberia | LRD |
| Sandbox | sandbox | EUR |
Configuration
| Setting | Description |
|---|---|
| Subscription Key | Ocp-Apim-Subscription-Key from the MTN MoMo developer portal Profile page. Stored encrypted. |
| API User ID | UUID v4 generated during sandbox provisioning or obtained from MTN Partner Portal. Stored encrypted. |
| API Key | Generated from the API User. Stored encrypted. |
| Environment | sandbox or production. Determines which MTN API base URL is used. |
| Target Environment | sandbox for testing, or a country-specific code for production (e.g., mtnuganda). |
| Currency | Must be EUR in sandbox. Country-specific in production (see table above). |
| Callback Host | Your domain for receiving webhook callbacks (production only). Must support HTTPS. |
Refunds
The MTN MoMo Collections API does not provide a refund endpoint. Refunds must be processed manually through the MTN MoMo Partner Portal or via the separate Disbursements API.
Dependencies
Required: The E-Shop add-on must be installed and active. The MoMo add-on registers as a payment gateway via the PaymentGatewayInterface contract and is automatically discovered by the shop’s payment system.
Setup Guide
- Install and activate the E-Shop add-on first.
- Install and activate the MTN MoMo add-on.
- Create an account at momodeveloper.mtn.com and subscribe to the Collections product.
- Go to MTN MoMo > Settings in the admin panel.
- Enter your Subscription Key and use the Generate API Credentials button for sandbox testing.
- For production, obtain credentials from the MTN MoMo Partner Portal and set the country-specific target environment.
- MTN MoMo will appear as a payment option during checkout.
Ideal for
- E-commerce sites targeting customers in African markets where MTN MoMo is widely used.
- Businesses in Cameroon, Ghana, Uganda, Ivory Coast, Benin, Congo, and Liberia.
- Mobile-first markets where customers prefer mobile money over credit card payments.
- Digital product sellers reaching mobile money users across Africa.