# 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:

```bash
composer require myanmyanpay/mmpay-php-sdk
```

## 🚀 Configuration

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

```php
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.

```php
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.

```php
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

```php
// 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.

```php
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).

```php
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.