Maesh.js

caution

You can only test the Maesh.js library in a server environment, testing on local environments is not possible as the library expects a request origin for security. Maesh.js Testing Sandbox coming soon! 🎉

This reference will help you add Maesh to web pages with the browser-side Maesh.js library served from our CDN.

The Maesh.js library allows you to create QR codes for your consumers to scan and pay, as well as to check the payment status of orders.

Generate the API key

To use this library, you need a Maesh API key. Create an account with Maesh to generate an API key. If you already have an account, login to generate or copy your API key.

Once you're in Maesh Dashboard, go to Settings tab and find the API key section to generate or view your API key.

Generate a token

Including Maesh.js

Include the Maesh.js library on your checkout page or payment page by adding a script tag to the head​ tag of your HTML file.

<script src="https://js.maesh.io/v1.js">
</script>

Payment Checkout Page

An instance of the Maesh object can generate and display a QR code in your website page for the user to scan the QR and pay using any SG bank application supporting PayNow.

This is how the Maesh component will look like once it is successfully integrated. Once this payment is successfully completed, Maesh redirects the consumer to the URL (gotoUrl) that you provided.

Maesh Component

Initialise Maesh

Initialise the Maesh function by assigning it to a variable. This is the entry point into Maesh.js library for creating a Maesh component

const maesh = Maesh();

Create Maesh Component

Create an instance of Maesh in your website by calling the method ​create, which expects an object with below parameters as input.

maesh.create({ 
    api_key: '--YOUR_API_KEY--',
    dom_element_id: '--YOUR_ELEMENT_ID--',
    currency: 'SGD',
    amount: 21700,
    gotoUrl: 'https://merchant.com/success',
    referenceCode: 'ABCDEFGH'
    });

Below are the params used to configure the Maesh object.

ParamTypeDescription
api_keyStringYour API key. This key identifies you to Maesh. Eg. sk39Josr78Ko23Mjftlp(Dummy)
dom_element_idStringThis is the id of an empty HTML div element in your website, you want Maesh component to load in.
amountIntegerOnly ​positive integers​ allowed. Amount is in a currency's​ ​smallest unit. Maximum amount allowed is S$200,000 due to FAST transaction upper limit Eg. S$ 8.88 should be supplied as 888
currencyStringThe currency you want your payment to be received in. Maximum characters allowed is 3. Eg. Singapore Dollar is SGD
gotoUrlStringThe ​goto URL which will be invoked by Maesh after a payment status change has been detected i.e. maybe your order confirmation page. Eg. https://merchant.com/success
referenceCodeStringThe merchant’s reference code for the order. Should be unique. Maximum characters allowed is 10. Eg. ABCDEFGH

Redirected Page

Handling Callback in the redirected page

In the redirected page, you can include a Maesh callback function to check the status of the transaction to ensure that the payment has been completed correctly. This function will return the status of the transaction.

Initialise Maesh and call the Maesh callback function.

In the redirected page, you can initialise the Maesh function by assigning it to a variable.

The Maesh callback will return a promise. Resolving the promise will give you the status and can help you in rendering your redirected page conditionally.

// Include below code in a script tag
const maesh = Maesh();
const maeshStatus = maesh.callback();
// Resolve promise to get status
maeshStatus.then(
    status => { 
        // Do something with the status here
    });

The status response is a string and below table describes the different status you receive as case-sensitive response.

StatusDescription
SucceededPayment is successful and Maesh received the payment.
UnpaidPayment is still not done yet, waiting for payment to complete
Succeeded - Paid too muchPayment is successful and Maesh received extra money from consumer than requested.
CancelledPayment is unsuccessful and Maesh did received any payment.
ErrorPayment is not yet initiated or someone is trying to access redirect page directly.

What if the consumer closes the browser?

The consumer might close the browser after scanning the QR code or move to another app on mobile while the payment is still processing. In these scenarios Maesh would be unable to redirect consumer to order conformation page.

To get the status of payments even if pages are closed, we expose an API endpoint to get the status of payments which you can use to check on orders periodically.

API endpoint
https://api.staging2.maesh.io/status

Parameters and Response

The Maesh Status API uses the following:

MethodPOST
Body{"reference" : 'Reference_Code_of_Order', "key" : 'Your_API_Key'}
Headers"Content-type": "application/json"
Success Response{'response': 'success', 'status' : 'STATUS_OF_TRANSACTION'}
Error Response{'response': 'fail'}