External Source

This documentation is synced directly from the GitHub Repository.

MMPay PHP SDK

A professional, comprehensive PHP client library for integrating with the MMPay Payment Gateway. This SDK mimics the official Node.js SDK structure, providing robust utilities for payment creation, handshake authentication, and secure webhook verification.

📦 Installation

Requires PHP 7.4 or higher.

Install the package via Composer:

composer require myanmyanpay/mmpay-php-sdk

🚀 Configuration

To start, initialize the SDK with your Merchant credentials found in the MMPay Dashboard.

use MMPay\MMPay;

$options = [
    'appId'          => 'YOUR_APP_ID',
    'publishableKey' => 'YOUR_PUBLISHABLE_KEY',
    'secretKey'      => 'YOUR_SECRET_KEY',
    'apiBaseUrl'     => '[https://api.mmpay.com](https://api.mmpay.com)'
];

$sdk = new MMPay($options);

Configuration Parameters

Parameter	Type	Required	Description
appId	string	Yes	Your unique Application ID.
publishableKey	string	Yes	Public key used for identification.
secretKey	string	Yes	Private key used for HMAC SHA256 signing.
apiBaseUrl	string	Yes	The base URL for the MMPay API.

---

🛠 Usage

1. Create a Payment (Sandbox)

Use sandboxPay for testing. This method automatically handles the required handshake and signature generation.

try {
    $params = [
        'orderId'       => 'ORD-SANDBOX-001',
        'amount'        => 5000,
        'currency'      => 'MMK',
        'callbackUrl'   => '[https://yoursite.com/webhook/mmpay](https://yoursite.com/webhook/mmpay)',
        'customMessage' => 'Thank you for shopping with us!', // Optional
        'items'         => [
            [
                'name'     => 'Premium Subscription',
                'amount'   => 5000,
                'quantity' => 1
            ]
        ]
    ];

    $response = $sdk->sandboxPay($params);
    print_r($response);

} catch (Exception $e) {
    echo "Payment Failed: " . $e->getMessage();
}

Parameters: sandboxPay / pay

Parameter	Type	Required	Description
orderId	string	Yes	Unique identifier for this order.
amount	number	Yes	Total transaction amount.
items	array	Yes	Array of item objects (see structure below).
currency	string	No	Currency code (e.g., "MMK").
callbackUrl	string	No	URL where the webhook result will be posted.
customMessage	string	No	A custom message to display on the payment page.

Structure: items (Array of Objects)

Key	Type	Required	Description
name	string	Yes	Name of the product or service.
amount	number	Yes	Cost per unit.
quantity	integer	Yes	Number of units.

---

2. Create a Payment (Production)

For live transactions, switch to the pay method.

