mmpay-browser-sdk 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.vscode/settings.json +33 -0
- package/README.md +151 -0
- package/dist/cjs/index.d.ts +129 -0
- package/dist/cjs/index.js +469 -0
- package/dist/esm/index.d.ts +129 -0
- package/dist/esm/index.js +465 -0
- package/dist/mmpay-sdk.js +476 -0
- package/dist/mmpay-sdk.js.map +1 -0
- package/package.json +51 -0
- package/rollup.config.js +41 -0
- package/src/index.ts +529 -0
- package/test/home.html +243 -0
- package/tsconfig.cjs.json +7 -0
- package/tsconfig.json +15 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"editor.rulers": [
|
|
3
|
+
80
|
|
4
|
+
],
|
|
5
|
+
"editor.tabCompletion": "on",
|
|
6
|
+
"editor.tabSize": 2,
|
|
7
|
+
"editor.trimAutoWhitespace": true,
|
|
8
|
+
"editor.formatOnSave": true,
|
|
9
|
+
"editor.codeActionsOnSave": {
|
|
10
|
+
"source.organizeImports": "explicit",
|
|
11
|
+
"source.fixAll.eslint": "explicit"
|
|
12
|
+
},
|
|
13
|
+
"files.exclude": {
|
|
14
|
+
"**/.DS_Store": true,
|
|
15
|
+
"**/.git": true,
|
|
16
|
+
"**/.angular": true,
|
|
17
|
+
"**/.hg": true,
|
|
18
|
+
"**/.svn": true,
|
|
19
|
+
"**/CVS": true,
|
|
20
|
+
"**/node_modules": true,
|
|
21
|
+
"**/keys": true,
|
|
22
|
+
},
|
|
23
|
+
"files.insertFinalNewline": true,
|
|
24
|
+
"files.trimTrailingWhitespace": true,
|
|
25
|
+
"typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces": false,
|
|
26
|
+
"typescript.preferences.quoteStyle": "single",
|
|
27
|
+
"eslint.run": "onSave",
|
|
28
|
+
"eslint.nodePath": "./node_modules",
|
|
29
|
+
"eslint.validate": [
|
|
30
|
+
"javascript",
|
|
31
|
+
"typescript"
|
|
32
|
+
]
|
|
33
|
+
}
|
package/README.md
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Supa JavaScript SDK
|
|
2
|
+
## 💳 Introduction
|
|
3
|
+
Welcome to the **Supa JavaScript SDK**! This library provides a secure and seamless way to integrate QR Code and Bank Redirect payments into any e-commerce checkout flow.
|
|
4
|
+
Developed using **TypeScript**, the SDK offers a clean, type-safe interface and handles complex tasks like API communication, UI rendering, and asynchronous payment status polling automatically.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 🛠️ Installation
|
|
9
|
+
The Supa SDK is distributed as a single JavaScript file, ready for direct inclusion.
|
|
10
|
+
|
|
11
|
+
### Step 1: Include the SDK
|
|
12
|
+
Embed the following `<script>` tag into the `<head>` or before the closing `</body>` tag of your checkout page.
|
|
13
|
+
```html
|
|
14
|
+
<script src="https://browser.myanmyanpay.com/v1/sdk.js"></script>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
### Step 2: Set up the Payment Container
|
|
18
|
+
Create a simple HTML element where the SDK will render the payment-specific UI (the QR code and redirect link).
|
|
19
|
+
```html
|
|
20
|
+
<div id="mmpay-checkout-widget"> </div>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 🚀 Usage
|
|
26
|
+
The `MMQRMerchant` class provides two distinct methods to suit different integration needs.
|
|
27
|
+
|
|
28
|
+
### 1. `showPaymentModal()` (Recommended: UI + Polling)
|
|
29
|
+
This is the easiest way to integrate. This method **initiates the transaction**, **renders the UI** (QR code/Redirect link) into your container, and automatically **polls your gateway** for payment completion status, executing a callback when the payment is final.
|
|
30
|
+
|
|
31
|
+
#### **Method Signature**
|
|
32
|
+
```typescript
|
|
33
|
+
showPaymentModal(
|
|
34
|
+
containerId: string,
|
|
35
|
+
paymentData: PaymentData,
|
|
36
|
+
onComplete: (result: PaymentResult) => void
|
|
37
|
+
): Promise<void>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
#### **Example Implementation**
|
|
41
|
+
```javascript
|
|
42
|
+
document.getElementById('place-order-button').addEventListener('click', () => {
|
|
43
|
+
const MMPay = new MMPaySDK('pk_live_YOUR_PUBLISHABLE_KEY');
|
|
44
|
+
const paymentDetails = {
|
|
45
|
+
amount: 50000,
|
|
46
|
+
orderId: 'ORD-' + new Date().getTime(),
|
|
47
|
+
callbackUrl: 'https://your-merchant-site.com/payment-confirmation' // Redirect URL after mobile payment
|
|
48
|
+
};
|
|
49
|
+
MMPay.showPaymentModal(
|
|
50
|
+
'mmpay-checkout-widget', // ID of the container element
|
|
51
|
+
paymentDetails,
|
|
52
|
+
(result) => {
|
|
53
|
+
// This callback fires ONLY after the payment is completed, failed, or expired.
|
|
54
|
+
if (result.success) {
|
|
55
|
+
console.log(`Payment confirmed! Transaction ID: ${result.transactionId}`);
|
|
56
|
+
// Redirect user to the success page
|
|
57
|
+
window.location.href = `/thank-you?txn=${result.transactionId}`;
|
|
58
|
+
} else {
|
|
59
|
+
console.error(`Payment failed: ${result.message}`);
|
|
60
|
+
// Update the UI to show the failure message
|
|
61
|
+
document.getElementById('mmpay-checkout-widget').innerHTML = `Payment failed: ${result.message}`;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
);
|
|
65
|
+
});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### 2. `createPaymentRequest()` (Advanced: JSON Only)
|
|
69
|
+
Use this method if you need to build a fully **custom user interface** or if you are only initiating the request from the client and handling polling/UI on your server. This method returns the raw QR/Redirect URLs in JSON format.
|
|
70
|
+
|
|
71
|
+
#### **Method Signature**
|
|
72
|
+
```typescript
|
|
73
|
+
createPaymentRequest(paymentData: PaymentData): Promise<CreatePaymentResponse>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
#### **Example Implementation**
|
|
77
|
+
```javascript
|
|
78
|
+
document.getElementById('get-qr-data').addEventListener('click', async () => {
|
|
79
|
+
const Supa = new MMQRMerchant('pk_live_YOUR_PUBLISHABLE_KEY');
|
|
80
|
+
const paymentDetails = {
|
|
81
|
+
amount: 100.00,
|
|
82
|
+
currency: 'USD',
|
|
83
|
+
orderId: 'CUST-API-' + Date.now()
|
|
84
|
+
};
|
|
85
|
+
try {
|
|
86
|
+
const response = await Supa.createPaymentRequest(paymentDetails);
|
|
87
|
+
|
|
88
|
+
if (response.success) {
|
|
89
|
+
console.log('Transaction initiated:', response.transactionId);
|
|
90
|
+
console.log('QR Code URL:', response.qrCodeUrl);
|
|
91
|
+
// Use response.qrCodeUrl and response.redirectUrl to build your custom UI
|
|
92
|
+
} else {
|
|
93
|
+
console.error('Initiation failed:', response.error);
|
|
94
|
+
}
|
|
95
|
+
} catch (error) {
|
|
96
|
+
console.error("API call error:", error);
|
|
97
|
+
}
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## 🧪 Testing and Environments
|
|
104
|
+
The SDK supports easy and secure switching between Sandbox (Test) and Production (Live) environments.
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
### Environment Configuration
|
|
108
|
+
The environment is set during SDK initialization using the `options` object.
|
|
109
|
+
| Option | Value | API Base URL | Key Type | Purpose |
|
|
110
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
111
|
+
| `environment` | `'production'` (Default) | `https://api.Supa.com/v1` | `pk_live_...` | Live transactions with real money. |
|
|
112
|
+
| `environment` | `'sandbox'` | `https://sandbox.api.Supa.com/v1` | `pk_test_...` | Testing and development (no money exchanged). |
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
### Example: Sandbox Initialization
|
|
116
|
+
Always use **Sandbox Mode** with your **Test Publishable Key** (`pk_test_...`) for development.
|
|
117
|
+
```javascript
|
|
118
|
+
// Test key and environment must match!
|
|
119
|
+
const SupaTest = new MMQRMerchant('pk_test_XYZ789', {
|
|
120
|
+
environment: 'sandbox', // <-- Activates the test API URL
|
|
121
|
+
pollInterval: 2000 // Optional: change polling frequency (default is 3000ms)
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
// Now call methods on the test instance
|
|
125
|
+
SupaTest.showPaymentModal(/* ... */);
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
## 🧑💻 Development & Contribution
|
|
132
|
+
If you are modifying the SDK code itself (`MMQRMerchant.ts`), use the following commands.
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
### Dependencies
|
|
136
|
+
Ensure you have Node.js and TypeScript installed globally or locally:
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
npm install typescript --save-dev
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Build Command
|
|
144
|
+
|
|
145
|
+
Use the defined script to compile the TypeScript source into the final JavaScript file for distribution.
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npm run build
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
This command cleans the old output and compiles `MMQRMerchant.ts` into `dist/MMQRMerchant.js`.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
export interface PaymentData {
|
|
2
|
+
amount: number;
|
|
3
|
+
currency: string;
|
|
4
|
+
orderId: string;
|
|
5
|
+
callbackUrl?: string;
|
|
6
|
+
}
|
|
7
|
+
export interface CreatePaymentResponse {
|
|
8
|
+
_id: string;
|
|
9
|
+
amount: number;
|
|
10
|
+
orderId: string;
|
|
11
|
+
currency: string;
|
|
12
|
+
transactionId: string;
|
|
13
|
+
qr: string;
|
|
14
|
+
url: string;
|
|
15
|
+
}
|
|
16
|
+
export interface PollingResponse {
|
|
17
|
+
_id: string;
|
|
18
|
+
appId: string;
|
|
19
|
+
orderId: string;
|
|
20
|
+
amount: number;
|
|
21
|
+
currency: string;
|
|
22
|
+
method?: string;
|
|
23
|
+
vendor?: string;
|
|
24
|
+
callbackUrl?: string;
|
|
25
|
+
callbackUrlStatus?: 'PENDING' | 'SUCCESS' | 'FAILED';
|
|
26
|
+
callbackAt?: Date;
|
|
27
|
+
disbursementStatus?: 'NONE' | 'PENDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
|
|
28
|
+
disburseAt?: Date;
|
|
29
|
+
items: {
|
|
30
|
+
name: string;
|
|
31
|
+
amount: number;
|
|
32
|
+
quantity: number;
|
|
33
|
+
}[];
|
|
34
|
+
merchantId: string;
|
|
35
|
+
status: 'PENDING' | 'SUCCESS' | 'FAILED' | 'EXPIRED';
|
|
36
|
+
createdAt: Date;
|
|
37
|
+
transactionRefId?: string;
|
|
38
|
+
qr?: string;
|
|
39
|
+
redirectUrl?: string;
|
|
40
|
+
}
|
|
41
|
+
export interface PolliongResult {
|
|
42
|
+
success: boolean;
|
|
43
|
+
transaction: PollingResponse;
|
|
44
|
+
}
|
|
45
|
+
export interface SDKOptions {
|
|
46
|
+
pollInterval?: number;
|
|
47
|
+
environment?: 'sandbox' | 'production';
|
|
48
|
+
baseUrl?: string;
|
|
49
|
+
merchantName?: string;
|
|
50
|
+
}
|
|
51
|
+
export declare class MMPaySDK {
|
|
52
|
+
private POLL_INTERVAL_MS;
|
|
53
|
+
private publishableKey;
|
|
54
|
+
private baseUrl;
|
|
55
|
+
private merchantName;
|
|
56
|
+
private environment;
|
|
57
|
+
private pollIntervalId;
|
|
58
|
+
private onCompleteCallback;
|
|
59
|
+
private overlayElement;
|
|
60
|
+
private pendingApiResponse;
|
|
61
|
+
private pendingPaymentPayload;
|
|
62
|
+
private readonly QR_SIZE;
|
|
63
|
+
constructor(publishableKey: string, options?: SDKOptions);
|
|
64
|
+
/**
|
|
65
|
+
* _callApi
|
|
66
|
+
* @param endpoint
|
|
67
|
+
* @param data
|
|
68
|
+
* @returns
|
|
69
|
+
*/
|
|
70
|
+
private _callApi;
|
|
71
|
+
/**
|
|
72
|
+
* createPaymentRequest
|
|
73
|
+
* @param {PaymentData} payload
|
|
74
|
+
* @returns
|
|
75
|
+
*/
|
|
76
|
+
createPaymentRequest(payload: PaymentData): Promise<CreatePaymentResponse>;
|
|
77
|
+
/**
|
|
78
|
+
* _createAndRenderModal
|
|
79
|
+
* @param {string} contentHtml
|
|
80
|
+
* @param isTerminal
|
|
81
|
+
* @returns
|
|
82
|
+
*/
|
|
83
|
+
private _createAndRenderModal;
|
|
84
|
+
/**
|
|
85
|
+
* showPaymentModal
|
|
86
|
+
* @param {PaymentData} payload
|
|
87
|
+
* @param {Function} onComplete
|
|
88
|
+
*/
|
|
89
|
+
showPaymentModal(payload: PaymentData, onComplete: (result: PolliongResult) => void): Promise<void>;
|
|
90
|
+
/**
|
|
91
|
+
* _renderQrModalContent
|
|
92
|
+
* @param {CreatePaymentResponse} apiResponse
|
|
93
|
+
* @param {PaymentData} payload
|
|
94
|
+
* @param {string} merchantName
|
|
95
|
+
*/
|
|
96
|
+
private _renderQrModalContent;
|
|
97
|
+
/**
|
|
98
|
+
* _showTerminalMessage
|
|
99
|
+
* @param {string} orderId
|
|
100
|
+
* @param {string} status
|
|
101
|
+
* @param {string} message
|
|
102
|
+
*/
|
|
103
|
+
private _showTerminalMessage;
|
|
104
|
+
/**
|
|
105
|
+
* _showCancelConfirmationModal
|
|
106
|
+
*/
|
|
107
|
+
private _showCancelConfirmationModal;
|
|
108
|
+
/**
|
|
109
|
+
* _reRenderPendingModalInstance
|
|
110
|
+
*/
|
|
111
|
+
private _reRenderPendingModalInstance;
|
|
112
|
+
/**
|
|
113
|
+
* Cleans up the modal and stops polling.
|
|
114
|
+
* @param restoreBodyScroll
|
|
115
|
+
*/
|
|
116
|
+
private _cleanupModal;
|
|
117
|
+
/**
|
|
118
|
+
* _injectQrScript
|
|
119
|
+
* @param {string} qrData
|
|
120
|
+
* @param {string} qrCanvasId
|
|
121
|
+
*/
|
|
122
|
+
private _injectQrScript;
|
|
123
|
+
/**
|
|
124
|
+
* _startPolling
|
|
125
|
+
* @param {string} _id
|
|
126
|
+
* @param {Function} onComplete
|
|
127
|
+
*/
|
|
128
|
+
private _startPolling;
|
|
129
|
+
}
|