Mojo Developers Program

Instamojo developers platform is created by Instamojo to collaborate with App developers across India, we aspire to solve problems faced by MSMEs in our country along with other like-minded solution providers. The developers can build apps and host it on Instamojo development platform. Instamojo sellers will be able to view the app from Instamojo app store (Android and web) and will be able to subscribe to the app.

This is a unique one of a kind opportunity for a developer/solution provider to work closely with Instamojo and get access to over 1 Million MSMEs on the platform and create a new revenue stream.

Features of Instamojo developer platform

APIs:

Instamojo developer platform will allow developers to access merchants data to create a solution. Following are the basic APIs Instamojo will expose in the first version

1. Merchant Profile API (Name, email, etc)
2. Merchant Payment API (Payment date, amount, etc)
3. Merchant Payout API (date, type, amount, etc)
4. Online Store API (Inventory, sales, etc)

APP:

Instamojo developer platform will enable developers to create an App that will be hosted by the developer on their end and will have the following information points shown on the Instamojo App store :

1. App Name
2. App Description
3. App Category
4. App Logo
5. App Images (Up to 5 high-quality images)
6. Video (Youtube video link - How to use the App)
7. Data Access Permissions requirement from the merchants
8. Price (In case the App is paid)
9. App URL (App to be hosted by the developer and a URL needs to be provided)
10. Redirect URI (For OAuth redirection)

In-App Purchases:

To start with developers can provide In-app purchases to the merchant. In the case of In-app purchases, developers will have to use Instamojo as the payment provider. The amount will be credited to the developer’s bank account on (T+3) days.

Merchant Flow:

Merchants can view all the App details (Name, description, etc) when they click on the App in the Instamojo App store. Once they subscribe to the App, the App opens on the Instamojo platform and sellers can access all the App features. The merchant needs to be validated by Instamojo token before they can get access to all the App features in case they open the App URL directly.

The below documentation explains the process of integrating your App with Instamojo App store and testing it on the sandbox environment.

SETUP

It is recommended that you test your integration in our sandbox environment before submitting the App for Approval on the production.

Steps :

1. Sign up on https://test.instamojo.com and create an app by generating new credentials at https://test.instamojo.com/integrations.

2. AUTHENTICATION FLOW - All the API interactions require you to have an authenticated credential. Use the client_id and client_secret obtained while creating an app to authenticate yourself against the API. We provide an access_token/refresh_token Oauth2 authentication.

The application(Your App) can ask the following 5 scopes explicitly:

• user-info: read (Data Points - Merchant Name, SignUp Date, City, Website)
• user-contact: read (Data Points - Merchant Email, Merchant Phone)
• products: read (Data Points - Product title, Price, Quantity, Is Shippable)
• payments: read (Data Points - Number of Payments, Amount in each payment, Payment Instrument, Payment Time)
• payouts: read (Data Points - Number of Payouts, Amount in each payout, Payout type, Charges)
• orders: read (Data Points - Buyer Email, Buyer Phone Number, Quantity of items bought, Unit Price)

4. Steps to generate oauth2 credentials, please follow the below steps :
   1. Go to https://test.instamojo.com/integrations.
   2. Scroll to Available Platform Plugins => Generate Credentials
   3. Click on +Generate New Credentials
   4. Select any platform from the drop-down and click on generate credentials
   5. You will get client_id and client_secret
   6. To get access to instamojo APIs developer has to send an email to ‘[email protected]’ requesting API access with username, email, platform (selected in 3rd step), client_id and scopes that are required for an app in the body. Also, please send redirect_uri to capture code after user authorization to an app.

5. Steps to generate an access token for the app user. The Oauth2 flow will work as described below

    1. Make GET request (From the front channel) on /oauth2/authorize - 
   

Request: https://test.instamojo.com/oauth2/authorize?scope=payments:read &redirect_uri=https://app.example.com/oauth2/callback
&response_type=code&client_id=812741506391&state=af0ifjsldkj

