API Reference
Log In
Mojo Developers Program

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)
  1. 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.

  2. 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)
862
         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.

900
               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:

Data PointsSignificance
full_nameFull name of the merchant
signup_dateThe date of joining of the merchant on Instamojo
CityRegistered city of the merchant
WebsiteThe public website of the merchant
  1. 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:

Data PointsSignificance
Full_nameFull name of the merchant
EmailEmail of merchant
PhoneThe contact number of the merchant
  1. Payments API :

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

API Filters:

Query ComponentsSignificanceExample
idpayment id/v2/payments?id=MOJO9618N05A3131214
buyerusername or account idv2/payments?buyer=username
sellerusername or account idv2/payments?seller=username
payoutpayout idv2/payments?payout=MOJO9423001M54251388
productproduct slugv2/payments?product=product_slug
min_created_atdate-timev2/payments?min_updated_at=2019-06-18T08:54:39.1127
max_created_atdate-timev2/payments?max_created_at=2019-06-18T08:54:39.1127
min_updated_atdate-timev2/payments?min_updated_at=2019-06-18T08:54:39.1127
max_updated_atdate-timev2/payments?max_updated_at=2019-06-18T08:54:39.1127
order_idorder idv2/payments?order_id=f0a3effe-21c1-450c-8bbb-a0066b09

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:

Data PointsSignificanceValues
idPayment Id
titleTitle of Payment
payment_typeType of PaymentVAN = payment form virtual_account
instapay = payment from Instapay
Dashboard_Smart_Link = Smart link payment

Dashboard_Link = Quick link payment
Dashboard_Product = Dashboard product payment
api_rap = payment from v2 api
dashboard_rap = payment from dashboard
sdk = payment from sdk
mojoPOS = QR code payment
StatusPayment StatusTrue = Payment is successful
False = Payment failed
None = Payment is pending
linkURL to a payment link
productURL to product
sellerURL to seller details
currencyType of Currency (INR)
amountPayment Amount
nameBuyer's name for this payment
emailSender's email for this payment
phoneSender's phone for this payment
payout idPayout of the primary merchant
feesFees charged to the primary merchant for this payment
total_taxesTotal tax to a primary merchant for this payment
cases (disputes)URL for case
instrument_typeInstrument type used for paymentCLAIM = 'CLAIM'
SOCIALPAY = 'SOCIALPAY'
USD = 'USD'
PROMO = 'PROMO'
CARD = 'CARD'
NETBANKING = 'NETBANKING'
EMI = 'EMI'
WALLET = 'WALLET'
UPI = 'UPI'
BANK_TRANSFER = 'BANK TRANSFER'
QR_CODE = 'QR'
billing_instrumentBilling InstrumentInternational Regular Credit Card (Visa/Mastercard)
Domestic Regular Credit Card (Visa/Mastercard)
Domestic Netbanking Category A or B
Unknown netbanking choice
Promo Payment, etc
failureFailure Reason/MessageAUTHENTICATION_FAILED
AUTHORIZATION_FAILED
DROPPED, CANCELLED, EXPIRED, etc
created_atDate of Payment Creation
updated_atDate of payment update
tax_invoice_idMerchant Tax Invoice ID
resource_uriresource URI for this payment
  1. Payouts API :

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

GET /v2/payouts

API Filters:

Query componentsSignificanceExample
idpayout id/v2/payouts?id=MOJO9423001M54251388
start_timepaid out date/time/v2/payouts?start_time=2019-06-18T04:59:37.227712Z
end_timepaid out date/time/v2/payouts?end_time=2019-06-18T04:59:37.227712Z

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"
},
….
….
]
}
}

  1. Products API :

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

GET /v2/products

API Filters:

Query ComponentsSignificanceExample
created_aftercreated date-time timezone=ufcv2/products?created_after=2019-06-18T04:59:37.227712Z
created_beforecreated date-time timezone=ufcv2/products?created_before=2019-06-18T04:59:37.227712Z
statusProduct status
Live = 20
Archived = 30
Pending Moderation = 33
v2/orders?status=20

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/

  1. Orders API:

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

API Filters:

Query componentsSignificanceExample
created_aftercreated date-time timezone=utcv2/orders?created_after=2019-06-18T04:59:37.227712Z
created_beforecreated date-time timezone=utcv2/orders?created_before=2019-06-18T04:59:37.227712Z
pendingpending = True (or 1)
i.e. exclude all the orders with successful payment

pending = False (or 0)
i.e. only include orders with successful payment
v2/orders?pending=True

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/"
]
}
]
},