MTN MoMo¶

The MTN Mobile Money driver supports Collections (RequestToPay) and Disbursements (Transfer). Collection and payout credentials are separate, and both flows are asynchronous.

Setup¶

MTNMOMO_COLLECTION_USER_ID=collection_api_user
MTNMOMO_COLLECTION_API_KEY=collection_api_key
MTNMOMO_COLLECTION_SUBSCRIPTION_KEY=collection_subscription_key
MTNMOMO_DISBURSEMENT_USER_ID=disbursement_api_user
MTNMOMO_DISBURSEMENT_API_KEY=disbursement_api_key
MTNMOMO_DISBURSEMENT_SUBSCRIPTION_KEY=disbursement_subscription_key
MTNMOMO_ENVIRONMENT=sandbox
MTNMOMO_CURRENCY=EUR
MTNMOMO_BASE_URL=https://sandbox.momodeveloper.mtn.com
MTNMOMO_CALLBACK_URL=https://example.com/webhooks/payment-gateways/mtnmomo

Create the API users, keys, and product subscriptions in MTN's developer portal. Use a target environment and currency that match the market/credentials. The driver obtains and caches separate collection and disbursement bearer tokens.

Request a payment¶

use Alphabalex\PaymentMadeEasy\Facades\Payment;

$driver = Payment::driver('mtnmomo');
$pending = $driver->initializePayment([
    'phone'        => '256771234567', // MSISDN digits, without +
    'amount'       => 1000.00,
    'currency'     => 'UGX',
    'reference'    => 'ORDER_123', // sent as X-Reference-Id
    'description'  => 'Order 123',
]);

// RequestToPay returns an accepted/pending result. Keep the reference and
// verify asynchronously using verifyPayment() or a callback.
$payment = $driver->verifyPayment('ORDER_123');

Amounts use major currency units and the configured currency; phone numbers should be in MSISDN format without a leading plus. The request's reference is the provider's X-Reference-Id and should be unique.

Disbursements and webhook flow¶

The driver implements shared DisbursementDriverInterface; use transfer() to send funds to a wallet. Ensure credentials for both products are not confused. Register POST /webhooks/payment-gateways/mtnmomo and wait for the result before fulfilling the related order.

See webhook handling and MTN MoMo in the API reference for status-query and payout examples. Related: configuration · gateway directory.