try {
    $params = [
        'orderId'     => 'ORD-LIVE-888',
        'amount'      => 10000,
        'items'       => [
            ['name' => 'E-Commerce Item', 'amount' => 10000, 'quantity' => 1]
        ]
    ];

    $response = $sdk->pay($params);

    // Redirect user to the payment URL provided in the response
    if (isset($response['url'])) {
        header('Location: ' . $response['url']);
        exit;
    }

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

---

3. Verify Webhook (Callback)

Secure your application by verifying the cryptographic signature of incoming webhooks. This ensures the request actually came from MMPay.

Handling callbacks

Incoming HTTP POST Parameters

Header

Field Name	Type	Required	Description
Content-Type	string	Yes	'application/json'
X-Mmpay-Signature	string	Yes	'34834890vfgh9hnf94irfg_48932i4rt90349849'
X-Mmpay-Nonce	string	Yes	'94843943949349'

Body

Field Name	Type	Required	Description
orderId	string	Yes	Unique identifier for the specific order.
amount	number	Yes	The transaction amount.
currency	string	Yes	The 3-letter currency code (e.g., MMK, USD).
vendor	string	Yes	Identifier for the vendor initiating the request.
method	'QR', 'PIN', 'PWA', 'CARD'	Yes	Identifier for the method.
status	'PENDING','SUCCESS','FAILED','REFUNDED'	Yes	Current status of the transaction.
condition	'PRESTINE', 'TOUCHED'	Yes	Used QR Code scan again or not
transactionRefId	string	Yes	The reference ID generated by the payment provider.
callbackUrl	string	No	Optional URL to receive webhooks or updates.
customMessage	string	No	User provided custom message

Pure PHP Example

// 1. Capture the raw POST body (Required for signature check)
$payload = file_get_contents('php://input');

// 2. Capture Headers
$headers = getallheaders(); 
$nonce = $headers['X-Mmpay-Nonce'] ?? '';
$signature = $headers['X-Mmpay-Signature'] ?? '';

// 3. Verify
try {
    $isValid = $sdk->verifyCb($payload, $nonce, $signature);

    if ($isValid) {
        // ✅ Signature matched. Process the order.
        $data = json_decode($payload, true);
        $status = $data['status']; 

        if ($status === 'SUCCESS') {
            // Mark order as paid in DB
        }

        http_response_code(200);
        echo "OK";
    } else {
        // ❌ Signature mismatch. Potential fraud.
        http_response_code(400);
        echo "Invalid Signature";
    }
} catch (Exception $e) {
    http_response_code(400);
    echo "Error: " . $e->getMessage();
}

Laravel Controller Example

In Laravel, you should use the Request object to fetch headers and the raw content.

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use MMPay\MMPay;
use Illuminate\Support\Facades\Log;

class PaymentController extends Controller
{
    public function handleWebhook(Request $request)
    {
        // Initialize SDK (Preferably via Service Provider or Config)
        $sdk = new MMPay([
            'appId'          => config('services.mmpay.app_id'),
            'publishableKey' => config('services.mmpay.key'),
            'secretKey'      => config('services.mmpay.secret'),
            'apiBaseUrl'     => config('services.mmpay.url'),
        ]);

        // 1. Get Raw Content (Crucial for signature verification)
        $payload = $request->getContent();

        // 2. Get Headers
        $nonce = $request->header('X-Mmpay-Nonce');
        $signature = $request->header('X-Mmpay-Signature');

        if (!$nonce || !$signature) {
            return response()->json(['message' => 'Missing Signature Headers'], 400);
        }

        // 3. Verify Signature
        try {
            $isValid = $sdk->verifyCb($payload, $nonce, $signature);

            if (!$isValid) {
                Log::warning('MMPay Webhook Signature Mismatch', ['ip' => $request->ip()]);
                return response()->json(['message' => 'Invalid Signature'], 400);
            }

            // ✅ Signature Valid - Process Logic
            $data = json_decode($payload, true);

            if ($data['status'] === 'SUCCESS' && $data['condition'] === 'PRESTINE') {
                // Update Order Status in Database
                // Order::where('order_id', $data['orderId'])->update(['status' => 'paid']);
            }

            return response()->json(['status' => 'success']);

        } catch (\Exception $e) {
            Log::error('MMPay Webhook Error: ' . $e->getMessage());
            return response()->json(['message' => 'Server Error'], 500);
        }
    }
}

Parameters: verifyCb

Parameter	Type	Description
payload	string	The raw, unmodified JSON string body of the request.
nonce	string	Value of the X-Mmpay-Nonce header.
expectedSignature	string	Value of the X-Mmpay-Signature header.

---

⚠️ Error Handling

The SDK throws standard PHP \Exception when errors occur (e.g., network issues, API validation errors, or handshake failures).

try {
    $sdk->pay($params);
} catch (\Exception $e) {
    // Log the error for debugging
    error_log($e->getMessage());

    // Return a user-friendly message
    echo "We could not process your payment at this time.";
}

---

Error Codes

Api Key Layer Authentication [SERVER SDK]

Code	Description
KA0001	Bearer Token Not Included In Your Request
KA0002	API Key Not 'LIVE'
KA0003	Signature mismatch
KA0004	Internal Server Error ( Talk to our support immediately fot this )
KA0005	IP Not whitelisted
429	Ratelimit hit only 1000 request / minute allowed

JWT Layer Authentication [SERVER SDK]

Code	Description
BA001	Btoken is nonce one time token is not included
BA002	Btoken one time nonce mismatch
BA000	Internal Server Error ( Talk to our support immediately fot this )
429	Ratelimit hit only 1000 request / minute allowed

---

📄 License

MIT License.