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 with your marketplace Client ID & Client Secret to get an access_token.

2. Use this access_token to create a user on Instamojo using Signup API. Here you should use a valid email id and a random 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_tokenusing the username & password from above 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 bank details of a user.

Payment Flow

1. Use User Based Authentication with your marketplace Client ID & Client Secret to get an access_token.

2. Use this access_token to Create a Payment Request.

3. Present the payment link created above to the buyer. Your can either redirect the merchant to this page, or use our Javascript SDK on web.

4. Once the buyer completes the payment, Instamojo will trigger a webhook to your servers as well redirect the buyer to the redirect_url you provided in step 2.

5. At this stage, the amount (& fees) is credited against the marketplace account. The marketplace can send all or parts of the amounts to individual sub-merchants using Create a Settlement API by sending type as CREDIT.

6. Once all the redistributions are done, the marketplace marks the payment as fulfilled using Fulfil a Payment API. The remaining balance is considered as marketplace’s commission, which gets paid out to marketplace’s bank account.

Key Points to Note

1. Marketplace can credit to their sub-merchants only upto a total of transaction amount (i.e; the amount paid by the buyer).
2. Crediting to sub-merchants work only till the payment gets marked as fulfilled. Once payment is marked as fulfilled, the distribution is deemed final.

Refund Flow

1. Marketplace can initiate a full / partial refund to the buyer using Create a Refund. This will deduct the amount from the marketplace and send it to the buyer.
2. The marketplace can then use the Create a Settlement to deduct from the individual / multiple sub-merchants by sending type as a DEBIT.

Key Points to Note

1. You can debit a sub-merchant only in case of refunds.
2. Only sub-merchants that were earlier credited for this payment can be debited by marketplace.
3. Marketplace can debit sub-merchants only upto refund amount.
4. A sub-merchant can be debited only if they have sufficient balance with Instamojo.