Node JS

External Source

This documentation is synced directly from the GitHub Repository.

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}`));