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
Generate a token

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

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

Create Maesh Component

Parameters for Maesh Component (Click to toggle)
ParameterTypeDescription
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

<!-- 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
Maesh Component

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
SucceededPayment is successful and Maesh received the exact payment.
Succeeded - Paid too muchPayment is successful and Maesh received extra money from consumer than requested. This can be due to a duplicate payment from the customer.
Unpaid - Paid too littlePayment is successful and Maesh received less money from consumer than requested.
ErrorPayment is not yet initiated or someone is trying to access redirect page directly.

Succeeded - Paid too much and Unpaid - 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.

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

<!-- Include the script tag in the head​ tag of your HTML file. -->
<script src="https://js.maesh.io/v1.js"></script>
// 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
    )

Maesh Status API (Server-Side Verification)

Maesh Status API 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 Endpoint
  • Maesh Status Webhook (Coming Soon 🎉) (Beta)

Maesh Status Endpoint

Maesh exposes a status endpoint for POST request to check the payment status of orders periodically.

Use the status accordingly to proceed with your orders on your server.

What different status does Maesh send? (Click to toggle)
Status (string)Description
SucceededPayment is successful and Maesh received the exact payment.
Succeeded - Paid too muchPayment is successful and Maesh received extra money from consumer than requested. This can be due to a duplicate payment from the customer.
UnpaidPayment is not done yet, waiting for payment to complete.
Unpaid - Paid too littlePayment is successful and Maesh received less money from consumer than requested.

Succeeded - Paid too much and Unpaid - 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.

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


Request

POST

Endpoint

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

Headers

Content-Type: application/json

Body

{
  "reference": "Reference_Code_of_Order",
  "key": "Your_API_Key"
}

Success Response 200 OK

{
  "response": "success",
  "status": "STATUS_OF_TRANSACTION"
}

Failed Response 400 BAD REQUEST

{
  "response": "fail",
  "error": "ERROR_MESSAGE"
}

Maesh Status Webhook (Beta)

This webhook is a URL Maesh will call (POST request) with the status of payment of your reference_code. 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.

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

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>", 
  "status":"<status_of_the_order>", 
  "timestamp" : "<timestamp_of_payment>"
}

To accept this you need to generate a HMAC (SHA256) hash 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 update your order if these hashes matches.

Please do not accept requests if there is no MAESH_SIGNATURE header or if the value doesn't match the HMAC (SHA256) hash generated on your end.

Please refer to this GitHub gist for HMAC (SHA256) implementations in different languages.

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
Generate a token

Changes

Replace all instances of testing with production.

Replace the testing API key with production API key.
<!-- Include the script tag in the head​ tag of your HTML file. -->
<script src="https://js.maesh.io/v1.js"></script>
# Install Maesh NPM library
npm install --save maesh-test
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.