@mmpay/aya-mmqr 0.0.0-stage → 1.0.13

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# 📘 AYA Pay Merchant API Integration Documentation (APIM)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An unofficial, personal-use TypeScript API integration package for connecting AYAPay Merchant's MMQR functionalities into Node.js applications.
+It provides a simple class-based wrapper around the AYAPay REST API, handling authentication, token management, dynamic QR generation, status checking, and refunds.
+
+> **Disclaimer:** This is an unofficial, community-driven integration package intended for personal reuse. It is not affiliated with, endorsed by, or maintained by AYA Bank.
+
+## 🚀 Installation
+
+Install the package via npm:
+
+```bash
+npm install @mmpay/aya-mmqr --save
+```
+
+
+## Implementation IDEA
+```javascript
+import { AYAPayMerchantApi, SDKOptions } from '@mmpay/aya-mmqr';
+
+const options: SDKOptions = {
+  baseUrl: 'https://sandboxxxxx.aya-payx.com/api', // <<< Request AYA Team. I cannot disclose here for security reasons
+  prefixUrl: 'xxx',  // <<< Request AYA Team. I cannot disclose here for security reasons
+  consumerKey: 'YOUR_CONSUMER_KEY',
+  consumerSecret: 'YOUR_CONSUMER_SECRET',
+  decryptionKey: 'YOUR_DECRYPTION_KEY_32_BYTES',
+  phone: 'MERCHANT_APP_PHONE_NUMBER',
+  password: 'MERCHANT_APP_PASSWORD', // Password Or Pincode
+};
+
+const ayaPayClient = AYAPayMerchantApi(options);
+
+// DEVELOPMENT QR
+const qrResponse = await ayaPayClient.requestQR({
+  amount: 5000,
+  currency: 'MMK',
+  externalTransactionId: 'ORD-' + new Date().getTime(),
+  serviceCode: 'xxx-qr', // << I cannot disclose all of these ENUM for security reasons, Please ask merchant onboarding teams
+  // externalAdditionalData: optional
+})
+console.log(qrResponse)
+
+const qrStatusResponse = await ayaPayClient.paymentStatusQR({
+  referenceNumber: qrResponse.data.referenceNumber,
+  externalTransactionId: qrResponse.data.externalTransactionId,
+})
+console.log(qrStatusResponse)
+
+
+const omResponse = await ayaPayClient.requestPush({
+  amount: 5000,
+  currency: 'MMK',
+  externalTransactionId: 'ORD-' + new Date().getTime(),
+  serviceCode: 'xxx-om', // << I cannot disclose all of these ENUM for security reasons, Please ask merchant onboarding teams
+  // externalAdditionalData: optional
+})
+console.log(omResponse)
+
+const omStatusResponse = await ayaPayClient.paymentStatusPush({
+  referenceNumber: omResponse.data.referenceNumber,
+  externalTransactionId: omResponse.data.externalTransactionId,
+})
+console.log(omStatusResponse)
+
+// Now you can call methods like:
+// await ayaPayClient.getToken({ grantType: 'client_credentials' });
+```
+
+## 📝 SDK Configuration and Initialization
+
+The SDK requires specific credentials and endpoint information for initialization.
+
+### `SDKOptions` Interface
+
+This configuration object is passed to the initialization function.
+
+| Property | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `baseUrl` | `string` | **Yes** | The base URL for the AYA Pay API (e.g., `https://api.gateway.com`). |
+| `consumerKey` | `string` | **Yes** | Your merchant consumer key used for generating the Basic Token. |
+| `consumerSecret` | `string` | **Yes** | Your merchant consumer secret used for generating the Basic Token. |
+| `decryptionKey` | `string` | **Yes** | The AES-256-ECB secret key for decrypting payment callback data. |
+| `basicKey` | `string` | No | *(Present in interface but currently unused in methods)*. |
+
+### Initialization Example (TypeScript)
+
+The `AYAPayMerchantApi` function returns a class instance containing all core methods.
+
+```javascript
+import { AYAPayMerchantApi, SDKOptions } from '@mmpay/aya-mmqr';
+
+const options: SDKOptions = {
+  baseUrl: 'https://sandbox.ayapay.com/api', // <<< Request HERE I cannot disclose for security reasons
+  consumerKey: 'YOUR_CONSUMER_KEY',
+  consumerSecret: 'YOUR_CONSUMER_SECRET',
+  decryptionKey: 'YOUR_DECRYPTION_KEY_32_BYTES',
+  basicKey: '', // Can be an empty string
+};
+
+const ayaPayClient = AYAPayMerchantApi(options);
+
+// Now you can call methods like:
+// await ayaPayClient.getToken({ grantType: 'client_credentials' });
+```
+
+---
+
+## 🔑 Authentication and Token Management
+
+All merchant API interactions require two tokens: the **Key Token** (for `Token` header) and the **API Token** (for `Authorization` header).
+
+### 1. `getToken()`
+
+Requests the primary Key Token using the Client Credentials grant type. This token is stored internally and used in the `Token` header.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `options.grantType` | `string` | Must be set to `'client_credentials'`. |
+
+#### `getTokenResponse` (Success Response)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `accessToken` | `string` | The Key Token obtained. |
+| `tokenType` | `string` | Token type, e.g., `'Bearer'`. |
+| `expiresIn` | `number` | Token expiry time in seconds. |
+
+### 2. `login(options: loginRequest)`
+
+Authenticates the merchant to retrieve the merchant-specific API Token and Refresh Token.
+
+#### `loginRequest` (Parameters)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `phone` | `string` | Merchant's registered phone number. |
+| `password` | `string` | Merchant's password. |
+
+#### `loginResponse` (Success Response)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `err` | `number` | Error code (0 for success). |
+| `message` | `string` | Status message. |
+| `token.token` | `string` | The API Token, stored internally and used for payment methods. |
+| `refreshToken.token` | `string` | The Refresh Token. |
+
+---
+
+## 💳 Payment Methods
+
+### 1. `requestQR(options: PaymentCreateRequest)`
+
+Generates a QR code for a customer to scan and pay.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `options` | `PaymentCreateRequest` | Object containing payment details. |
+
+### 2. `requestPush(options: PaymentCreateRequest)`
+
+Initiates a payment by sending a push notification request to the customer's payment app.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `options` | `PaymentCreateRequest` | Object containing payment details. |
+
+#### `PaymentCreateRequest` (Parameters for QR/Push)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `amount` | `number` | Transaction amount. |
+| `currency` | `string` | Currency code (e.g., `'MMK'`). |
+| `externalTransactionId` | `string` | **Unique ID** from the merchant's system. |
+| `serviceCode` | `string` | Merchant's service code. |
+| `externalAdditionalData` | `string` | Optional field for extra merchant data. |
+
+#### `PaymentCreateResponse` (Success Response)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `data.qrdata` | `string` | (QR) Raw QR code string. |
+| `data.mmqrdata` | `string` | (QR) Myanmar QR code string. |
+| `data.referenceNumber` | `string` | **Unique** transaction reference number from AYA Pay. |
+| `data.amount` | `string` | Transaction amount confirmed. |
+| `data.expiredAt` | `string` | Timestamp when the payment request expires. |
+
+---
+
+## 🔍 Status Check Methods
+
+### 1. `paymentStatusQR(options: PaymentStatusRequest)`
+
+Checks the status of a previously requested QR payment.
+
+### 2. `paymentStatusPush(options: PaymentStatusRequest)`
+
+Checks the status of a previously requested Push payment.
+
+#### `PaymentStatusRequest` (Parameters for Status Check)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `referenceNumber` | `string` | The AYA Pay unique transaction reference number. |
+| `externalTransactionId` | `string` | The merchant's unique transaction ID. |
+
+#### `PaymentStatusResponse` (Success Response)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `status` | `string` | The transaction status (e.g., `'PENDING'`, `'SUCCESS'`, `'FAILED'`). |
+| `transRefId` | `string` | Alias for the AYA Pay transaction ID. |
+| `err` | `number` | Error code (0 for success). |
+
+---
+
+## 🔔 Callback Verification
+
+This utility method is used by the merchant's callback endpoint to securely decrypt the transaction result payload sent by the AYA Pay system.
+
+### `verifyCallback(options: CallbackEncoded)`
+
+Decrypts the Base64-encoded, encrypted payload using AES-256-ECB with the configured `decryptionKey`.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `options.paymentResult` | `string` | The encrypted and Base64-encoded payment payload from the callback body. |
+| `options.refundResult` | `string` | The encrypted refund payload (if applicable). |
+| `options.externalTransactionId` | `string` | The merchant's unique ID for context. |
+
+| Returns | Type | Description |
+| :--- | :--- | :--- |
+| `Promise<CallbackDecoded>` | The raw, decrypted JSON string of the transaction result. **Must be parsed** into an object for use. |
+
+### Decryption Example
+
+```javascript
+// Example handler for the merchant's callback endpoint (e.g., /api/payment/callback)
+
+async function handleCallback(encodedBody) {
+  try {
+    const decryptedPayload = await ayaPayClient.verifyCallback(encodedBody);
+    // The result is a JSON string, which must be parsed
+    const paymentResult = JSON.parse(decryptedPayload as string);
+    // Process paymentResult (e.g., update order status)
+    console.log('Decrypted Status:', paymentResult.status);
+
+  } catch (error) {
+    console.error('Decryption Failed:', error);
+  }
+}
+```

