MyanMyanPay Node SDK

📋 Implementation Documentation

This documentation details the steps for integrating the mmpay-node-sdk into your application to securely send callbacks to the MyanMyanPay SDK server and to verify incoming callbacks from MyanMyanPay.

// TypeScript OR Esm Module
import { MMPaySDK } from 'mmpay-node-sdk';

⬇️ 1. Installation

Install the package via npm:

npm install mmpay-node-sdk --save

⚙️ 2. Configuration

Before use, you must configure the shared Secret Key. This key is used for HMAC-SHA256 signature calculation and verification and must match the key configured on the MMPay platform. It is CRITICAL that this key is loaded from an environment variable for security.

// Load the SDK and configuration
const { MMPaySDK } = require('mmpay-node-sdk');
const MMPay = new MMPaySdk({
  appId: "MMxxxxxxx",
  publishableKey: "pk_test_abcxxxxx",
  secretKey: "sk_test_abcxxxxx",
  apiBaseUrl: "https://xxxxxx"
})

💳 3. Make Payment

let options = {
  orderId: 'ORD-199399933',
  amount: 5000,
  items: [
    { name: "Pencil", amount: 5000, quantity: 1 }
  ],
  customMessage: '', // max 150 char  string
  callbackUrl: 'https://abcdef/callback' // [optional] overrides default callbackURL
}
// sync
MMPay.pay(options)
    .then((response) => {
        console.log(response)
    }).catch((error) => {
        console.log(error)
    })

// async
try {
    await MMPay.pay(options)
} catch (error) {
    console.log(error)
}

Request Body (payload structure)

The request body should be a JSON object containing the transaction details. Based on your IPTrx interface, the required fields are:

Field	Type	Required	Description	Example
orderId	string	Yes	Your generated order ID for the order or system initiating the payment.	"ORD-3983833"
amount	number	Yes	The total transaction amount.	1500.50
callbackUrl	string	No	The URL where the payment gateway will send transaction status updates.	"https://yourserver.com/webhook"
currency	string	No	The currency code (e.g., 'MMK').	"MMK"
customMessage	string	No	Your Customization String
items	Array<Object>	No	List of items included in the purchase.	[{name: "Hat", amount: 1000, quantity: 1}]

items Object Structure

Field	Type	Description
name	string	The name of the item.
amount	number	The unit price of the item.
quantity	number	The number of units purchased.

Response Codes

Code	Status	Description
201	Created	Transaction initiated successfully. Response contains QR code URL/details.
401	Unauthorized	Invalid or missing Publishable Key.
400	Bad Request	Missing required body fields (validated by schema, if implemented).
503	Service Unavailable	Upstream payment API failed or is unreachable.
500	Internal Server Error	General server error during payment initiation.

Successful Response (201) Example

{
  "orderId": "_trx_0012345",
  "amount": 2800,
  "currency": "MMK",
  "qr": "base64:StringxxxIt_Is_A_QR_Code",
  "status": "PENDING"
}

🚀 4. Requesting On Sandbox Environment

let options = {
  orderId: 'ORD-199399933',
  amount: 5000,
  items: [
    { name: "Pencil", amount: 5000, quantity: 1 }
  ],
  customMessage: '', // max 150 char  string
  callbackUrl: 'https://abcdef/callback' // [optional] overrides default callbackURL
}
// sync
MMPay.sandboxPay(options)
    .then((response) => {
        console.log(response)
    }).catch((error) => {
        console.log(error)
    })

// async
try {
    await MMPay.sandboxPay(options)
} catch (error) {
    console.log(error)
}

---

🔐 4. Verifying Incoming Callbacks (Webhooks)

To secure your webhook endpoint that receives callbacks from the MMPay server, use the built-in Express middleware provided by the SDK. This middleware performs the mandatory Signature and Nonce verification.

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

app.post("/callback", async (req, res) => {
  const incomingSignature = req.headers('sppay-x-signature');
  const incomingNonce = req.headers('sppay-x-nonce');
  const { payloadString } = req.body;
  const cbResponse = await MMPay.verifyCb(payloadString, incomingNonce, incomingSignature );
  if (cbResponse) {
    const parsedPayload = JSON.parse(payloadString);
    if (parsedPayload.status === 'SUCCESS') {
      // SUCCESS LOGIC HERE
    }
    if (parsedPayload.status !== 'SUCCESS') {
      // NOT SUCCESS LOGIC HERE
    }
  }
  if (!cbResponse) {
    return res.status(500).json({ error: 'Callback Verification Fail' });
  }
  res.status(200).json({ message: "Success" });
});

---

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

---

💡 Implementation IDEA

We Love Typescript, so here are our favourite framework plugins implementations

Express JS Framwork Usage Full Example

const express = require("express");
const bodyParser = require("body-parser");
const app = express();
const PORT = process.env.PORT || 3000;
app.use(bodyParser.json());

const { MMPaySDK } = require('mmpay-node-sdk');
const MMPay = new MMPaySDK({
    appId: "MMxxxxxxx",
    publishableKey: "pk_test_abcxxxxx",
    secretKey: "sk_test_abcxxxxx",
    apiBaseUrl: "https://xxxxxx"
})

app.post("/create-order", async (req, res) => {
    const { amount, items } = req.body;
    const orderId = ''; // GET YOUR ORDER ID FROM YOUR BIZ LOGIC
    const payload = {
        orderId: 'ORD-199399933',
        amount: 5000,
        items: [
        { name: "Pencil", amount: 5000, quantity: 1 }
        ],
        customMessage: '', // max 150 char  string
        callbackUrl: 'https://abcdef/callback' // [optional] overrides default callbackURL
    }
    let payResponse = await MMPay.pay(payload);
    res.status(200).json(payResponse);
});
// Validating Callback
app.post("/callback", async (req, res) => {
    const incomingSignature = req.headers('x-mmpay-signature');
    const incomingNonce = req.headers('x-mmpay-nonce');
    const payload = request.body;
    const payloadString = JSON.stringify(payload);
    const cbResponse = await MMPay.verifyCb(payloadString, incomingNonce, incomingSignature );
    if (cbResponse) {
        if (payload.status === "SUCCESS" && payload.condition === "PRISTINE") {

        }
        if (payload.status === 'FAILED' && payload.condition === "PRISTINE") {

        };
        if (payload.status === 'REFUNDED' && payload.condition === "PRISTINE") {

        };
        res.status(200).json({ message: "Success" });
    }
    if (!cbResponse) {
        return res.status(500).json({ error: 'Callback Verification Fail' });
    }
});
app.listen(PORT, () => console.log(`Server is running on port ${PORT}`));