This is a GET request with a bunch of query params (not URL-encoded for example purposes). Scopes are from Instamojo's API. The redirect_uri is the URL of the client application that the authorization grant should be returned to. This should match the value from the client registration process (at the Instamojo). You don't want the authorization being bounced back to a foreign application. Response type varies the OAuth flows. Client ID is also from the registration process. The state is a security flag, similar to CSRF.

      2. If the above request is valid then the user is redirected to an authorize page (shown below)

         3. If the user authorizes the app for permissions, the user is redirected to the application. Response:

HTTP/1.1 302 Found
Location: https://app.example.com/oauth2/callback?
code=MsCeLvIaQm6bTrgtp7&state=af0ifjsldkj

The code returned is the authorization grant and state is to ensure it's not forged
and it's from the same request. This code is valid for 60 sec.

               4. After the Front Channel is done, a Back Channel Flow happens, exchanging the authorization code for an access token. The Developers (clients) application sends an access token request to the token endpoint on the Authorization Server with confidential client credentials and client id. This process exchanges an Authorization Code Grant for an Access Token and (optionally) a Refresh Token. The client accesses a protected resource with the Access Token. Below is how this looks in raw HTTP.

Request: POST /oauth2/token/ HTTP/1.1
Host: test.instamojo.com
Content-Type: application/x-www-form-urlencoded
code=MsCeLvIaQm6bTrgtp7&client_id=812741506391&client_secret={client_secret}&redirect_uri=https://app.example.com/oauth2/callback&grant_type=authorization_code

The grant_type is the extensibility part of OAuth. It's an authorization code from a precomputed perspective.

Response:
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

                5. Once you have an access token, you can use the access token in an Authentication header (using the token_type as a prefix) to make protected resource requests.

curl -H "Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA"
https://test.instamojo.com/v2/users/

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token.

curl --request POST
--url 'https://test.instamojo.com/oauth2/token'
--header 'content-type: application/x-www-form-urlencoded'
--data grant_type=refresh_token
--data 'client_id=YOUR_CLIENT_ID'
--data client_secret=YOUR_CLIENT_SECRET
--data refresh_token=YOUR_REFRESH_TOKEN

API Details

Below mentioned are the API request/response details

1. user-info API :

Request:

 Required Scope: user-info:read
     Header: Authorization: Bearer <your-token>

GET /v2/user-info/

Response:

[
{
"full_name": "Gavin Belson",
"signup_date": "2019-06-03",
"username": "gavinbelson17",
"city": null,
"website": "https://www.hooli.com"
}
]

User-Profile parameter Description:

2. user-contact API :

Request:
Required Scope: user-contact:read
Header: Authorization: Bearer
GET /v2/user-contact/

Response:
[
{
"full_name": "Gavin Belson",
"email": "[email protected]",
"phone": "+919876543212",
“username”: “gavin17”,
“account_id”: “0f9c251fc4d04765a1ccd246bf81b23b”,
}
]

User-Contact parameter Description:

3. Payments API :

Request:
Required Scope: payments:read
Header: Authorization: Bearer
GET /v2/payments

API Filters:

Response:
{
"count": 192,
"next": "https://test.instamojo.com/v2/payments/?page=2",
"previous": null,
"payments": [
{
"id": "MOJO9520R12A973123120",
"title": "test payment",
“payment_type”:”instapay”
"status": true,
"link": "https://test.instamojo.com/v2/links/l0e72e50122c04af7b62382380bfcba66/",
"product": null,
"seller": "https://test.instamojo.com/v2/users/3f5c511283a34e0c88e5bea4943a2c03/",
"currency": "INR",
"amount": "9494.00",
"name": "buyer",
"email": "[email protected]",
"phone": "+919876543210",
"payout": null,
"fees": "192.88",
"total_taxes": "34.72",
"cases": [],
"instrument_type": "CARD",
"billing_instrument": "International Regular Credit Card (Visa/Mastercard)",
"failure": null,
"created_at": "2019-05-20T09:30:23.808234Z",
"updated_at": "2019-05-24T07:45:04.639332Z",
"tax_invoice_id": "0355221229/000006",
"resource_uri": "https://test.instamojo.com/v2/payments/MOJO121520R05A97991120/"
},
….
….
]
}
}

Payment Parameter Description:

4. Payouts API :

Request:
Required Scope: payouts:read
Header: Authorization: Bearer

