{"title":"Mojo Developers Program","slug":"mojo-developers-program","body":"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. \n\nThis 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. \n\nFeatures of Instamojo developer platform\n\nAPIs: \n\nInstamojo 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\n1. Merchant Profile API (Name, email, etc)\n2. Merchant Payment API (Payment date, amount, etc)\n3. Merchant Payout API (date, type, amount, etc)\n4. Online Store API (Inventory, sales, etc)\n\nAPP: \n\nInstamojo 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 :\n1. App Name\n2. App Description\n3. App Category \n4. App Logo\n5. App Images (Up to 5 high-quality images)\n5. Video (Youtube video link - How to use the App)\n6. Data Access Permissions requirement from the merchants\n7. Price (In case the App is paid)\n8. App URL (App to be hosted by the developer and a URL needs to be provided)\n9. Redirect URI (For OAuth redirection)\n\nIn-App Purchases: \n\nTo 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.\n\nMerchant Flow: \n\nMerchants 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.\n\n\nThe below documentation explains the process of integrating your App with Instamojo App store and testing it on the sandbox environment.\n\nSETUP\n\nIt is recommended that you test your integration in our sandbox environment before submitting the App for Approval on the production. \n\nSteps :\n\n1. Sign up on https://test.instamojo.com and create an app by generating new credentials at https://test.instamojo.com/integrations. \n  \n2. 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.\n\nThe application(Your App) can ask the following 5 scopes explicitly:\n\n  * user-info: read (Data Points - Merchant Name, SignUp Date, City, Website)\n  * user-contact: read (Data Points - Merchant Email, Merchant Phone)\n  * products: read (Data Points - Product title, Price, Quantity, Is Shippable)\n  * payments: read (Data Points - Number of Payments, Amount in each payment, Payment Instrument, Payment Time)\n  * payouts: read (Data Points - Number of Payouts, Amount in each payout, Payout type, Charges)\n  * orders: read (Data Points - Buyer Email, Buyer Phone Number, Quantity of items bought, Unit Price)\n\n  \n4. Steps to generate oauth2 credentials, please follow the below steps : \n          1. Go to https://test.instamojo.com/integrations. \n          2. Scroll to Available Platform Plugins => Generate Credentials\n          3. Click on +Generate New Credentials\n          4. Select any platform from the drop-down and click on generate credentials\n          5. You will get client_id and client_secret\n          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.\n\n5. Steps to generate an access token for the app user. The Oauth2 flow will work as described below\n \n         1. Make GET request (From the front channel) on /oauth2/authorize - \n\nRequest: https://test.instamojo.com/oauth2/authorize?scope=payments:read &redirect_uri=https://app.example.com/oauth2/callback \n&response_type=code&client_id=812741506391&state=af0ifjsldkj\n\nThis 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.\n\n\n          2. If the above request is valid then the user is redirected to an authorize page (shown below)\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/84fe566-Screenshot_2019-08-07_13.06.33.png\",\n        \"Screenshot 2019-08-07 13.06.33.png\",\n        862,\n        482,\n        \"#e8e9e9\"\n      ]\n    }\n  ]\n}\n[/block]\n             3. If the user authorizes the app for permissions, the user is redirected to the application. Response:\n\nHTTP/1.1 302 Found\nLocation: https://app.example.com/oauth2/callback?\ncode=MsCeLvIaQm6bTrgtp7&state=af0ifjsldkj\n\t\n\nThe code returned is the authorization grant and state is to ensure it's not forged\nand it's from the same request. This code is valid for 60 sec.\n\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/62255fe-Screenshot_2019-08-07_13.09.20.png\",\n        \"Screenshot 2019-08-07 13.09.20.png\",\n        900,\n        460,\n        \"#c8d6da\"\n      ]\n    }\n  ]\n}\n[/block]\n                   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.\n\nRequest: POST /oauth2/token/ HTTP/1.1\nHost: test.instamojo.com\nContent-Type: application/x-www-form-urlencoded\ncode=MsCeLvIaQm6bTrgtp7&client_id=812741506391&client_secret={client_secret}&redirect_uri=https://app.example.com/oauth2/callback&grant_type=authorization_code\n\n\nThe grant_type is the extensibility part of OAuth. It's an authorization code from a precomputed perspective. \n\nResponse:\n{\n  \"access_token\": \"2YotnFZFEjr1zCsicMWpAA\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600,\n  \"refresh_token\": \"tGzv3JOkF0XG5Qx2TlKWIA\"\n}\n\n\n                    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.\n\ncurl -H \"Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA\" \\\n  https://test.instamojo.com/v2/users/\n\nTo 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.\n\ncurl --request POST \\\n  --url 'https://test.instamojo.com/oauth2/token' \\\n  --header 'content-type: application/x-www-form-urlencoded' \\\n  --data grant_type=refresh_token \\\n  --data 'client_id=YOUR_CLIENT_ID' \\\n  --data client_secret=YOUR_CLIENT_SECRET \\\n  --data refresh_token=YOUR_REFRESH_TOKEN\n\n\n\nAPI Details\n\nBelow mentioned are the API request/response details\n\n\n1. user-info API : \n\n Request:\n\n\t Required Scope: user-info:read\n         Header: Authorization: Bearer <your-token>\n\nGET /v2/user-info/\n\nResponse:\n\n[\n    {\n        \"full_name\": \"Gavin Belson\",\n        \"signup_date\": \"2019-06-03\",\n        \"username\": \"gavinbelson17\",\n        \"city\": null,\n        \"website\": \"https://www.hooli.com\"\n    }\n]\n\n\nUser-Profile parameter Description:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data Points\",\n    \"h-1\": \"Significance\",\n    \"0-0\": \"full_name\",\n    \"0-1\": \"Full name of the merchant\",\n    \"1-0\": \"signup_date\",\n    \"1-1\": \"The date of joining of the merchant on Instamojo\",\n    \"2-0\": \"City\",\n    \"2-1\": \"Registered city of the merchant\",\n    \"3-0\": \"Website\",\n    \"3-1\": \"The public website of the merchant\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n2. user-contact API :\n\nRequest:\n\tRequired Scope: user-contact:read\n        Header: Authorization: Bearer <your-token>\n        GET /v2/user-contact/\n\nResponse:\n[\n    {\n        \"full_name\": \"Gavin Belson\",\n        \"email\": \"[email protected]\",\n        \"phone\": \"+919876543212\",\n      “username”: “gavin17”,\n      “account_id”: “0f9c251fc4d04765a1ccd246bf81b23b”,\n    }\n]\n\n\n\nUser-Contact parameter Description:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data Points\",\n    \"h-1\": \"Significance\",\n    \"0-0\": \"Full_name\",\n    \"0-1\": \"Full name of the merchant\",\n    \"1-0\": \"Email\",\n    \"1-1\": \"Email of merchant\",\n    \"2-0\": \"Phone\",\n    \"2-1\": \"The contact number of the merchant\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n3. Payments API :\n\nRequest:\n\tRequired Scope: payments:read\n        Header: Authorization: Bearer <your-token>\n        GET /v2/payments\n\nAPI Filters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Query Components\",\n    \"h-1\": \"Significance\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"id\",\n    \"1-0\": \"buyer\",\n    \"2-0\": \"seller\",\n    \"3-0\": \"payout\",\n    \"4-0\": \"product\",\n    \"5-0\": \"min_created_at\",\n    \"6-0\": \"max_created_at\",\n    \"7-0\": \"min_updated_at\",\n    \"8-0\": \"max_updated_at\",\n    \"9-0\": \"order_id\",\n    \"0-1\": \"payment id\",\n    \"0-2\": \"/v2/payments?id=MOJO9618N05A3131214\",\n    \"1-1\": \"username or account id\",\n    \"1-2\": \"v2/payments?buyer=username\",\n    \"2-2\": \"v2/payments?seller=username\",\n    \"3-1\": \"payout id\",\n    \"3-2\": \"v2/payments?payout=MOJO9423001M54251388\",\n    \"4-1\": \"product slug\",\n    \"4-2\": \"v2/payments?product=product_slug\",\n    \"5-1\": \"date-time\",\n    \"5-2\": \"v2/payments?min_updated_at=2019-06-18T08:54:39.1127\",\n    \"6-2\": \"v2/payments?max_created_at=2019-06-18T08:54:39.1127\",\n    \"7-2\": \"v2/payments?min_updated_at=2019-06-18T08:54:39.1127\",\n    \"8-2\": \"v2/payments?max_updated_at=2019-06-18T08:54:39.1127\",\n    \"9-2\": \"v2/payments?order_id=f0a3effe-21c1-450c-8bbb-a0066b09\",\n    \"9-1\": \"order id\",\n    \"2-1\": \"username or account id\",\n    \"6-1\": \"date-time\",\n    \"7-1\": \"date-time\",\n    \"8-1\": \"date-time\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\nResponse:\n{\n    \"count\": 192,\n    \"next\": \"https://test.instamojo.com/v2/payments/?page=2\",\n    \"previous\": null,\n    \"payments\": [\n        {\n            \"id\": \"MOJO9520R12A973123120\",\n            \"title\": \"test payment\",\n\t“payment_type”:”instapay”\n            \"status\": true,\n            \"link\": \"https://test.instamojo.com/v2/links/l0e72e50122c04af7b62382380bfcba66/\",\n            \"product\": null,\n            \"seller\": \"https://test.instamojo.com/v2/users/3f5c511283a34e0c88e5bea4943a2c03/\",\n            \"currency\": \"INR\",\n            \"amount\": \"9494.00\",\n            \"name\": \"buyer\",\n            \"email\": \"[email protected]\",\n            \"phone\": \"+919876543210\",\n            \"payout\": null,\n            \"fees\": \"192.88\",\n            \"total_taxes\": \"34.72\",\n            \"cases\": [],\n            \"instrument_type\": \"CARD\",\n            \"billing_instrument\": \"International Regular Credit Card (Visa/Mastercard)\",\n            \"failure\": null,\n            \"created_at\": \"2019-05-20T09:30:23.808234Z\",\n            \"updated_at\": \"2019-05-24T07:45:04.639332Z\",\n            \"tax_invoice_id\": \"0355221229/000006\",\n            \"resource_uri\": \"https://test.instamojo.com/v2/payments/MOJO121520R05A97991120/\"\n        },\n        ….\n        …. \n        ]\n}\n}\n\nPayment Parameter Description:\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data Points\",\n    \"h-1\": \"Significance\",\n    \"h-2\": \"Values\",\n    \"0-0\": \"id\",\n    \"0-1\": \"Payment Id\",\n    \"1-0\": \"title\",\n    \"1-1\": \"Title of Payment\",\n    \"2-0\": \"payment_type\",\n    \"2-1\": \"Type of Payment\",\n    \"2-2\": \"VAN = payment form virtual_account\\ninstapay = payment from Instapay\\nDashboard_Smart_Link = Smart link payment \\n\\nDashboard_Link = Quick link payment\\nDashboard_Product = Dashboard product payment\\napi_rap = payment from v2 api\\ndashboard_rap = payment from dashboard\\nsdk = payment from sdk\\nmojoPOS = QR code payment\",\n    \"3-0\": \"Status\",\n    \"3-1\": \"Payment Status\",\n    \"3-2\": \"True = Payment is successful\\nFalse = Payment failed\\nNone = Payment is pending\",\n    \"4-0\": \"link\",\n    \"4-1\": \"URL to a payment link\",\n    \"5-0\": \"product\",\n    \"5-1\": \"URL to product\",\n    \"6-0\": \"seller\",\n    \"6-1\": \"URL to seller details\",\n    \"7-0\": \"currency\",\n    \"8-0\": \"amount\",\n    \"9-0\": \"name\",\n    \"10-0\": \"email\",\n    \"11-0\": \"phone\",\n    \"12-0\": \"payout id\",\n    \"13-0\": \"fees\",\n    \"14-0\": \"total_taxes\",\n    \"15-0\": \"cases (disputes)\",\n    \"16-0\": \"instrument_type\",\n    \"17-0\": \"billing_instrument\",\n    \"18-0\": \"failure\",\n    \"19-0\": \"created_at\",\n    \"20-0\": \"updated_at\",\n    \"21-0\": \"tax_invoice_id\",\n    \"22-0\": \"resource_uri\",\n    \"7-1\": \"Type of Currency (INR)\",\n    \"8-1\": \"Payment Amount\",\n    \"9-1\": \"Buyer's name for this payment\",\n    \"10-1\": \"Sender's email for this payment\",\n    \"11-1\": \"Sender's phone for this payment\",\n    \"12-1\": \"Payout of the primary merchant\",\n    \"13-1\": \"Fees charged to the primary merchant for this payment\",\n    \"14-1\": \"Total tax to a primary merchant for this payment\",\n    \"15-1\": \"URL for case\",\n    \"16-1\": \"Instrument type used for payment\",\n    \"16-2\": \"CLAIM = 'CLAIM'\\nSOCIALPAY = 'SOCIALPAY'\\nUSD = 'USD'\\nPROMO = 'PROMO'\\nCARD = 'CARD'\\nNETBANKING = 'NETBANKING'\\nEMI = 'EMI'\\nWALLET = 'WALLET'\\nUPI = 'UPI'\\nBANK_TRANSFER = 'BANK TRANSFER'\\nQR_CODE = 'QR'\",\n    \"17-1\": \"Billing Instrument\",\n    \"17-2\": \"International Regular Credit Card (Visa/Mastercard)\\nDomestic Regular Credit Card (Visa/Mastercard)\\nDomestic Netbanking Category A or B\\nUnknown netbanking choice\\nPromo Payment, etc\",\n    \"18-1\": \"Failure Reason/Message\",\n    \"18-2\": \"AUTHENTICATION_FAILED\\nAUTHORIZATION_FAILED\\nDROPPED, CANCELLED, EXPIRED, etc\",\n    \"19-1\": \"Date of Payment Creation\",\n    \"20-1\": \"Date of payment update\",\n    \"21-1\": \"Merchant Tax Invoice ID\",\n    \"22-1\": \"resource URI for this payment\"\n  },\n  \"cols\": 3,\n  \"rows\": 23\n}\n[/block]\n4. Payouts API :\n\nRequest:\n          Required Scope: payouts:read\n          Header: Authorization: Bearer <your-token>\n\nGET /v2/payouts\n\nAPI Filters:\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Query components\",\n    \"h-1\": \"Significance\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"id\",\n    \"1-0\": \"start_time\",\n    \"2-0\": \"end_time\",\n    \"0-1\": \"payout id\",\n    \"1-1\": \"paid out date/time\",\n    \"2-1\": \"paid out date/time\",\n    \"0-2\": \"/v2/payouts?id=MOJO9423001M54251388\",\n    \"1-2\": \"/v2/payouts?start_time=2019-06-18T04:59:37.227712Z\",\n    \"2-2\": \"/v2/payouts?end_time=2019-06-18T04:59:37.227712Z\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nResponse:\n{\n    \"count\": 17,\n    \"next\": null,\n    \"previous\": null,\n    \"payouts\": [\n        {\n            \"id\": \"MOJO9413001M10071018\",\n            \"recipient\": \"https://test.instamojo.com/v2/users/3f5c51c283a34e0c88e5bea4943a2c03/\",\n            \"status\": true,\n            \"paid_out_at\": \"2019-04-22T12:23:19.239722Z\",\n            \"currency\": \"INR\",\n            \"paid_amount\": \"1570.75\",\n            \"sales_amount\": \"26983.21\",\n            \"fee_amount\": \"1744.92\",\n            \"total_tax_amount\": \"314.24\",\n            \"held_amount\": \"0.00\",\n            \"reversed_amount\": \"3965.00\",\n            \"refunded_amount\": \"0.00\",\n            \"affiliate_commission_amount\": \"0.00\",\n            \"partner_commission_amount\": \"0.00\",\n            \"payout_type\": 0,\n            \"resource_uri\": \"https://test.instamojo.com/v2/payouts/MOJO9413001M10071018/\",\n            \"shipping_fee\": \"23386.42\"\n        },\n        ….\n        …. \n        ]\n}\n}\n\n\n\n\n5. Products API :\n\nRequest:\n\tRequired Scope: products:read\n        Header: Authorization: Bearer <your-token>\n\nGET /v2/products\n\nAPI Filters:\n\n\n\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Query Components\",\n    \"h-1\": \"Significance\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"created_after\",\n    \"1-0\": \"created_before\",\n    \"0-1\": \"created date-time timezone=ufc\",\n    \"1-1\": \"created date-time timezone=ufc\",\n    \"0-2\": \"v2/products?created_after=2019-06-18T04:59:37.227712Z\",\n    \"1-2\": \"v2/products?created_before=2019-06-18T04:59:37.227712Z\",\n    \"2-0\": \"status\",\n    \"2-1\": \"Product status\\nLive = 20\\nArchived = 30\\nPending Moderation = 33\",\n    \"2-2\": \"v2/orders?status=20\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nResponse:\n{\n    \"count\": 10,\n    \"next\": \"https://test.instamojo.com/v2/products/?page=2\",\n    \"previous\": null,\n    \"products\": [\n        {\n            “title\": \"test_product\",\n            \"description\": \"test product description\",\n            \"status\": \"Live\",\n            \"user\": \"https://test.instamojo.com/v2/users/3f5c51c283123e0c88e5bea4943a2c03/\",\n            \"slug\": \"test_product\",\n            \"shorturl\": \"https://imojo.in/test_product\",\n            \"currency\": \"INR\",\n            \"base_price\": \"25.00\",\n            \"min_price\": \"25.00\",\n            \"max_price\": \"25.00\",\n            \"pay_what_you_want\": false,\n            \"limit_quantity\": null,\n            \"purchased_quantity\": 0,\n            \"discount_public\": false,\n\t    “product_type”:”physical”,\n            \"requires_shipping\": true,\n            \"ships_within_days\": 25,\n            \"start_date\": null,\n            \"end_date\": null,\n            \"venue\": null,\n            \"timezone\": null,\n            \"redirect_url\": null,\n            \"redirect_time\": 2000,\n            \"webhook_url\": null,\n            \"custom_note_success\": \"\",\n            \"is_signing_mandatory\": false,\n            \"created_at\": \"2019-05-27T09:14:42.078152Z\",\n            \"resource_uri\": \"https://test.instamojo.com/v2/products/test_product/\"\n        },\n        ….\n        …. \n        ]\n}\n}\n\n\nTo get product images:\n             Required Scope: products:read\n             Header: Authorization: Bearer <your-token>\nGET /v2/products/<product_slug>/covers/\n\n6. Orders API:\n\nRequest:\n\tRequired Scope: orders:read\n        Header: Authorization: Bearer <your-token>\nGET /v2/orders\n\nAPI Filters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Query components\",\n    \"h-1\": \"Significance\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"created_after\",\n    \"1-0\": \"created_before\",\n    \"2-0\": \"pending\",\n    \"0-1\": \"created date-time timezone=utc\",\n    \"1-1\": \"created date-time timezone=utc\",\n    \"0-2\": \"v2/orders?created_after=2019-06-18T04:59:37.227712Z\",\n    \"1-2\": \"v2/orders?created_before=2019-06-18T04:59:37.227712Z\",\n    \"2-1\": \"pending = True (or 1)\\ni.e. exclude all the orders with successful payment\\n\\npending = False (or 0)\\ni.e. only include orders with successful payment\",\n    \"2-2\": \"v2/orders?pending=True\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nResponse:\n\n{\n    \"count\": 30,\n    \"num_pages\": 1,\n    \"next\": null,\n    \"previous\": null,\n    \"orders\": [\n        {\n            \"id\": \"4d0d5054-5f19-4ce8-b0b7-ee7a01442297\",\n            \"title\": \"MacBook pro\",\n            \"currency\": \"INR\",\n            \"created_at\": \"2019-07-02T11:16:43.313684Z\",\n            \"buyer_email\": \"[email protected]\",\n            \"buyer_name\": \"Litesh Patil\",\n            \"buyer_phone\": \"9790707007\",\n            \"buyer_address\": \"17, 7th Cross road, Bengaluru\",\n            \"buyer_city\": \"Bengaluru\",\n            \"buyer_state\": \"Karnataka\",\n            \"buyer_zip\": \"560034\",\n            \"buyer_country\": \"India\",\n            \"amount\": \"70000.00\",\n            \"order_status\": \"Fully Paid\",\n            \"payments_uri\": \"http://localhost:5000/v2/payments/?order_id=4d0d5054-5f19-4ce8-b0b7- \n                                       ee7a01442297\",\n            \"payments\": [\n                {\n                    \"payment_id\": \"MOJO9702J00A09128126\",\n                    \"amount\": \"70000.00\",\n                    \"instrument_type\": \"CARD\",\n                    \"status\": \"Success\",\n                    \"resource_uri\": \"http://localhost:5000/v2/payments/MOJO9702J00A09128126/\"\n                }\n            ],\n            \"items\": [\n                {\n                    \"unit_price\": \"50000.00\",\n                    \"quantity\": 1,\n                    \"amount\": \"70000.00\",\n                    \"is_shipping_required\": true,\n                    \"seller\": \"http://localhost:5000/v2/users/0f9c251fc4d04765a1ccd246bf81b34b/\",\n                    \"shipping_charge_logic\": null,\n                    \"shipping_charges\": null,\n                    \"product\": \"http://localhost:5000/v2/products/macbook-pro/\",\n                    \"order\": \"http://localhost:5000/v2/orders/4d0d5054-5f19-4ce8-b0b7-ee7a01442297/\",\n                    \"discount\": null,\n                    \"variants\": [\n                        \"http://localhost:5000/v2/products/macbook-pro/variant_categories/1/variants/1/\"\n                    ]\n                }\n            ]\n        },","html":"","htmlmode":false,"fullscreen":false,"hidden":false,"_id":"5d4a72b586b8040030b6d646","project":"56a1c9c13845200d0066d6fe","user":{"name":"Abhineet Sinha","username":"","_id":"5ce26a9d4c3d820056874747"},"createdAt":"2019-08-07T06:41:57.432Z","__v":0,"metadata":{"title":"","description":"","image":[]}}

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) 5. Video (Youtube video link - How to use the App) 6. Data Access Permissions requirement from the merchants 7. Price (In case the App is paid) 8. App URL (App to be hosted by the developer and a URL needs to be provided) 9. 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) [block:image] { "images": [ { "image": [ "https://files.readme.io/84fe566-Screenshot_2019-08-07_13.06.33.png", "Screenshot 2019-08-07 13.06.33.png", 862, 482, "#e8e9e9" ] } ] } [/block] 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/62255fe-Screenshot_2019-08-07_13.09.20.png", "Screenshot 2019-08-07 13.09.20.png", 900, 460, "#c8d6da" ] } ] } [/block] 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: [block:parameters] { "data": { "h-0": "Data Points", "h-1": "Significance", "0-0": "full_name", "0-1": "Full name of the merchant", "1-0": "signup_date", "1-1": "The date of joining of the merchant on Instamojo", "2-0": "City", "2-1": "Registered city of the merchant", "3-0": "Website", "3-1": "The public website of the merchant" }, "cols": 2, "rows": 4 } [/block] 2. user-contact API : Request: Required Scope: user-contact:read Header: Authorization: Bearer <your-token> GET /v2/user-contact/ Response: [ { "full_name": "Gavin Belson", "email": "[email protected]", "phone": "+919876543212", “username”: “gavin17”, “account_id”: “0f9c251fc4d04765a1ccd246bf81b23b”, } ] User-Contact parameter Description: [block:parameters] { "data": { "h-0": "Data Points", "h-1": "Significance", "0-0": "Full_name", "0-1": "Full name of the merchant", "1-0": "Email", "1-1": "Email of merchant", "2-0": "Phone", "2-1": "The contact number of the merchant" }, "cols": 2, "rows": 3 } [/block] 3. Payments API : Request: Required Scope: payments:read Header: Authorization: Bearer <your-token> GET /v2/payments API Filters: [block:parameters] { "data": { "h-0": "Query Components", "h-1": "Significance", "h-2": "Example", "0-0": "id", "1-0": "buyer", "2-0": "seller", "3-0": "payout", "4-0": "product", "5-0": "min_created_at", "6-0": "max_created_at", "7-0": "min_updated_at", "8-0": "max_updated_at", "9-0": "order_id", "0-1": "payment id", "0-2": "/v2/payments?id=MOJO9618N05A3131214", "1-1": "username or account id", "1-2": "v2/payments?buyer=username", "2-2": "v2/payments?seller=username", "3-1": "payout id", "3-2": "v2/payments?payout=MOJO9423001M54251388", "4-1": "product slug", "4-2": "v2/payments?product=product_slug", "5-1": "date-time", "5-2": "v2/payments?min_updated_at=2019-06-18T08:54:39.1127", "6-2": "v2/payments?max_created_at=2019-06-18T08:54:39.1127", "7-2": "v2/payments?min_updated_at=2019-06-18T08:54:39.1127", "8-2": "v2/payments?max_updated_at=2019-06-18T08:54:39.1127", "9-2": "v2/payments?order_id=f0a3effe-21c1-450c-8bbb-a0066b09", "9-1": "order id", "2-1": "username or account id", "6-1": "date-time", "7-1": "date-time", "8-1": "date-time" }, "cols": 3, "rows": 10 } [/block] 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: [block:parameters] { "data": { "h-0": "Data Points", "h-1": "Significance", "h-2": "Values", "0-0": "id", "0-1": "Payment Id", "1-0": "title", "1-1": "Title of Payment", "2-0": "payment_type", "2-1": "Type of Payment", "2-2": "VAN = payment form virtual_account\ninstapay = payment from Instapay\nDashboard_Smart_Link = Smart link payment \n\nDashboard_Link = Quick link payment\nDashboard_Product = Dashboard product payment\napi_rap = payment from v2 api\ndashboard_rap = payment from dashboard\nsdk = payment from sdk\nmojoPOS = QR code payment", "3-0": "Status", "3-1": "Payment Status", "3-2": "True = Payment is successful\nFalse = Payment failed\nNone = Payment is pending", "4-0": "link", "4-1": "URL to a payment link", "5-0": "product", "5-1": "URL to product", "6-0": "seller", "6-1": "URL to seller details", "7-0": "currency", "8-0": "amount", "9-0": "name", "10-0": "email", "11-0": "phone", "12-0": "payout id", "13-0": "fees", "14-0": "total_taxes", "15-0": "cases (disputes)", "16-0": "instrument_type", "17-0": "billing_instrument", "18-0": "failure", "19-0": "created_at", "20-0": "updated_at", "21-0": "tax_invoice_id", "22-0": "resource_uri", "7-1": "Type of Currency (INR)", "8-1": "Payment Amount", "9-1": "Buyer's name for this payment", "10-1": "Sender's email for this payment", "11-1": "Sender's phone for this payment", "12-1": "Payout of the primary merchant", "13-1": "Fees charged to the primary merchant for this payment", "14-1": "Total tax to a primary merchant for this payment", "15-1": "URL for case", "16-1": "Instrument type used for payment", "16-2": "CLAIM = 'CLAIM'\nSOCIALPAY = 'SOCIALPAY'\nUSD = 'USD'\nPROMO = 'PROMO'\nCARD = 'CARD'\nNETBANKING = 'NETBANKING'\nEMI = 'EMI'\nWALLET = 'WALLET'\nUPI = 'UPI'\nBANK_TRANSFER = 'BANK TRANSFER'\nQR_CODE = 'QR'", "17-1": "Billing Instrument", "17-2": "International Regular Credit Card (Visa/Mastercard)\nDomestic Regular Credit Card (Visa/Mastercard)\nDomestic Netbanking Category A or B\nUnknown netbanking choice\nPromo Payment, etc", "18-1": "Failure Reason/Message", "18-2": "AUTHENTICATION_FAILED\nAUTHORIZATION_FAILED\nDROPPED, CANCELLED, EXPIRED, etc", "19-1": "Date of Payment Creation", "20-1": "Date of payment update", "21-1": "Merchant Tax Invoice ID", "22-1": "resource URI for this payment" }, "cols": 3, "rows": 23 } [/block] 4. Payouts API : Request: Required Scope: payouts:read Header: Authorization: Bearer <your-token> GET /v2/payouts API Filters: [block:parameters] { "data": { "h-0": "Query components", "h-1": "Significance", "h-2": "Example", "0-0": "id", "1-0": "start_time", "2-0": "end_time", "0-1": "payout id", "1-1": "paid out date/time", "2-1": "paid out date/time", "0-2": "/v2/payouts?id=MOJO9423001M54251388", "1-2": "/v2/payouts?start_time=2019-06-18T04:59:37.227712Z", "2-2": "/v2/payouts?end_time=2019-06-18T04:59:37.227712Z" }, "cols": 3, "rows": 3 } [/block] 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 <your-token> GET /v2/products API Filters: [block:parameters] { "data": { "h-0": "Query Components", "h-1": "Significance", "h-2": "Example", "0-0": "created_after", "1-0": "created_before", "0-1": "created date-time timezone=ufc", "1-1": "created date-time timezone=ufc", "0-2": "v2/products?created_after=2019-06-18T04:59:37.227712Z", "1-2": "v2/products?created_before=2019-06-18T04:59:37.227712Z", "2-0": "status", "2-1": "Product status\nLive = 20\nArchived = 30\nPending Moderation = 33", "2-2": "v2/orders?status=20" }, "cols": 3, "rows": 3 } [/block] 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 <your-token> GET /v2/products/<product_slug>/covers/ 6. Orders API: Request: Required Scope: orders:read Header: Authorization: Bearer <your-token> GET /v2/orders API Filters: [block:parameters] { "data": { "h-0": "Query components", "h-1": "Significance", "h-2": "Example", "0-0": "created_after", "1-0": "created_before", "2-0": "pending", "0-1": "created date-time timezone=utc", "1-1": "created date-time timezone=utc", "0-2": "v2/orders?created_after=2019-06-18T04:59:37.227712Z", "1-2": "v2/orders?created_before=2019-06-18T04:59:37.227712Z", "2-1": "pending = True (or 1)\ni.e. exclude all the orders with successful payment\n\npending = False (or 0)\ni.e. only include orders with successful payment", "2-2": "v2/orders?pending=True" }, "cols": 3, "rows": 3 } [/block] 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/" ] } ] },