package/bun.lock

@@ -0,0 +1,23 @@
+{
+  "lockfileVersion": 2,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@mmpay/aya-mmqr",
+      "devDependencies": {
+        "@types/node": "^26.0.0",
+        "dotenv": "^17.2.2",
+        "typescript": "^5.4.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@26.6.5", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-uMzsv9stDdofIZBx4UGh4Z9ZgXnGC9seRDscilBcTHAeOFk67MZg/k9bWVfO+bk4qZmG+l52hRnLwUiH2LnJTg=="],
+
+    "dotenv": ["dotenv@17.4.2", "", {}, "sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.9.0", "", {}, "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg=="],
+  }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,78 @@
+import { CallbackDecoded, CallbackEncoded, getTokenResponse, loginResponse, PaymentCreateRequest, PaymentCreateResponse, PaymentStatusRequest, PaymentStatusResponse } from './types';
+export { CallbackDecoded, CallbackEncoded, getTokenResponse, loginResponse, PaymentCreateRequest, PaymentCreateResponse, PaymentStatusRequest, PaymentStatusResponse };
+/**
+ * @InstanceOptions
+ */
+export interface InstanceOptions {
+    baseUrl: string;
+    prefixUrl: string;
+    consumerKey: string;
+    consumerSecret: string;
+    decryptionKey: string;
+    phone: string;
+    password: string;
+}
+/**
+ * @AYAPayMerchantApi
+ * @param {InstanceOptions} options
+ * @returns {AYAPayMerchantClass} A status message string.
+ */
+export declare function AYAPayMerchantApi(options: InstanceOptions): AYAPayMerchantClass;
+/**
+ * @AYAPayMerchantClass
+ */
+declare class AYAPayMerchantClass {
+    #private;
+    constructor(options: InstanceOptions);
+    /**
+     * basicToken
+     * @returns
+     */
+    private basicToken;
+    /**
+     * getToken
+     * @returns {Promise<getTokenResponse>}
+     */
+    private getToken;
+    /**
+     * login
+     * @returns {Promise<loginResponse>}
+     */
+    private login;
+    /**
+     * authenticate
+     */
+    authenticate(): Promise<void>;
+    /**
+     * requestQR
+     * @param {PaymentCreateRequest} options
+     * ...
+     * @returns {Promise<PaymentCreateResponse>}
+     */
+    requestQR(options: PaymentCreateRequest): Promise<PaymentCreateResponse>;
+    /**
+     * paymentStatusQR
+     * ...
+     */
+    paymentStatusQR(options: PaymentStatusRequest): Promise<PaymentStatusResponse>;
+    /**
+     * requestPush
+     * ...
+     */
+    requestPush(options: PaymentCreateRequest): Promise<PaymentCreateResponse>;
+    /**
+     * paymentStatusPush
+     * ...
+     */
+    paymentStatusPush(options: PaymentStatusRequest): Promise<PaymentStatusResponse>;
+    /**
+     * verifyCallback
+     * ...
+     */
+    verifyCallback(options: CallbackEncoded): Promise<CallbackDecoded>;
+    /**
+     * verifyCallbackRefund
+     * ...
+     */
+    verifyCallbackRefund(options: CallbackEncoded): Promise<CallbackDecoded>;
+}

package/dist/cjs/index.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AYAPayMerchantApi = AYAPayMerchantApi;
+const node_buffer_1 = require("node:buffer");
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * @AYAPayMerchantApi
+ * @param {InstanceOptions} options
+ * @returns {AYAPayMerchantClass} A status message string.
+ */
+function AYAPayMerchantApi(options) {
+    return new AYAPayMerchantClass({
+        baseUrl: options.baseUrl,
+        prefixUrl: options.prefixUrl,
+        consumerKey: options.consumerKey,
+        consumerSecret: options.consumerSecret,
+        decryptionKey: options.decryptionKey,
+        phone: options.phone,
+        password: options.password,
+    });
+}
+/**
+ * @AYAPayMerchantClass
+ */
+class AYAPayMerchantClass {
+    #baseUrl;
+    #prefixUrl;
+    #consumerKey;
+    #consumerSecret;
+    #decryptionKey;
+    #phone;
+    #password;
+    #keyToken = '';
+    #apiToken = '';
+    constructor(options) {
+        this.#baseUrl = options.baseUrl;
+        this.#prefixUrl = options.prefixUrl;
+        this.#consumerKey = options.consumerKey;
+        this.#consumerSecret = options.consumerSecret;
+        this.#decryptionKey = options.decryptionKey;
+        this.#phone = options.phone;
+        this.#password = options.password;
+    }
+    /**
+     * basicToken
+     * @returns
+     */
+    basicToken() {
+        const rawString = `${this.#consumerKey}:${this.#consumerSecret}`;
+        const buffer = node_buffer_1.Buffer.from(rawString);
+        const base64String = buffer.toString('base64');
+        return base64String;
+    }
+    /**
+     * getToken
+     * @returns {Promise<getTokenResponse>}
+     */
+    async getToken() {
+        try {
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Authorization': `Basic ${this.basicToken()}`
+                }
+            };
+            const body = {
+                grant_type: 'client_credentials'
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/token`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            const originResponse = (await response.json());
+            const modifiedResponse = {
+                accessToken: originResponse.access_token,
+                scope: originResponse.scope,
+                tokenType: originResponse.token_type,
+                expiresIn: originResponse.expires_in,
+            };
+            this.#keyToken = modifiedResponse.accessToken;
+            return modifiedResponse;
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * login
+     * @returns {Promise<loginResponse>}
+     */
+    async login() {
+        try {
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': `Bearer ${this.#keyToken}`
+                }
+            };
+            const body = {
+                phone: this.#phone,
+                password: this.#password,
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/${this.#prefixUrl}/1.0.0/thirdparty/merchant/login`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            const loginResponse = (await response.json());
+            this.#apiToken = loginResponse.token.token;
+            return loginResponse;
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * authenticate
+     */
+    async authenticate() {
+        await this.getToken();
+        await this.login();
+    }
+    /**
+     * requestQR
+     * @param {PaymentCreateRequest} options
+     * ...
+     * @returns {Promise<PaymentCreateResponse>}
+     */
+    async requestQR(options) {
+        try {
+            await this.authenticate();
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': `Bearer ${this.#keyToken}`,
+                    'Authorization': `Bearer ${this.#apiToken}`,
+                }
+            };
+            const body = {
+                amount: options.amount,
+                currency: options.currency,
+                externalTransactionId: options.externalTransactionId,
+                externalAdditionalData: options.externalAdditionalData,
+                serviceCode: options.serviceCode,
+                MMQR: options.MMQR,
+                timelimit: options.timelimit,
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/${this.#prefixUrl}/1.0.0/thirdparty/merchant/v2/requestQRPayment`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            return (await response.json());
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * paymentStatusQR
+     * ...
+     */
+    async paymentStatusQR(options) {
+        try {
+            await this.authenticate();
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': `Bearer ${this.#keyToken}`,
+                    'Authorization': `Bearer ${this.#apiToken}`,
+                }
+            };
+            const body = {
+                externalTransactionId: options.externalTransactionId,
+                referenceNumber: options.referenceNumber,
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/${this.#prefixUrl}/1.0.0/thirdparty/merchant/checkQRPayment`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            return (await response.json());
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * requestPush
+     * ...
+     */
+    async requestPush(options) {
+        try {
+            await this.authenticate();
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': `Bearer ${this.#keyToken}`,
+                    'Authorization': `Bearer ${this.#apiToken}`,
+                }
+            };
+            const body = {
+                amount: options.amount,
+                currency: options.currency,
+                externalTransactionId: options.externalTransactionId,
+                externalAdditionalData: options.externalAdditionalData,
+                serviceCode: options.serviceCode,
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/${this.#prefixUrl}/1.0.0/thirdparty/merchant/v2/requestPushPayment`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            return (await response.json());
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * paymentStatusPush
+     * ...
+     */
+    async paymentStatusPush(options) {
+        try {
+            await this.authenticate();
+            const config = {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': `Bearer ${this.#keyToken}`,
+                    'Authorization': `Bearer ${this.#apiToken}`,
+                }
+            };
+            const body = {
+                externalTransactionId: options.externalTransactionId,
+                referenceNumber: options.referenceNumber,
+            };
+            const formBody = new URLSearchParams();
+            Object.entries(body).forEach(([key, value]) => {
+                if (value !== undefined)
+                    formBody.append(key, String(value));
+            });
+            const response = await fetch(`${this.#baseUrl}/${this.#prefixUrl}/1.0.0/thirdparty/merchant/checkRequestPayment`, {
+                method: 'POST',
+                headers: config.headers,
+                body: formBody
+            });
+            return (await response.json());
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * verifyCallback
+     * ...
+     */
+    async verifyCallback(options) {
+        try {
+            if (!options.paymentResult)
+                throw new Error("paymentResult is missing or undefined");
+            const cipherRaw = node_buffer_1.Buffer.from(options.paymentResult, 'base64');
+            const key = node_buffer_1.Buffer.from(this.#decryptionKey);
+            const decipher = node_crypto_1.default.createDecipheriv('aes-256-ecb', key, null);
+            let decrypted = decipher.update(cipherRaw, undefined, 'utf8');
+            decrypted += decipher.final('utf8');
+            const result = JSON.parse(decrypted);
+            return result;
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+    /**
+     * verifyCallbackRefund
+     * ...
+     */
+    async verifyCallbackRefund(options) {
+        try {
+            if (!options.refundResult)
+                throw new Error("refundResult is missing or undefined");
+            const cipherRaw = node_buffer_1.Buffer.from(options.refundResult, 'base64');
+            const key = node_buffer_1.Buffer.from(this.#decryptionKey);
+            const decipher = node_crypto_1.default.createDecipheriv('aes-256-ecb', key, null);
+            let decrypted = decipher.update(cipherRaw, undefined, 'utf8');
+            decrypted += decipher.final('utf8');
+            const result = JSON.parse(decrypted);
+            return result;
+        }
+        catch (error) {
+            console.error(error);
+            throw error;
+        }
+    }
+}