GET /v2/payouts

API Filters:

Response:
{
"count": 17,
"next": null,
"previous": null,
"payouts": [
{
"id": "MOJO9413001M10071018",
"recipient": "https://test.instamojo.com/v2/users/3f5c51c283a34e0c88e5bea4943a2c03/",
"status": true,
"paid_out_at": "2019-04-22T12:23:19.239722Z",
"currency": "INR",
"paid_amount": "1570.75",
"sales_amount": "26983.21",
"fee_amount": "1744.92",
"total_tax_amount": "314.24",
"held_amount": "0.00",
"reversed_amount": "3965.00",
"refunded_amount": "0.00",
"affiliate_commission_amount": "0.00",
"partner_commission_amount": "0.00",
"payout_type": 0,
"resource_uri": "https://test.instamojo.com/v2/payouts/MOJO9413001M10071018/",
"shipping_fee": "23386.42"
},
….
….
]
}
}

5. Products API :

Request:
Required Scope: products:read
Header: Authorization: Bearer

GET /v2/products

API Filters:

Response:
{
"count": 10,
"next": "https://test.instamojo.com/v2/products/?page=2",
"previous": null,
"products": [
{
“title": "test_product",
"description": "test product description",
"status": "Live",
"user": "https://test.instamojo.com/v2/users/3f5c51c283123e0c88e5bea4943a2c03/",
"slug": "test_product",
"shorturl": "https://imojo.in/test_product",
"currency": "INR",
"base_price": "25.00",
"min_price": "25.00",
"max_price": "25.00",
"pay_what_you_want": false,
"limit_quantity": null,
"purchased_quantity": 0,
"discount_public": false,
“product_type”:”physical”,
"requires_shipping": true,
"ships_within_days": 25,
"start_date": null,
"end_date": null,
"venue": null,
"timezone": null,
"redirect_url": null,
"redirect_time": 2000,
"webhook_url": null,
"custom_note_success": "",
"is_signing_mandatory": false,
"created_at": "2019-05-27T09:14:42.078152Z",
"resource_uri": "https://test.instamojo.com/v2/products/test_product/"
},
….
….
]
}
}

To get product images:
Required Scope: products:read
Header: Authorization: Bearer
GET /v2/products/<product_slug>/covers/

6. Orders API:

Request:
Required Scope: orders:read
Header: Authorization: Bearer
GET /v2/orders

API Filters:

Response:

{
"count": 30,
"num_pages": 1,
"next": null,
"previous": null,
"orders": [
{
"id": "4d0d5054-5f19-4ce8-b0b7-ee7a01442297",
"title": "MacBook pro",
"currency": "INR",
"created_at": "2019-07-02T11:16:43.313684Z",
"buyer_email": "[email protected]",
"buyer_name": "Litesh Patil",
"buyer_phone": "9790707007",
"buyer_address": "17, 7th Cross road, Bengaluru",
"buyer_city": "Bengaluru",
"buyer_state": "Karnataka",
"buyer_zip": "560034",
"buyer_country": "India",
"amount": "70000.00",
"order_status": "Fully Paid",
"payments_uri": "http://localhost:5000/v2/payments/?order_id=4d0d5054-5f19-4ce8-b0b7-
ee7a01442297",
"payments": [
{
"payment_id": "MOJO9702J00A09128126",
"amount": "70000.00",
"instrument_type": "CARD",
"status": "Success",
"resource_uri": "http://localhost:5000/v2/payments/MOJO9702J00A09128126/"
}
],
"items": [
{
"unit_price": "50000.00",
"quantity": 1,
"amount": "70000.00",
"is_shipping_required": true,
"seller": "http://localhost:5000/v2/users/0f9c251fc4d04765a1ccd246bf81b34b/",
"shipping_charge_logic": null,
"shipping_charges": null,
"product": "http://localhost:5000/v2/products/macbook-pro/",
"order": "http://localhost:5000/v2/orders/4d0d5054-5f19-4ce8-b0b7-ee7a01442297/",
"discount": null,
"variants": [
"http://localhost:5000/v2/products/macbook-pro/variant_categories/1/variants/1/"
]
}
]
},