Maesh.js

Maesh.js is a browser-side JavaScript library that lets you integrate Maesh into your platform. Maesh.js will take care of generating the QR and displaying it to the user to scan and pay and redirect user after a successful payment.

This documentation will help you to integrate Maesh either using the Vanilla JS CDN or the NPM library.

Not a developer? Get in touch with us.

Getting Started

Create a testing account with Maesh to get your testing API key. This testing account helps you to play around with the library, assess design changes on your end and trigger test payments to verfiy end-to-end flow. Once you're happy with testing, going live with Maesh is very easy.

If you already have a testing account, login to find your API key.

Request origin for Maesh Component

While creating an account, make sure you provide the Company Website field with the website URL which you'll use to make requests to the library. Maesh verifies the origin of request and only allows request from the provided Company Website.

Due to this, 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.

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 Testing API key

Login to Maesh Testing Dashboard, go to Settings tab, find the API key section and choose JS library as your plugin to generate your API key. If your API key is lost/compromised, generate a new API key.

https://dashboard.staging2.maesh.io/settings

warning

Do not share your API keys. Store them in your servers and fetch only when required.

Integration

How Maesh.js works

You include Maesh.js in your checkout/payment page to create a Maesh Component with QR for the customer to scan and pay.
Once the customer successfully completes the payment, Maesh redirects the customer to a redirect URL provided by you.
You can verify the payment on client-side using Maesh callback in your redirected page or using the Maesh Status API on the server-side.

Checkout/Payment Page

In your checkout or payment page, follow these steps

Include Maesh.js

HTML+JS
React

<!-- Include the script tag in the head tag of your HTML file. -->
<script src="https://js.maesh.io/v1.js"></script>

Create Maesh Component

HTML+JS
React

Parameters for Maesh Component (Click to toggle)

