PHPackages                             microweber-packages/omnipay-momo-mtn - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. microweber-packages/omnipay-momo-mtn

ActiveLibrary

microweber-packages/omnipay-momo-mtn
====================================

MoMo payment gateway driver for Omnipay library

0.2(7mo ago)0664MITPHP

Since Sep 25Pushed 7mo agoCompare

[ Source](https://github.com/microweber-packages/omnipay-momo-mtn)[ Packagist](https://packagist.org/packages/microweber-packages/omnipay-momo-mtn)[ Docs](https://github.com/microweber-packages/omnipay-momo-mtn)[ RSS](/packages/microweber-packages-omnipay-momo-mtn/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (3)Used By (0)

Omnipay: MTN Mobile Money
=========================

[](#omnipay-mtn-mobile-money)

**MTN Mobile Money driver for the Omnipay PHP payment processing library**

[Omnipay](https://github.com/thephpleague/omnipay) is a framework agnostic, multi-gateway payment processing library for PHP. This package implements MTN Mobile Money support for Omnipay.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Initialization](#initialization)
- [API Features](#api-features)
- [Sandbox Testing](#sandbox-testing)
- [Authentication Flow](#authentication-flow)
- [Payment Processing](#payment-processing)
- [Account Services](#account-services)
- [Error Handling](#error-handling)
- [Testing](#testing)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)

Installation
------------

[](#installation)

Install via Composer:

```
composer require microweber-packages/omnipay-momo-mtn
```

Basic Usage
-----------

[](#basic-usage)

```
use Omnipay\Omnipay;

// Create gateway instance
$gateway = Omnipay::create('MoMoMtn');

// Initialize with credentials
$gateway->initialize([
    'apiUserId' => 'your-api-user-id',
    'apiKey' => 'your-api-key',
    'subscriptionKey' => 'your-subscription-key',
    'targetEnvironment' => 'sandbox', // or 'production'
]);

// Process a payment
$response = $gateway->purchase([
    'amount' => '100.00',
    'currency' => 'EUR',
    'payerPhone' => '56733123453',
    'payerMessage' => 'Payment for order #12345',
    'payeeNote' => 'Order payment received'
])->send();

if ($response->isSuccessful()) {
    echo "Payment successful! Transaction ID: " . $response->getTransactionReference();
} else {
    echo "Payment failed: " . $response->getMessage();
}
```

Initialization
--------------

[](#initialization)

### Required Parameters

[](#required-parameters)

ParameterDescriptionEnvironment`apiUserId`API User ID (UUID)Both`apiKey`API Key (UUID)Both`subscriptionKey`Subscription KeyBoth`targetEnvironment`Environment (`sandbox` or `production`)Both### Optional Parameters

[](#optional-parameters)

ParameterDescriptionDefault`testMode`Enable test mode`true`### Example Initialization

[](#example-initialization)

```
$gateway->initialize([
    'apiUserId' => '2bf15487-2309-46e8-82e9-1f658cf3a82c',
    'apiKey' => '7f00bd3a51d7485cbbd85d083e70481b',
    'subscriptionKey' => 'b95263cce7184eaba10d1d309ded4d59',
    'targetEnvironment' => 'sandbox',
    'testMode' => true
]);
```

API Features
------------

[](#api-features)

### ✅ Implemented Features

[](#-implemented-features)

- **Authentication**

    - API User provisioning (sandbox only)
    - API Key generation (sandbox only)
    - OAuth 2.0 token generation
- **Payment Processing**

    - RequestToPay (payment initiation)
    - Payment status checking
    - Transaction reference tracking
- **Account Services**

    - Balance checking (limited in sandbox)
    - Account active status (limited in sandbox)

### 🔄 Payment Flow

[](#-payment-flow)

1. **Initiate Payment** - Use `purchase()` method
2. **Get Transaction Reference** - Store the returned reference
3. **Check Status** - Use `completePurchase()` with the reference
4. **Handle Result** - Process based on status (SUCCESSFUL, FAILED, PENDING, etc.)

Sandbox Testing
---------------

[](#sandbox-testing)

### Test Phone Numbers

[](#test-phone-numbers)

Phone NumberExpected ResultActual Test Result`56733123453`SUCCESSFUL✅ 202 Accepted, empty status returned`46733123450`FAILED✅ 202 Accepted, status check returns error`46733123451`REJECTED✅ 202 Accepted, status check returns error`46733123452`TIMEOUT✅ 202 Accepted, status check returns error`46733123454`PENDING✅ 202 Accepted, status check returns error> **Note**: In sandbox testing, all phone numbers accept payment requests (202 Accepted), but status check behavior varies. This is normal sandbox behavior and doesn't affect the integration functionality.

### Sandbox Credentials Setup

[](#sandbox-credentials-setup)

1. **Register at MTN Developer Portal**

    - Visit [MTN MoMo Developer Portal](https://momodeveloper.mtn.com)
    - Create account and subscribe to Collections product
    - Get your subscription key
2. **Generate Sandbox Credentials**

    ```
    // This is automatically handled by the gateway in sandbox mode
    $gateway->createApiUser()->send(); // Creates API User
    $gateway->createApiKey()->send();  // Creates API Key
    ```

Authentication Flow
-------------------

[](#authentication-flow)

### OAuth 2.0 Token Generation

[](#oauth-20-token-generation)

```
// Tokens are automatically managed by the gateway
// Manual token generation (if needed):
$tokenResponse = $gateway->createToken()->send();
if ($tokenResponse->isSuccessful()) {
    $accessToken = $tokenResponse->getAccessToken();
    $expiresIn = $tokenResponse->getExpiresIn(); // seconds
}
```

Payment Processing
------------------

[](#payment-processing)

### 1. Initiate Payment

[](#1-initiate-payment)

```
$response = $gateway->purchase([
    'amount' => '50.00',
    'currency' => 'EUR', // or 'UGX', 'GHS', etc.
    'payerPhone' => '56733123453',
    'payerMessage' => 'Payment for premium subscription',
    'payeeNote' => 'Monthly subscription fee',
    'externalId' => 'unique-external-reference', // optional
    'callbackUrl' => 'https://yoursite.com/momo/callback' // optional
])->send();

if ($response->isSuccessful()) {
    $transactionId = $response->getTransactionReference();
    // Store transaction ID for status checking
} else {
    echo "Error: " . $response->getMessage();
}
```

### Callback URL Integration

[](#callback-url-integration)

MTN Mobile Money supports callback URLs to notify your application when payment status changes:

```
// Set up payment with callback URL
$response = $gateway->purchase([
    'amount' => '100.00',
    'currency' => 'EUR',
    'payerPhone' => '56733123453',
    'payerMessage' => 'Order payment',
    'payeeNote' => 'E-commerce purchase',
    'callbackUrl' => 'https://yoursite.com/webhooks/momo'
])->send();

if ($response->isSuccessful()) {
    // Payment request submitted successfully
    // MTN will send callback to your URL when status changes
    echo "Payment initiated: " . $response->getTransactionReference();
}
```

#### Callback URL Requirements

[](#callback-url-requirements)

- **HTTPS Required**: Callback URLs must use HTTPS in production
- **POST Method**: MTN sends HTTP POST requests to your callback URL
- **Response**: Your endpoint should respond with HTTP 200 OK
- **Timeout**: MTN will timeout after 30 seconds

#### Example Callback Handler

[](#example-callback-handler)

```
// webhook endpoint: /webhooks/momo