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.

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 } = req.body;
    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}`));

FastifyJS With Plugin Usage Full Example (Fast)

// server.ts
import {mmpayPlugin} from './plugins/mmpayPlugin';

interface MMPayIncomingCallbackScheme {
    orderId: string;
    amount: number;
    method: string;
    currency: string;
    vendor: string;
    status: 'PENDING' | 'SUCCESS' | 'FAILED' | 'REFUNDED';
    condition: 'PRISTINE' | 'TOUCHED' | 'EXPIRED';
    transactionRefId: string;
    callbackUrl?: string;
    customMessage?: string;
}

const fastify: FastifyInstance = Fastify({ logger: true });

await fastify.register(mmpayPlugin, {
    appId: process.env.MMPAY_APP_ID!,
    uatPubKey: process.env.MMPAY_UAT_PUBKEY!,
    uatSecKey: process.env.MMPAY_UAT_SECKEY!,
    prdPubKey: process.env.MMPAY_PRD_PUBKEY!,
    prdSecKey: process.env.MMPAY_PRD_SECKEY!,
});

fastify.post('/create-order', async (request: FastifyRequest, reply: FastifyReply) => {
    const { amount, orderId, items, customMessage } = body;
    const payResponse = await fastify.mmpay.createProductionPayment({ amount, orderId, items, customMessage });
})

fastify.post('/webhooks/mmpay', async (request: FastifyRequest<{Body: any}>, reply: FastifyReply) => {
    const incomingSignature = request.headers['x-mmpay-signature'] as string;
    const incomingNonce = request.headers['x-mmpay-nonce'] as string;
    const payload = request.body as MMPayIncomingCallbackScheme;
    const payloadString = JSON.stringify(payload);

    const cbResult = await fastify.mmpay.verifyProductionCallBack({
        payloadString: payloadString,
        nonce: incomingNonce,
        signature: incomingSignature
    });

    if (cbResult) {
        if (payload.status === "SUCCESS" && payload.condition === "PRISTINE") {

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

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

        };
        reply.code(200).send({message: "Callback Processed Successfully"});
    }

    if (!cbResult) {
        reply.code(200).send({message: "Callback Verification Failed"});
    }
});

// plguins/mmpayPlugin.ts
/**
 * MMpay FastifyJS Plugin
 * @author          [NawIng]
 * @organization    [MyanMyanPay]
 */
import {FastifyInstance, FastifyPluginAsync} from 'fastify';
import fastifyPlugin from 'fastify-plugin';
import {MMPaySDK} from 'mmpay-node-sdk';
/**
 * @IOrderedItem
 */
interface IOrderedItem {
    name: string;
    quantity: number;
    amount: number;
}
/**
 * @CreatePaymentRequest
 */
export interface CreatePaymentRequest {
    amount: number;
    orderId: string;
    items?: IOrderedItem[];
    customMessage?: string;
}
/**
 * @PaymentCreateResponse
 */
export interface PaymentCreateResponse {
    orderId: string;
    amount: number;
    currency?: string;
    transactionRefId?: string;
    qr: string;
}
/**
 * @Callback
 */
export interface CallbackEncoded {
    payloadString: string;
    nonce: string;
    signature: string;
}
/**
 * @fastify
 */
declare module 'fastify' {
    interface FastifyInstance {
        mmpay: {
            createSandboxPayment: (request: CreatePaymentRequest) => Promise<PaymentCreateResponse>;
            verifySandboxCallBack: (request: CallbackEncoded) => Promise<boolean>;
            createProductionPayment: (request: CreatePaymentRequest) => Promise<PaymentCreateResponse>;
            verifyProductionCallBack: (request: CallbackEncoded) => Promise<boolean>;
        };
    }
}
/**
 * @MMPayPluginOptions
 */
interface MMPayPluginOptions {
    appId: string;
    uatPubKey: string;
    uatSecKey: string;
    prdPubKey: string;
    prdSecKey: string;
}
const mmpayPlugin: FastifyPluginAsync<MMPayPluginOptions> = fastifyPlugin(async (fastify: FastifyInstance, options: MMPayPluginOptions) => {
    const SandBoxMMPay = MMPaySDK({
        appId: options.appId,
        publishableKey: options.uatPubKey,
        secretKey: options.uatSecKey,
        apiBaseUrl: 'https://xxx.myanmyanpay.com' // Ask Our Team
    });
    const ProductionMMPay = MMPaySDK({
        appId: options.appId,
        publishableKey: options.prdPubKey,
        secretKey: options.prdSecKey,
        apiBaseUrl: 'https://xxx.myanmyanpay.com' // Ask Our Team
    });
    /**
     * createSandboxPayment
     * @param {CreatePaymentRequest} params
     * @returns {Promise<PaymentCreateResponse>}
     */
    const createSandboxPayment = async (params: CreatePaymentRequest): Promise<PaymentCreateResponse> => {
        let options = {
            orderId: params.orderId,
            currency: 'MMK',
            amount: params.amount,
            items: params.items,
            customMessage: params.customMessage,
        }
        return await SandBoxMMPay.sandboxPay(options);
    }
    /**
     * verifySandboxCallBack
     * @param {CallbackEncoded} params
     * @param {string} params.nonce
     * @param {string} params.signature
     * @returns {Promise<boolean>}
     */
    const verifySandboxCallBack = async (params: CallbackEncoded): Promise<boolean> => {
        return await SandBoxMMPay.verifyCb(params.payloadString, params.nonce, params.signature);
    };
    /**
     * createProductionPayment
     * @param {CreatePaymentRequest} params
     * @returns {Promise<PaymentCreateResponse>}
     */
    const createProductionPayment = async (params: CreatePaymentRequest): Promise<PaymentCreateResponse> => {
        let options = {
            orderId: params.orderId,
            currency: 'MMK',
            amount: params.amount,
            items: params.items,
            customMessage: params.customMessage,
        }
        return await ProductionMMPay.pay(options);
    };
    /**
     * verifyProductionCallBack
     * @param {CallbackEncoded} params
     * @param {string} params.nonce
     * @param {string} params.signature
     * @returns {Promise<boolean>}
     */
    const verifyProductionCallBack = async (params: CallbackEncoded): Promise<boolean> => {
        return await ProductionMMPay.verifyCb(params.payloadString, params.nonce, params.signature);
    };
    /**
     * @mmpay
     */
    fastify.decorate('mmpay', {
        createSandboxPayment,
        verifySandboxCallBack,
        createProductionPayment,
        verifyProductionCallBack
    });
});
export {mmpayPlugin};

ElysiaJS With Plugin Usage Full Example (Bun Native - Extremely Fast)

// server.ts
//usage example
import {Elysia} from 'elysia';
import {mmpayPlugin} from './plugins/mmpayPlugin';

interface MMPayIncomingCallbackScheme {
    orderId: string;
    amount: number;
    method: string;
    currency: string;
    vendor: string;
    status: 'PENDING' | 'SUCCESS' | 'FAILED' | 'REFUNDED';
    condition: 'PRISTINE' | 'TOUCHED' | 'EXPIRED';
    transactionRefId: string;
    callbackUrl?: string;
    customMessage?: string;
}

const app = new Elysia()
    .use(mmpayPlugin)
    .post('/create-order', async ({body, mmpay}) => {
        const { amount, orderId, items } = body;
        await mmpay.createProductionPayment(amount, orderid, items)
    })
    .post('/create-order-sandbox', async ({body, mmpay}) => {
        const { amount, orderId, items } = body;
        await mmpay.createSandboxPayment(amount, orderid, items)
    })
    .post('/webhooks/mmpay', async ({body, headers, mmpay}) => {
        const incomingSignature = headers['x-mmpay-signature'] as string;
        const incomingNonce = headers['x-mmpay-nonce'] as string;
        const payload = body as MMPayIncomingCallbackScheme;
        const payloadString = JSON.stringify(payload);
        const cbResult = await mmpay.verifyProductionCallback({
            payloadString: payloadString,
            nonce: incomingNonce,
            signature: incomingSignature
        });
        if (cbResult) {
            if (payload.status === "SUCCESS" && payload.condition === "PRISTINE") {

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

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

            };
            reply.code(200).send({message: "Callback Processed Successfully"});
        }

        if (!cbResult) {
            reply.code(200).send({message: "Callback Verification Failed"});
        }
    })
    .post('/webhooks/mmpay-sandbox', async ({body, headers, mmpay}) => {
        const incomingSignature = headers['x-mmpay-signature'] as string;
        const incomingNonce = headers['x-mmpay-nonce'] as string;
        const payload = body as MMPayIncomingCallbackScheme;
        const payloadString = JSON.stringify(payload);
        const cbResult = await mmpay.verifySandboxCallback({
            payloadString: payloadString,
            nonce: incomingNonce,
            signature: incomingSignature
        });
        if (cbResult) {
            if (payload.status === "SUCCESS" && payload.condition === "PRISTINE") {

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

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

            };
            reply.code(200).send({message: "Callback Processed Successfully"});
        }

        if (!cbResult) {
            reply.code(200).send({message: "Callback Verification Failed"});
        }
    })

// plguins/mmpayPlugin.ts
/**
 * MMpay ElysiaJS Plugin
 * @author          [NawIng]
 * @organization    [MyanMyanPay]
 */
import {Elysia} from 'elysia';
import {MMPaySDK} from 'mmpay-node-sdk';

const SandboxMMPay = MMPaySDK({
    appId: process.env.SBX_MMPAY_APP_ID!,
    publishableKey: process.env.SBX_MMPAY_PUB_KEY!,
    secretKey: process.env.SBX_MMPAY_SEC_KEY!,
    apiBaseUrl: 'https://xxx.myanmyanpay.com', // Ask Our Team
});

const ProductionMMPay = MMPaySDK({
    appId: process.env.PDX_MMPAY_APP_ID!,
    publishableKey: process.env.PDX_MMPAY_PUB_KEY!,
    secretKey: process.env.PDX_MMPAY_SEC_KEY!,
    apiBaseUrl: 'https://xxx.myanmyanpay.com', // Ask Our Team
});
/**
 * @Callback
 */
export interface CallbackEncoded {
    payloadString: string;
    nonce: string;
    signature: string;
}
/**
 * @PaymentCreateResponse
 */
export interface PaymentCreateResponse {
    orderId: string;
    amount: number;
    currency?: string;
    transactionRefId?: string;
    qr: string;
}

/**
 * @mmpayPlugin
 */
export const mmpayPlugin = new Elysia({name: 'plugin.mmpay'})
    .decorate('mmpay', {
        /**
         * createSandboxPayment
         * @param {string} orderId
         * @param {number} amount
         * @param {string} customMessage
         * @param {any[]} items
         * @returns
         */
        async createSandboxPayment(orderId: string, amount: number,  customMessage: string, items: any ): Promise <PaymentCreateResponse> {
            return await SandboxMMPay.sandboxPay({
                amount,
                orderId,
                customMessage,
                items,
            });
        },
        /**
         * verifySandboxCallback
         * @param orderId
         * @param amount
         * @returns
         */
        async verifySandboxCallback(params: CallbackEncoded): Promise<boolean> {
            return await SandboxMMPay.verifyCb(params.payloadString, params.nonce, params.signature);
        },
        /**
         * createProductionPayment
         * @param {string} orderId
         * @param {number} amount
         * @param {any[]} items
         * @returns
         */
        async createProductionPayment(orderId: string, amount: number, customMessage: string, items: any): Promise <PaymentCreateResponse>  {
            return await ProductionMMPay.pay({
                amount,
                orderId,
                customMessage,
                items,
            });
        },
        /**
         * verifyProductionCallback
         * @param {CallbackEncoded} params
         * @param {string} params.nonce
         * @param {string} params.signature
         * @returns {Promise<boolean>}
         */
        async verifyProductionCallback(params: CallbackEncoded): Promise<boolean> {
            return await ProductionMMPay.verifyCb(params.payloadString, params.nonce, params.signature);
        }
    });