README

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.

📦 1. Installation

Requires PHP 7.4 or higher.

Install the package via Composer:

composer require myanmyanpay/mmpay-php-sdk

🚀 2. Configuration

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

Implementation

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)'
];

$mmpayx = new MMPay($options);

Configuration Parameters

🛠 3. Create a Payment

pay This method automatically handles the required handshake and signature generation.

Method Signature

$mmpayx->pay($payload);

Implementation

try {
    $payload = [
        '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 = $mmpayx->pay($payload);
    print_r($response);

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

Request Body (payload structure)

Item Object

Response Body Code (201)

{
  "orderId": "_trx_0012345",
  "status": "PENDING",
  "vendorQrRefId": "39233043003345",
  "transactionRefId": "39233043003345", // This is deprecated - transactionRefId will show only after payment is confirmed
  "amount": 2800,
  "currency": "MMK",
  "qr": "EMVco MMQR String => You_have_to_embed_as_qr_image_yourself"
}

🛠 4. Retrieve Payment

This method is used to retrieve a payment and MMQR related events.

Method Signature

$mmpayx->get($payload);

Implementation

try {
    $payload = [
        'orderId'     => 'ORD-LIVE-888'
    ];
    $response = $mmpayx->get($payload);
    if (isset($response['url'])) {
        header('Location: ' . $response['url']);
        exit;
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Request Body (payload structure)

Response Body Code (200)

{
  "orderId": "ORD-111111111",
  "appId": "MMP3883483",
  "amount": 1000,
  "vendor": "KBZPay",
  "method": "QR",
  "customMessage": "",
  "callbackUrl": "",
  "callbackUrlAt": "JSDateObject",
  "callbackUrlStatus": "SUCCESS",
  "status": "SUCCESS", //  'PENDING' | 'SUCCESS' | 'FAILED' | 'REFUNDED' | 'CANCELLED' | 'EXPIRED';
  "disbursementId": "289348734939",
  "disStatus": "SUCCESS",
  "condition": "TOUCHED", // TOUCHED | 'PRISTINE' | 'DIRTY' | 'EXPIRED'
  "createdAt": "JSDateObject",
  "transactionRefId": "939583046594",
  "vendorQrRefId": "48309449034",
  "qr": "EMVCo QR String::MMQR Standard",
}

🛠 5. Cancel Payment

This method is used to cancel a payment and all of its MMQR releated instances

Method Signature

$mmpayx->cancel($payload);

Implementation

try {
    $payload = [
        'orderId'     => 'ORD-LIVE-888'
    ];
    $response = $mmpayx->cancel($payload);
    if (isset($response['url'])) {
        header('Location: ' . $response['url']);
        exit;
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Request Body (payload structure)

Response Body Code (200)

{
  "amount": 1000,
  "orderId": "ORD-111111111",
  "status": "CANCELLED",
  "vendorQrRefId": "289348734939",
}

🔐 6. Handling Webhooks

To secure your webhook endpoint that receives callbacks from the MMPay server, use this event listener to handle the events. The listen performs the mandatory Signature and Nonce verification and emits events

Handling callbacks

Incoming HTTP POST Parameters

Header

Body

Example Implementation With Laravel

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;

class PaymentWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $mmpayx = new MMPay([
            'appId' => config('services.mmpay.app_id'),
            'publishableKey' => config('services.mmpay.publish_key'),
            'secretKey' => config('services.mmpay.secret_key'),
            'apiBaseUrl' => 'https://api.myanmyanpay.com'
        ]);

        $mmpayx->onTxCreate(function ($tx) {
            \Log::info("Payment Created for order: " . $tx['orderId']);
            // Verify Source of truth here if you are using browser mmpayx showPaymentModal()
        });

        // Attach listeners
        $mmpayx->onTxSuccess(function ($tx) {
            // Update your database order status here
            \Log::info("Payment Successful for order: " . $tx['orderId']);
        });

        $mmpayx->onTxFail(function ($tx) {
            \Log::error("Payment Failed for order: " . $tx['orderId']);
        });

        $mmpayx->onTxCancel(function ($tx) {
            \Log::info("Payment Cancelled for order: " . $tx['orderId']);
        });

        $mmpayx->onTxExpire(function ($tx) {
            \Log::info("Payment Expired for order: " . $tx['orderId']);
        });

        $mmpayx->onHeartbeat(function ($tx) {
            \Log::info("Already Sent Event Coming in Again: " . $tx['orderId']);
        });

        // Get headers and raw body
        $nonce = $request->header('X-Mmpay-Nonce');
        $signature = $request->header('X-Mmpay-Signature');
        $payload = $request->getContent();

        // Listen triggers the events
        $mmpayx->listen($payload, $nonce, $signature);

        return response()->json(['received' => true], 200);
    }
}

⚠️ 7. Error Handling

The mmpayx 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.";
}

⚠️ 8. Error Codes

HMac Layer (SERVER Side)

JWT Layer (SERVER Side)

Response Codes

📄 License

MIT License.