Parameter	Type	Description
`api_key`	String	Your API key. This key identifies you to Maesh. Eg. sk39Josr78Ko23Mjftlp(Dummy)
`dom_element_id`	String	This is the id of an empty HTML div element in your website, you want Maesh component to load in.
`amount`	Integer	Only 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
`currency`	String	The currency you want your payment to be received in. Maximum characters allowed is 3. Eg. Singapore Dollar is SGD
`gotoUrl`	String	The 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`
`referenceCode`	String	The merchant’s reference code for the order. Should be unique. Maximum characters allowed is 10. Eg. ABCDEFGH

<!-- Prepare an empty div to load the Maesh Component-->
<div id="maesh-component"></div>
<!-- Place this div where you want the component to load on your page -->

// Include below code in a script tag
const maesh = Maesh();
maesh.create({
  api_key: "--YOUR_API_KEY--",
  dom_element_id: "maesh-component",
  currency: "SGD",
  amount: 21700,
  gotoUrl: "https://merchant.com/success",
  referenceCode: "ABCDEFGH",
});

Maesh Component

After adding the code to create the Maesh Compoenent, this is how the component is going to load in your page. This is a mobile-friendly, responsive component built for all screen sizes and browsers.

https://merchant.com/payment

Trigger Test Payments

You can trigger successful test payments using our Maesh Test Payments developer tool to check how end-to-end flow looks like on your end.

Maesh Payment Status Verification

Maesh provides you options to verify the payment status on your client-side, server-side or both. You can choose any method suitable for you to drive your application.

Redirected Page (Client-Side Verification)

In the redirected page, include a Maesh callback function to check the status of the payment. This is to ensure that the current payment has been completed correctly. This function will return the status of the payment that happened in that session. This is the Client-Side verification. In your redirected page, follow these steps

What different status does Maesh send? (Click to toggle)

Status (string)	Description
`Succeeded`	Payment is successful and Maesh received the exact payment.
`Succeeded - Paid too much`	Payment is successful and Maesh received extra money from consumer than requested. This can be due to a duplicate payment from the customer.
`Pending - Paid too little`	Payment is successful and Maesh received less money from consumer than requested.
`Error`	Payment is not yet initiated or someone is trying to access redirect page directly.

Succeeded - Paid too much and Pending - Paid too little are special cases in the status that Maesh identified.

Succeeded - Paid too much, if you receive this status for any intent, proceed with your order confirmation, Maesh will take care of refunding the extra money to consumer.

Pending - Paid too little, a highly unlikely case to happen. Do not confirm your order if you receive this status.

All the data you receive is of type STRING

HTML+JS
React

<!-- Include the script tag in the head tag of your HTML file. -->
<script src="https://js.maesh.io/v1.js"></script>

To obtain the just the status of payment

// Include below code in a script tag

const maesh = Maesh();
const maeshStatus = maesh.callback();
// Resolve promise to get status of payment.
maeshStatus.then(
    status => // do something with the status
    )

To obtain status and other information (Maesh Transaction ID, Amount paid) of payment

> Send 'transaction_id' to the function to get the Maesh Transaction ID of the payment

// Include below code in a script tag

const maesh = Maesh();
const maeshStatus = maesh.callback('transaction_id');
// Resolve promise to get data of payment.
maeshStatus.then(
    data => {
            var status = data["status"];
            var transaction_id = data["transaction_id"]; // Based on your input
            
            // do something with the status, transaction ID.
    }
    )

> Send 'paid_amount' to the function to get the Amount paid in the payment

// Include below code in a script tag

const maesh = Maesh();
const maeshStatus = maesh.callback('paid_amount');
// Resolve promise to get data of payment.
maeshStatus.then(
    data => {
            var status = data["status"];
            var paid_amount = data["paid_amount"]; // Based on your input
            
            // do something with the status, amount paid.
    }
    )

> Send both 'transaction_id, 'paid_amount' to the function to get both Maesh Transaction ID, Amount paid

// Include below code in a script tag

const maesh = Maesh();
const maeshStatus = maesh.callback('transaction_id', 'paid_amount');
// Resolve promise to get data of payment.
maeshStatus.then(
    data => {
            var status = data["status"];
            var transaction_id = data["transaction_id"]; // Based on your input
            var paid_amount = data["paid_amount"]; // Based on your input
            
            // do something with the status, amount paid, transaction ID.
    }
    )

Maesh Payment Status (Server-Side Verification)

Maesh Payment Status helps you to get the status of a payment on your server. It can be used in two ways based on your requirement and setup.

Maesh Status Webhook (Recommended)
Maesh Status Endpoint

Maesh Status Webhook
Maesh Status Endpoint

This webhook is a URL, Maesh does a POST request with the status of payment of your reference_code after every successful payment. This is used to process real-time payment updates. You can use this to update order status on your end based on the status of payment that Maesh sends.

Default Webhook URL : your_company_website/maesh_order_confirmation

If you submitted your 'Company Website' as https://merchant.com then the webhook URL Maesh calls is

https://merchant.com/maesh_order_confirmation

If you did not setup the webhook URL in Settings Tab of Maesh Dashboard, you will not receive this request.

https://dashboard.staging2.maesh.io/settings

To setup the webhook, please change the Webhook URL field you want Maesh to POST the payment status and click on 'Set Webhook URL'. Once, it is successful, Maesh will send a POST request to that URL after every successful transaction for your reference_code

https://dashboard.staging2.maesh.io/settings

You can remove the Webhook URL by clicking 'Delete Webhook URL' and once successful, Maesh will not POST the payment status to that URL.

caution

This endpoint must be reachable from Maesh, so as to send you the status of payment. This feature is in beta testing and not available in production, please reach out to us at hello@maesh.io to test this feature.

Raw Request

POST /maesh_order_confirmation HTTP/1.1
Host: merchant.com
Content-Type: application/json
MAESH-SIGNATURE: *************************
Accept: */*
Content-Length: **

{
  "reference_code": "<your_order_reference_code>", 
  "transaction_id": "<maesh_transaction_id>",
  "paid_amount": "<amount_of_transaction>"
  "status":"<status_of_the_order>", 
  "timestamp" : "<timestamp_of_payment>"
}

To accept this you need to generate a HMAC (SHA256) hash in lowercase hexits from the body of request as message and use your Maesh API key as key to convert the message into hash.

message = body["reference_code"] + '-' + body["transaction_id"] + '-'+ body["timestamp"]

This is to make sure the request to the webhook is only from Maesh and not from any third-party websites. After the hash is generated, verify against the MAESH-SIGNATURE header sent in the request.

Only proceed to use the body of the request if these hashes match.

Please do not accept requests if there is no MAESH-SIGNATURE header or if the value doesn't match the HMAC (SHA256) hash in lowercase hexits output generated on your end.

Please refer to this GitHub gist for HMAC (SHA256) implementations in different languages. Remember to generate hash in lowercase hexits form.

Go live with Maesh

After testing the Maesh component on your platform and moving to production is very simple.

Create a Maesh Production account

Click here to create a Maesh Production Account.

Generate Maesh Production API key

Login to Maesh Dashboard, go to Settings tab, find the API key section and choose JS library as your plugin to generate your API key. If your API key is lost/compromised, generate a new API key.

https://dashboard.maesh.io/settings

You can setup Webhook URL in the same section as API key.

https://dashboard.maesh.io/settings

Changes

Replace all instances of testing with production.

Replace the testing API key with production API key.

Testing
Production

For HTML + JS

<!-- Include the script tag in the head tag of your HTML file. -->
<script src="https://js.maesh.io/v1.js"></script>

For React

# Install Maesh NPM library
npm install --save maesh-test

For Maesh Status Endpoint

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

Still have questions?

If you still have questions, please feel free to reach out to us at hello@maesh.io or through our chat widget at https://maesh.io.