API Reference
Log In
API Reference

Integration Guide

Integration Steps

❗️

Restricted Access

The Marketplace API is available only to select customers based on their business needs.
Regular Instamojo API credentials will not work for the Marketplace API.

For credentials related to Marketplace API contact [email protected] and specify your platform (production/sandbox).

Authentication Flow

All API interactions required you to have a authentication credentials. Use the client_id and client_secret to authenticate yourself against the API. There are three kinds of authentication:

  1. Application Based - This gives you extra privileges like creating an account on Instamojo.

  2. User Based - This gives you privileges for performing actions on a user's account. For eg: updating their name and location, creating payment links on their behalf, etc.

  3. Refresh Token Based - An access_token obtained via the User Based authentication will expire in 36000 seconds. But it also gives a refresh_token, which can be used to obtain a new pair of access_token and refresh_token without the need for the username and password.

Signup Flow

  1. Use Application Based Authentication to get an access_token.

  2. Use this access_token to create a user on Instamojo. Here you should use a valid email id and a password. Ensure that you are not storing the password in your system. On signup, you will receive a unique id for the user, which will be used henceforth to identify the user.

  3. Use User Based Authentication to get an access_token. You will need the password for the first time when you are requesting an access_token in this step. Going forward, you must store the access_token and refresh_token safely in your database, and discard the password that you had used. If the current access_token expires, you should use the Refresh Token Based authentication to get a new pair of access_token and refresh_token.

  4. Use this access_token to update the bank account details of the user.

Payment flow

  1. Use User Based Authentication to get an access_token.

  2. Use this access_token to create a payment link.

  3. Send the payment link to the buyer.

  4. When the payment is complete, we will send you a webhook request or redirect the buyer to your redirect_url depending on the mode chosen by you while creating the payment link.

Additional Features

  1. Refunds - Use this feature if you want to refund the complete or partial amount for a payment.

  2. Collecting fees - Use this feature if you want to collect a commission fee on each transaction that you drive via your marketplace.

  3. Hold and Release - You can specify to hold a payment until you are confident that the buyer has received the services for their payment. Once you tell us to release the payment, only then the merchant will be paid out.

  4. Light Checkout - You can use this to display only the payment form. This is useful if you are going to use this in a mobile app or within your website. To use this feature, simply append ?embed at the end of the payment link.