# Authenticate Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/authentication/authentication projects/connect/openapi.json POST /authenticate API to authenticate the API User # Authorize Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/authentication/authorization projects/connect/openapi.json POST /authorize API to authorize the API User # Authorize Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/oauth/authorize projects/connect/openapi.json POST /oauth/authorize API to exchange request token for resource owner's access token # Order Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/advisory/order projects/connect/openapi.json GET /advisory/contacts/{contact_id}/orders/{order_id} API to get the details of the order # Orders Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/advisory/orders projects/connect/openapi.json GET /advisory/contacts/{contact_id}/orders API to get the details of the orders # User Details Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/entitlements/user-details projects/connect/openapi.json GET /entitlements/user API to get the details of the user # ITR Details Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/income-tax/file/itr-details projects/connect/openapi.json GET /income-tax/tax-payer/itr API to get the details of the ITR # Computation of Tax Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/income-tax/file/tax-computation projects/connect/openapi.json GET /income-tax/tax-payer/itr/computation-of-tax API to get the computation of tax # Tax Payer Source: https://company-quicko-8c502003.mintlify.app/projects/connect/api-reference/open-apis/income-tax/tax-payer projects/connect/openapi.json GET /income-tax/tax-payer API to get the details of the tax payer # Event Directory Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/events/directory Catalog of event types emitted by Quicko Connect Here's a catalog of event types we presently emit. We may introduce others, so in your code upkeep, don't consider this list exhaustive. ## ITR Lifecycle Events | Event | Client | Postback | | - | - | - | | `com.quicko.it.itr.in_progress` | ✅ | ✅ | | `com.quicko.it.itr.e_filed` | ✅ | ✅ | | `com.quicko.it.itr.e_verified` | ✅ | ✅ | ### Payload The payload for each event will be an object that describes that state of their Income Tax Return. ```json theme={null} { "filed_under_section": "on_or_before_the_due_date_us_139_1", "filing_type": "original", "id": "8555b943-c3a9-4c95-9663-625b347b00da", "form": "itr_1", "status": "in_progress", "assessment_year": "AY 2023-24", "due_date": 1722450599000, "opt_audit": null, "audit_under_section": null, "filed_on": null, "e_verified_on": null, "acknowledgement_number": null } ``` | Param | Type | Description | | - | - | - | | @entity | string | Describes the type of the JSON object. | | filed\_under\_section | string | Indicates the section under which the user is trying to file their tax return. Values: `on_or_before_the_due_date_us_139_1` \| `revised_return_us_139_5` \| `in_response_to_a_notice_us_139_9_defactive_return` \| `in_response_to_notice_us_142_1` | | filing\_type | string (Enum) | Type of the income tax return. Values: `original` \| `revised` | | id | string | UUID for this specific ITR | | form | string (Enum) | Type of the ITR form that is derived based on user input. Values: `itr_1` \| `itr_2` \| `itr_3` \| `itr_4` | | status | string | State of the ITR on Quicko. Values: `not_started` \| `in_progress` \| `e_filed` \| `e_verified` \| `revised` \| `cancelled` \| `prepared` | | assessment\_year | string | Assessment year that the tax return is being prepared for | | due\_date | number | Due date for filing ITR | | filed\_on | number | Date at which the ITR was filed | | acknowledgement\_number | string | Populated once the tax return is filed, the field indicates the acknowledgement number of the ITR | | opt\_audit | boolean | Indicates if the user has opted for tax audit | | audit\_under\_section | string | Section under which audit is opted | | e\_verified\_on | number | Date at which the ITR was e-verified | ## User Events | Event | Client | Postback | | - | - | - | | `com.quicko.user.authenticated` | ✅ | 🚫 | | `com.quicko.user.deleted` | ✅ | ✅ | **Payload Example:** ```json theme={null} { "id": "0D6B076A2D0B192CE063020015ACC47F", "email": "[email protected]", "created_at": 1682797023000, "status": "active", "request_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpbnRlbnQiOiJSRVFVRVNUX1RPS0VOIiwiYXBpX2tleSI6ImtleV90ZXN0X3RFc1RERU1PdE9rM25CVHpTNFI1b09VaHBjb3UzWmdHIiwiaWF0IjoxNzA5Mjc3MjcyLCJleHAiOjE3MDkyNzc4NzIsImF1ZCI6Im9hdXRoLnF1aWNrby5jb20iLCJpc3MiOiJvYXV0aC5xdWlja28uY29tIiwic3ViIjoiMEQ2QjA3NkEyRDBCMTkyQ0UwNjMwMjAwMTVBQ0M0N0YifQ.V5V_C1aBE5Jqr99rzPRNqwoAcDT0qUQky1iHYNBqSQULykXhO19hA9iV893hJzAR78D-P8bR3cASVOMuLFSSAw" } ``` | Param | Type | Description | | - | - | - | | status | string (Enum) | Indicates the status of the user's account. Values: `active` \| `inactive` \| `pending` | | id | string | Hex UUID for the user | | request\_token | string | Resource Owner's request token that need to be exchanged for an access token using the /oauth/authorize endpoint. Relevant only for `com.quicko.user.authenticated` event | | created\_at | number | Timestamp of when user signed up. | | email | string | Email Id associated with the account | ## Advisory Events ### User Events | Event | Client | Postback | | - | - | - | | `com.quicko.advisory.contact.authenticated` | ✅ | ✅ | **Payload Example:** ```json theme={null} { "id": "3a0b279d-1ea5-48cd-926c-4a05d8348c05", "created_at": 1682797023000 } ``` | Param | Type | Description | | - | - | - | | id | string | Hex UUID for the user | | created\_at | number | Timestamp of when was created. | ### Order Lifecycle Events | Event | Client | Postback | | - | - | - | | `com.quicko.advisory.order.confirmed` | ✅ | ✅ | | `com.quicko.advisory.order.completed` | 🚫 | ✅ | | `com.quicko.advisory.order.cancelled` | ✅ | ✅ | **Payload Example:** ```json theme={null} { "@entity": "com.quicko.advisory.order", "id": "0225636CE4", "status": "confirmed", "created_at": 1717480715227, "order_time": 1717480715227, "updated_at": 1717480729031, "total_price": 5308.82, "discount": 0, "sub_total": 4499, "gst_amount": 809.82, "price_including_gst": false } ``` | Param | Type | Description | | - | - | - | | id | string | A unique identifier for the order. | | created\_at | long | Timestamp indicating when the order was created (in milliseconds since epoch). | | updated\_at | long | Timestamp indicating when the order was last updated (in milliseconds since epoch). | | @entity | string | The entity type, indicating this is an order. | | status | string (Enum) | The current status of the order. Values: `CONFIRMED` \| `COMPLETED` \| `CANCELLED` | | order\_time | long | Timestamp indicating the time of the order (in milliseconds since epoch). | | total\_price | float | The total price of the order including GST. | | sub\_total | float | The price of the order excluding GST. | | gst\_amount | float | The amount of GST applied to the order. | | price\_including\_gst | boolean | A boolean flag indicating whether the price includes GST. | This list is not exhaustive. We may introduce additional event types in the future. Keep your code flexible to handle new events. # The Event Object Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/events/index Understanding Quicko Connect events and how to handle them Events are pivotal markers that signal significant occurrences linked to user activities. Using the CloudEvents specification, Quicko standardizes how these events are presented, ensuring consistency and interoperability. An example event is when a taxpayer e-files their tax return, generating a `com.quicko.it.itr.e_filed` event. These events don't merely signify the occurrence but also capture the exact state of the associated API resource when the event was created. For instance, the `com.quicko.it.itr.e_filed` event contains details like the user's acknowledgment number, refund amount, and status. Events are divided into two main categories: **Postback Events** and **Client Events**. These events can be consumed to enrich your system's understanding of the user journey. ## The Event Object Events are represented using the CloudEvents format: ```json theme={null} { "specversion" : "1.0", "type": "com.quicko.it.itr.e_filed", "source": "/tax-payers/9c0d1fef-8dfb-4aa8-ad8a-08cf38ce3b6a/file/itrs/ca96c1a5-9348-4c0b-951f-5cdae4549461/e-file", "id": "d2dfe831-2b5c-445c-b952-8385a514bbb3", "time": "2023-10-31T12:00:00Z", "datacontenttype": "application/json", "subject": "9c0d1fef-8dfb-4aa8-ad8a-08cf38ce3b6a", "data": { // Additional event details go here } } ``` ### Parameters | Param | Type | Description | | - | - | - | | type | string | Describes the type of the CloudEvent. | | source | URI | URI representing the source context of the event. | | id | string | A unique identifier for the event. | | time | string | ISO8601 timestamp indicating when the event was triggered. | | specversion | string | The version of the CloudEvents specification. | | datacontenttype | string | The content type of the data. | | subject | string | Unique ID of the user for whom the event triggered. | | data | object | Data associated with the event. | ## 1. Postback Events You can configure these events are relayed directly to a specified endpoint on your server. Much like a messenger delivering a letter, when an event occurs, the Quicko communicates this event to your server. It ensures real-time updates and lets you process and react to the data instantaneously. Postback events are useful because the user can close the client app before the SDK sends out the event. In such cases, you can always rely on postbacks to notify your systems. ## 2. Client Events On the flip side, Client Events are geared towards the handling events within your application. These events are designed to be processed directly within the client, offering an interactive response to the user. Client events are great for updating the state of your application without needing to make an API request to Quicko's servers. ### Processing Handling SDK Client Events differs from their server counterpart. These events require client-side logic to interpret and respond. They can be utilized to update the user interface, prompt user actions, or offer feedback. The SDK emits several events during its lifecycle. Developers can set listeners for these events to execute custom logic or to capture specific feedback. #### Setting up Event Listener Setting up an event listener involves monitoring and responding to specific events or changes in a system or application. ```java theme={null} QuickoSDK.INSTANCE.setEventListener(new EventListener() { @Override public void onEvent(@NonNull Event event) { super.onEvent(event); // your implementation } }); ``` ```kotlin theme={null} QuickoSDK.setEventListener(object : EventListener() { override fun onEvent(event: Event) { super.onEvent(event) // your implementation } }) ``` ```swift theme={null} QuickoSDK.instance.setEventListener(eventListener: MyEventListener()) class MyEventListener: EventListener { override func onEvent(event: Event) { // your implementation } } ``` Here's a breakdown of the process: `setEventListener(...)`: This is a method call that tells the SDK to prepare to listen for specific events. `EventListener() { ... }`: This creates a new instance of an `QuickoSDK.EventListener` class. `onEvent(EventDetails details) { ... }`: Provide a custom implementation for this method but overriding `EventListener.onEvent` method. When an event occurs, you'll get a native `EventDetails` model (Java, Swift). ## Conclusion Events fall under both categories, but how you process them vastly differs based on their nature and your use case. Ensure that you're equipped to handle both types to offer a seamless experience for both your backend processes and your end users. Always keep an eye on the events for the most accurate picture of your user's activity. # Authentication Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/getting-started/authentication Quicko Connect uses a two-tiered authentication system to secure API interactions Quicko Connect uses a two-tiered authentication system to secure API interactions and ensure that only authorised users can access sensitive data: 1. **API User Access Token**: Required to interact with OAuth APIs. This token authenticates your application as a trusted client. 2. **Resource Owner Access Token**: Used to authenticate requests to Open APIs. This token represents the user's consent and is obtained through the OAuth flow. ## Acquiring API User Access Token To use Quicko's OAuth APIs, you need an API User Access Token: Call the `/authenticate` endpoint with your API credentials (key and secret). Use credentials starting with `key_test_...` and `secret_test_...`. Use credentials starting with `key_live_...` and `secret_live_...` for both key and secret. ## Best Practices for Security Store your API keys and secrets securely and never expose them in public repositories or client-side code. Ensure all API requests are made over HTTPS to protect data in transit. Implement error handling for authentication failures and other API errors. You can read about the OAuth workflow, which details the process to acquire this token. # Introduction Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/getting-started/index Embed complete tax workflows into your app with Quicko Connect’s modular APIs and SDKs. Quicko Connect offers a comprehensive tax solution tailored for FinTech platforms aiming to enhance the tax journey for their users. We provide a seamless integration experience across your platforms to help your users save, pay, file & track taxes. It encapsulates a range of features that cater to diverse platform needs while ensuring user privacy and data security. Follow our step-by-step integration guide to embed Quicko Connect into your application. ## Key Features Quicko Connect is versatile and covers both web and mobile use cases. For mobile platforms (Android & iOS), Quicko Connect offers a plug-and-play SDK that integrates effortlessly. It uses Material 3 design to blend seamlessly into the host app's theme, ensuring a consistent user experience. For web platforms, Quicko Connect provides a redirect-based journey, guiding users to the our Income Tax Web App. The user journey with Quicko Connect is event-driven, and these events are shared transparently with the channel partner. We prioritise user privacy and consent. All actions and data accesses are done with explicit user consent. This documentation will also guide you on leveraging the open APIs that allow channel partners to query user data from their servers with proper user consent. ## Understanding Channel Partners A Channel Partner refers to external platforms or businesses that have embedded the Quicko Connect SDK into their applications. By doing so, these platforms can harness the power and features of Quicko Connect to solve tax-related issues for their users. Using Quicko Connect, you can add taxes to your offerings and enhance the experience for your users with minimal effort. The SDK is designed as a low-code solution. Channel Partners can effortlessly provide a "drop-in" tax solution to their users without heavy development work. With user consent, Channel Partners can glean insights into user data by querying our open APIs. Channel Partners can generate revenue through Clique, Quicko's affiliate platform, whenever a user engages in a transaction on the SDK. ## Getting Started Depending on your platform, choose between the mobile SDK or the web solution. Follow our step-by-step integration guide to embed Quicko Connect into your application. Understand the event-driven user journey to know what to expect and how to handle different scenarios in your application. Familiarize yourself with the open APIs to fetch user data from the servers. *** ## Conclusion With Quicko Connect, you're not just integrating a tax solution. You're enhancing your user's experience, ensuring their privacy, and creating new revenue opportunities for your platform. Dive into the subsequent sections of this documentation to kickstart your integration and make the most out of Quicko Connect. # Quickstart Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/getting-started/quickstart Set up a Quicko account, register your app, and provision credentials to connect your app to your users' Quicko accounts. This quickstart walks through onboarding to **Quicko Connect** — the OAuth-based workflow that lets you connect your app to your users' Quicko accounts once they grant consent. **Not what you're looking for?** If your app does not need consent-based access and only needs to redirect users into Quicko, use a redirection workflow instead: * **Mobile** — embed Quicko Tools in a WebView. See [Mobile Integration](/projects/tools/integration/mobile/index). * **Web** — redirect users to the Income Tax Web App with your `affiliate_id`. See [Refer](/projects/connect/guides/integrations/web-integration/refer). ## Before you start You will need: * A Quicko account owned by your organisation (not a personal account). * Access to your application's hosted Redirect URL, Policy URL, and Logo URL. * An HTTPS endpoint on your servers if you plan to receive webhook events. ## 1. Create a Quicko account Sign up at [quicko.com](https://quicko.com) using a **shared organisational email** rather than an individual employee's address. Examples: * `team-tax@yourcompany.com` * `tax-filing@yourcompany.com` * `quicko-integration@yourcompany.com` Using a shared mailbox keeps ownership with the team — credentials, app status, and webhook alerts continue to reach you when team members move on. ## 2. Register your app Sign in to [myaccount.quicko.com](https://myaccount.quicko.com) and navigate to **Settings → Integrations & Access → Connect**, then click **Create App**. Fill in the following details: | Field | Description | | - | - | | **App Name** | The display name your users will see on the consent screen. | | **App Description** | A short summary of what your app does and why it needs access to Quicko data. | | **Business Name** | The legal name of the business that owns the app. | | **Whitelisted Domain** | The domain that hosts your application (for example, `app.yourcompany.com`). Quicko accepts a `redirect_uri` during the OAuth flow only if its host matches this value, which prevents authorization codes from being delivered to an unintended destination. | | **Policy URL** | Public URL of your privacy policy. Shown to users during consent. | | **Logo URL** | Direct URL to your app's logo (`.png`, `.svg`, or `.jpg`). Displayed on the consent screen. | Newly created apps are in **Draft** status and cannot be used to make live OAuth requests. After submitting the form, email **[developer@quicko.com](mailto:developer@quicko.com)** with the subject **Quicko Connect Integration** and include your registered email and use case in the body so the team can review and approve your app. Compose in Gmail web. Compose in Outlook web. Open in your system's default mail client. ## 3. Generate API credentials Once your app is approved, navigate to **Settings → Integrations & Access → API Access** to generate your credentials. You will receive an **API Key** and an **API Secret**: * Credentials are prefixed with `key_live_…` / `secret_live_…`. * These are used to call the [Authenticate API](/projects/connect/api-reference/authentication/authentication) and obtain your API User Access Token. The **API Secret is shown — and downloadable — only once**, immediately after it is generated. Save it to your secret manager right away. If you lose it, you must rotate the credential and update every system that uses it. Learn how to exchange these credentials for an API User Access Token. ## 4. Configure webhooks Webhooks let Quicko push event notifications to your servers as users progress through their tax journey. Go to **Settings → Integrations & Access → Webhooks** and click **Create Webhook**. | Field | Description | | - | - | | **Endpoint URL** | HTTPS URL on your server that will receive event notifications via `POST`. | | **Secret** *(optional)* | A shared secret used to sign every webhook delivery so you can verify it came from Quicko. See [Verifying webhook signatures](#verifying-webhook-signatures) below. | | **Events** | Select which events this endpoint should receive. You can configure multiple endpoints to fan-out different events to different services. | ### Available events | Event | Description | | - | - | | **ITR In-Progress** | Fired when a user starts their Income Tax Return. | | **ITR E-Filed** | Fired when a user e-files their Income Tax Return. | | **ITR E-Verified** | Fired when a user e-verifies their Income Tax Return. | ### Verifying webhook signatures Providing a **Secret** when creating the webhook is optional but strongly recommended. When a secret is set, Quicko signs every delivery so your server can confirm the request is authentic and was not tampered with in transit. **How the signature is produced** 1. Quicko serialises the event payload as a JSON string (the same bytes sent in the request body). 2. It computes an `HMAC-SHA256` of that string using your webhook secret as the key. 3. The hex-encoded digest is sent in the `x-webhook-signature` request header. If no secret is configured on the webhook, the `x-webhook-signature` header is omitted and no signature is computed. **How to verify on your server** Recompute the HMAC over the raw request body using the same secret and compare it against the header value using a constant-time comparison. ```javascript theme={null} import crypto from "crypto"; function verifyQuickoSignature(rawBody, headerSignature, secret) { const expected = crypto .createHmac("sha256", secret) .update(rawBody) .digest("hex"); const a = Buffer.from(expected, "hex"); const b = Buffer.from(headerSignature ?? "", "hex"); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` ```python theme={null} import hashlib import hmac def verify_quicko_signature(raw_body: bytes, header_signature: str, secret: str) -> bool: expected = hmac.new( secret.encode("utf-8"), raw_body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, header_signature or "") ``` ```go theme={null} import ( "crypto/hmac" "crypto/sha256" "encoding/hex" ) func VerifyQuickoSignature(rawBody []byte, headerSignature, secret string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write(rawBody) expected := hex.EncodeToString(mac.Sum(nil)) a, _ := hex.DecodeString(expected) b, _ := hex.DecodeString(headerSignature) return hmac.Equal(a, b) } ``` Verify against the **raw request body** — not a re-serialised version of the parsed JSON. Whitespace and key ordering changes will break the signature check. Treat the webhook secret with the same care as your API Secret. Rotate it immediately if you suspect it has been exposed, and update every receiver before discarding the old value. ## Next steps Exchange your API credentials for an access token to call Quicko APIs. Walk through the consent flow and obtain a Resource Owner access token. Explore the data and actions available through the consent-based APIs. See the full directory of events you can subscribe to via webhooks. # Integrations Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/index Integrate Quicko Connect into your platform with mobile SDK, web, or API integrations Quicko Connect offers flexible integration options to suit your platform's needs. Whether you're building a mobile app, web application, or need direct API access, we provide seamless integration paths that prioritize user privacy and developer experience. Not sure which integration method is right for you? Check our getting started guide to help you decide. ## Integration Options Integrate Quicko Connect into your native iOS or Android applications using our plug-and-play SDK. The SDK uses Material 3 design to blend seamlessly into your app's theme, ensuring a consistent user experience. Native iOS SDK that integrates effortlessly with Swift and Objective-C applications. Supports iOS 13.0 and above. Native Android SDK built with Kotlin and Java support. Compatible with Android API level 21 and above. **Key Features:** * Plug-and-play SDK with minimal setup * Material 3 design system integration * Customizable theme matching * Event-driven callback system * User consent management built-in Integrate Quicko Connect into your web platform using our redirect-based journey. Guide users seamlessly to the Quicko Income Tax Web App while maintaining full control over the user experience. **Integration Flow:** * User initiates tax filing from your platform * Redirect to Quicko Connect web interface * User completes tax filing journey * Return to your platform with status updates **Benefits:** * Quick implementation with minimal code * No SDK dependencies required * Full feature access through web interface * Seamless user experience with redirects Implement OAuth 2.0 flow to authenticate users and obtain access tokens for API interactions. This integration method provides the most control and flexibility for custom implementations. **OAuth Flow Steps:** 1. Obtain API User Access Token via `/authenticate` endpoint 2. Initialize OAuth authorization flow 3. User grants consent through authorization endpoint 4. Receive Resource Owner Access Token 5. Use token for Open API requests **Use Cases:** * Custom UI implementations * Server-side integrations * Advanced workflow customization * Multi-platform integrations Integrate directly with Quicko Connect APIs for complete control over user experience and data flow. Perfect for advanced use cases requiring custom implementations. **Available APIs:** * User management endpoints * Tax filing endpoints * Tax computation APIs * Advisory services APIs * Event webhooks **Requirements:** * Valid API credentials (key and secret) * OAuth flow implementation * User consent management * Secure token storage ## Integration Architecture Quicko Connect uses an event-driven architecture that keeps your platform informed about user actions and journey progress. All events are shared transparently with channel partners. **Event Types:** * User journey milestones * Tax filing status updates * Payment transactions * Document uploads * User consent changes **Implementation:** * Register event listeners in your app * Handle events asynchronously * Update UI based on event data * Track user journey progress Privacy and user consent are fundamental to Quicko Connect integrations. All data access and actions require explicit user consent, ensuring compliance with privacy regulations. **Consent Management:** * Explicit consent prompts * Granular permission controls * Consent revocation support * Transparent data usage policies **Best Practices:** * Request consent at appropriate times * Explain data usage clearly * Provide easy opt-out mechanisms * Maintain consent records Proper token management is crucial for secure integrations. Understand how to acquire, store, and refresh access tokens throughout your application lifecycle. **Token Types:** * **API User Access Token**: Authenticates your application * **Resource Owner Access Token**: Represents user consent **Security Practices:** * Store tokens securely (never in client-side code) * Implement token refresh mechanisms * Use HTTPS for all API requests * Handle token expiration gracefully ## Quick Start Determine whether you need mobile SDK (iOS/Android), web integration, or direct API access based on your platform and requirements. Obtain your API credentials (key and secret) from the Quicko Connect dashboard. Use test credentials for development and live credentials for production. Set up authentication using the OAuth flow or API User Access Token, depending on your integration type. Implement event listeners to track user journey progress and update your application state accordingly. Test your integration thoroughly in the test environment before deploying to production. ## Integration Best Practices Never expose API keys or secrets in client-side code. Store credentials securely on your backend and use them for server-side API calls. Implement comprehensive error handling for authentication failures, network errors, and API rate limits. Provide clear error messages to users. Design seamless user flows that guide users through the tax filing process. Provide clear progress indicators and status updates. Test thoroughly in the test environment before production deployment. Use test credentials and verify all integration flows work correctly. *** ## Next Steps Ready to start integrating? Choose your integration method and follow the detailed guides: Learn how to integrate Quicko Connect into your iOS or Android application. Get started with web integration using redirect-based flows. Explore the complete API reference for direct API integrations. # Mobile SDK Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/index Integrate Quicko Connect Mobile SDK into your iOS or Android applications The Mobile SDK is an out-of-box solution tailored specifically for platforms looking to solve taxes for their users. The UI is customizable to the extent that users experience a fluid transition, without abrupt design breaks, providing them with a truly cohesive and unified user interface. It also comes equipped with robust connectors to our API, which, in turn, unlocks a plethora of tax-related functionalities. ## Income Tax SDK Integration Quicko Mobile SDK Workflow # Installing the SDK Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/installing Install the Quicko Income Tax SDK for Android and iOS platforms ## Android To integrate the `com.quicko.income-tax-sdk` library in your Android project, follow these steps: Ensure you have Android Studio installed and your project is set up with a minimum SDK version of 26 or higher. Add the following to your project-level `settings.gradle` file inside the `allprojects` block: ```groovy theme={null} pluginManagement { repositories { google() mavenCentral() gradlePluginPortal() } } ``` Include the SDK in your app-level `build.gradle` file under `dependencies`: ```groovy theme={null} dependencies { implementation 'com.quicko:income-tax-sdk:1.0.1-RC' } ``` Sync your project with Gradle files and build the project to complete the integration. ## iOS To integrate the `IncomeTaxSDK` in your iOS project using CocoaPods, follow these instructions: Ensure you have CocoaPods installed. If not, install it using the following command: ```bash theme={null} sudo gem install cocoapods ``` Navigate to your project directory in the terminal and run: ```bash theme={null} pod init ``` Edit the `Podfile` to include: ```ruby theme={null} platform :ios, '12.0' target ':target' do use_frameworks! pod 'IncomeTaxSDK', '~> :version' end ``` Replace `':target'` with the actual target name of your project and `':version'` with the latest version. Install the pod by running: ```bash theme={null} pod install --repo-update ``` In your Swift files where you want to use the SDK, add: ```swift theme={null} import income_tax_sdk ``` # Integration Steps Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/integrating Step by step understanding of the workflow and interactions between different systems involved The following page will give you step by step understanding of the workflow and interactions between different systems involved. Quicko Mobile SDK Integrating Workflow The host application serves as the primary point of integration for the Quicko SDK. As part of this initiation, an optional `options` object can be passed to the SDK. This object typically contains user's data, identifying information and theme configuration. **Sample `options` object** ```json theme={null} { "user": { "email": "[email protected]", "mobile": { "isd": "91", "number": "XXXXXXXXXX" } }, "theme": { "mode": "dark", "seed": "#3962FF" } } ``` **`options` object breakdown** * **`user`**: Contains identifying information about the user. Values provided here will help streamline auth on the SDK. * **`theme`**: Contains visual customization options to modify the appearance of the SDK interface for a more personalized user experience. * **`mode`**: Specifies the display mode, which can be either "light" or "dark". In the provided example, it's set to "dark", meaning the SDK will use a dark-themed interface. * **`seed`**: Represents the accent color used for highlights and other UI elements in the SDK. This is generally your brand's primary theme color. The authorization step in the SDK is designed to verify the user's identity. This process ensures that only authenticated users can access specific resources or functionalities. If a user is already authenticated (i.e., has a valid session), they can proceed to the next step. If not, the SDK will initiate the identity setup process. When the user authentication process is successfully completed within the SDK, an event named `com.quicko.user.authenticated` will be emitted. This event carries with it an request token. It is essential for the host platform to exchange it for an access token. The access token serves as the necessary authorization to access user data via the Open APIs. Always ensure that this token is safely handled and stored to maintain the privacy and security of user data. Users can delve into preparing their tax returns right within the host application's interface. The SDK provides an intuitive UI and all the necessary tools for users to input, validate, and ensure that their tax information is correct and complete. Once satisfied, users can proceed to submit their tax returns through the SDK without needing to jump to a different platform or tool. Behind the scenes, once the user submits their tax information, Quicko's system takes charge. The entered data undergoes a transformation to align with the standards and format set by the Income Tax Department. Quicko ensures that this process is seamless and transparent to the user. After this transformation, the SDK utilizes the ERI (E-Return Intermediary) API to forward and officially submit the user's tax return to the Income Tax Department. The SDK is designed not just to act but also to inform. The SDK emits specific events like when users submit their tax return or exit without finishing the filing process. The host application can be configured to listen to these events. By capturing these events, the host application can provide feedback, notifications, or even guide the user to the next steps in the process. One of the advantages of integrating with the SDK is the ability to retrieve tax return details without cumbersome processes. Using the read-only access token provided during the initialization, the host app can send requests to Quicko's API. This lets the host application fetch and display the user's tax return details. Whether for verification, record-keeping, or any other purpose, this feature ensures that the host app remains the central hub for all user tax-related activities. # Configuration Options Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/options/config Module-specific configuration options for customizing the SDK behavior The configuration options allow you to dynamically customize module-specific settings to enhance the user experience. The configurations listed below are not exhaustive and may be extended in the future. ## com.quicko.it.file We support the following configurations for the file module: Toggle advisory CTAs in the filing journey. Defaults to `true`. **Example Configuration:** ```json theme={null} { "config": { "com.quicko.it.file": { "available": true, "com.quicko.it.file.advisory": { "available": true | false } } } } ``` Set `"available": false` to disable advisory CTAs in the filing journey. # Options Object Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/options/index Configure the Quicko Connect SDK behavior with flexible options ## Overview The `Options` object provides a flexible mechanism for configuring the behavior of the Quicko Connect SDK. This configuration object allows you to specify various options that can tailor the SDK's functionality to meet specific requirements of your application. The object is completely optional; omitting it will invoke the SDK's default behavior. ## Structure Each field is optional, and default settings are used if specific options are not provided. Below is a detailed description of each available option: Specifies the purpose of using the SDK. **Values**: `connect` | `refer` Specifies the intent to fully integrate into Quicko's ecosystem. It enables consent-based access to user events and Open API functionalities. This option is ideal for applications requiring deeper integration with Quicko's capabilities, such as retrieving user-specific data or actions through the API, which can enhance the application's functionality and user experience. Specifies an intent to use the SDK for a more specific and limited purpose — to assist users in solving their tax-related issues without the need for deep integration into the Quicko ecosystem. SDK operates in a mode that does not involve event callbacks, nor does it provide access to the Open API. This option is tailored for scenarios with the primary goal is to facilitate a straightforward and effortless integration. Defines the module of the product that you wish to interact with. **Values**: `com.quicko.it.save` | `com.quicko.it.pay` | `com.quicko.it.file` | `com.quicko.it.track` | `com.quicko.it.advisory` * **`com.quicko.it.save`**: Unlock greater insights for your users, help them visualize & plan their taxes. * **`com.quicko.it.pay`**: Offer your users a smarter, quicker, safer way to deal with their tax dues. * **`com.quicko.it.file`**: Seamless, three step tax return filing. Just simply autofill, review and e-file. * **`com.quicko.it.track`**: Harness our unique vantage point across integrations for a comprehensive P\&L. * **`com.quicko.it.advisory`**: Leverage our completely online tax advisory and extend the solution to your users. Exposes a set of configurations for different `module` options. You can learn more about different configurations here. Provides user-specific details that can be used by the SDK to prefill information for the user when they are authenticating with Quicko. **Fields**: * **`email`**: The user's email address. * **`mobile`**: An object containing mobile phone details. * **`isd`**: International Subscriber Dialing code, e.g., `91` for India. * **`number`**: The user's mobile phone number (without ISD code). * **`external_id`**: Identifier for a user in your system Configures the visual theme of the SDK components. **Fields**: * **`mode`**: Selects the theme mode. * **Values**: `dark` | `light` * **`seed`**: A hexadecimal color code that determines the primary color theme. For example, `#3962FF`. ## Usage Example Here is a simple JSON representation of the `Options` object with all options set: ```json theme={null} { "intent": "connect", "module": "com.quicko.it.file", "user": { "email": "[email protected]", "mobile": { "isd": "91", "number": "1234567890" }, "external_id": "bcfffb86-be2a-4ca4-9697-43340cca0334" }, "theme": { "mode": "dark", "seed": "#3962FF" } } ``` ## Integration The `Options` object can be easily integrated into your application setup when initializing the Quicko Connect SDK. Detailed instructions on integrating and using the SDK can be found in other sections of the documentation. This flexibility allows developers to customize the SDK to better align with the specific needs of their applications, providing a more tailored user experience. # Resetting Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/resetting Clear persisted user session data from the SDK The SDK has been designed to provide a seamless and unified experience for the end users. After a user has been authenticated successfully, the SDK will persist the user session information. This ensures that users won't need to reauthenticate during subsequent interactions, making the experience smoother. However, there could be scenarios where it's necessary to remove or clear the persisted user session data from the client side. For instance, if a user logs out or if there's a need to start a fresh session. ## `reset()` Method To facilitate this, the SDK provides the `reset()` method. ```java theme={null} QuickoSDK.INSTANCE.reset(); ``` ```kotlin theme={null} QuickoSDK.reset() ``` ```swift theme={null} QuickoSDK.instance.reset() ``` By invoking this method, developers can effectively clear all the data that the SDK persisted on the client end. This includes user session information, any cached data, and other related parameters. ## Sample Use Cases When a user logs out of your application, you can call the `reset()` method to ensure that their session and related data are wiped clean. If your platform has a privacy mode or similar feature, where data persistence isn't desired, you can use the `reset()` method to clear session data whenever needed. In rare cases, if there are session-related issues or anomalies, invoking the `reset()` method can serve as a first step in troubleshooting, ensuring a clean slate. # Setting up the SDK Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/setting_up Configure and set up the Quicko SDK in your application Quicko SDK is a library designed to provide seamless integration with Quicko's services. With just a few lines of code, developers can set up the SDK and leverage its functionality. Before utilizing the SDK, you need to ensure that you have integrated it into your project. Once that is complete, setting up is simple. ## Configuration and Setup For developers seeking to integrate Quicko Connect into their platforms, the primary point of interaction is through the QuickoSDK class. This class acts as the gateway to the plethora of features and functionalities that Quicko Connect offers. The class is designed as a singleton. This ensures that there's only one instance of the class throughout the application's lifecycle, maintaining data consistency and preventing potential issues that could arise from having multiple instances. Here are the ways you can access the SDK on different platforms: ```java theme={null} final QuickoSDK sdk = QuickoSDK.INSTANCE; ``` ```kotlin theme={null} val sdk = QuickoSDK ``` ```swift theme={null} let sdk = QuickoSDK.instance ``` To ensure proper initialization and functioning of the SDK, it's imperative to configure the API key using the `setAPIKey` method. This step must be completed prior to invoking any other operations. **Code Examples:** ```java theme={null} QuickoSDK.INSTANCE.setAPIKey("YOUR_API_KEY"); ``` ```kotlin theme={null} QuickoSDK.setAPIKey("YOUR_API_KEY") ``` ```swift theme={null} QuickoSDK.instance.setAPIKey("YOUR_API_KEY") ``` **Parameters:** * **`apiKey`**: A string parameter that represents the API key you've been provided with. An exception will be raised if the API key supplied to the SDK is invalid or does not adhere to the expected format. **Sample:** ```java theme={null} try { QuickoSDK.INSTANCE.setAPIKey("invalidKey"); } catch (IllegalArgumentException e) { System.out.println("Error encountered: Invalid API Key."); } ``` ```kotlin theme={null} try { QuickoSDK.setAPIKey("invalidKey") } catch (IllegalArgumentException e) { println("Error encountered: Invalid API Key.") } ``` ```swift theme={null} do { try QuickoSDK.instance.setAPIKey("invalidKey") } catch let error as IllegalArgumentException { print("Error encountered: Invalid API Key.") } ``` In this sample, an invalid API key ("invalidKey") is purposely used. Consequently, `IllegalArgumentException` is triggered, and the error message "Error encountered: Invalid API Key." gets displayed. Implementing a try-catch mechanism around the `setAPIKey` function is advisable. This allows for efficient exception handling, ensuring users receive pertinent feedback or assisting developers during the debugging process. # Launching Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/iosandroid-integration/triggering Launch the Quicko SDK tax solution within your application Triggering the QuickoSDK is the process of launching the tax solution within your app. This is typically done by calling the open method provided by the SDK. It's important to note that the implementation of this method varies slightly between Android and iOS, catering to the specific requirements and conventions of each platform. ## `open` method **Definition:** ``` open([PlatformSpecific Param], JSONObject options) ``` ### Parameters 1. **Platform Specific Param** * **Android**: `android.content.Context` * **iOS**: `UIViewController` 2. **options (Options)**: An object that allows customisation of the SDK's user interface. **Example Usage:** ```java theme={null} import org.json.JSONObject; // Constructing a JSONObject for the mobile number. JSONObject mobileJson = new JSONObject(); mobileJson.put("isd", "91"); mobileJson.put("number", "9988774455"); // Constructing a JSONObject for the user. JSONObject userJson = new JSONObject(); userJson.put("email", "[email protected]"); userJson.put("mobile", mobileJson); // Constructing a JSONObject for the theme. JSONObject themeJson = new JSONObject(); themeJson.put("mode", "dark"); themeJson.put("seed", "#2962FF"); // Constructing the root JSONObject which will contain the user and theme details. JSONObject optionsJson = new JSONObject(); optionsJson.put("intent", "connect"); optionsJson.put("module", "com.quicko.it.file"); optionsJson.put("user", userJson); optionsJson.put("theme", themeJson); // Triggering the FILE module with the constructed JSON options. // The open() method in QuickoSDK is a suspend function. // Suspend functions in Kotlin require an additional Continuation parameter when called from Java. // Java does not natively support coroutines, so you must explicitly provide a Continuation instance. // Below is an example of invoking the open() method with a "dummy" Continuation to handle or ignore the result. QuickoSDK.INSTANCE.open( getApplicationContext(), // Pass the application context as the first parameter optionsJson, // Provide the JSONObject with options as the second parameter new Continuation() { // Manually implement the Continuation interface for the third parameter @NotNull @Override public CoroutineContext getContext() { // Returning an empty coroutine context as no specific context is required here. return EmptyCoroutineContext.INSTANCE; } @Override public void resumeWith(@NotNull Object result) { // This method is called when the suspend function completes. // The 'result' parameter can contain either the success result or an exception: // - If successful, result will be of type Unit. // - If an exception occurred, result will be an instance of Result.Failure. // For simplicity, you can leave this method empty since you don't need to handle the outcome. } } ); ``` ```kotlin theme={null} import org.json.JSONObject // Creating a JSONObject for the mobile. val mobileJson = JSONObject().apply { put("isd", "91") put("number", "9988774455") } // Creating a JSONObject for the user. val userJson = JSONObject().apply { put("email", "[email protected]") put("mobile", mobileJson) } // Creating a JSONObject for the theme. val themeJson = JSONObject().apply { put("mode", "dark") put("seed", "#2962FF") } // Creating the root JSONObject which will include user and theme. val optionsJson = JSONObject().apply { put("intent", "connect") put("module", "com.quicko.it.file") put("user", userJson) put("theme", themeJson) } // Triggering the FILE module with the constructed JSON options. QuickoSDK.INSTANCE.open(context, optionsJson) ``` ```swift theme={null} import Foundation import income_tax_sdk // Creating a dictionary for the mobile. let mobileJson: [String: Any] = [ "isd": "91", "number": "9988774455" ] // Creating a dictionary for the user. let userJson: [String: Any] = [ "email": "[email protected]", "mobile": mobileJson ] // Creating a dictionary for the theme. let themeJson: [String: Any] = [ "mode": "dark", "seed": "#2962FF" ] // Creating the root dictionary which will include user and theme. let optionsJson: [String: Any] = [ "intent": "connect", "module": "com.quicko.it.file", "user": userJson, "theme": themeJson ] // Triggering the FILE module with the constructed JSON options. QuickoSDK.open(context: context, options: optionsJson) ``` This exception is thrown when the API key has not been set before invoking the `open` method, and if your intent is `connect`. **Example:** ```java theme={null} try { QuickoSDK.open(myContext, myModule); } catch (IllegalArgumentException iEA) { System.out.println("Error: API Key has not been set."); } ``` ```kotlin theme={null} try { QuickoSDK.open(myContext, myOptions) } catch (e: IllegalArgumentException) { println("Error: API Key has not been set.") } ``` ```swift theme={null} do { try QuickoSDK.open(controller: myController, options: myOptions) } catch let error as IllegalArgumentException { print("Error: API Key has not been set.") } catch { // Handle other potential errors if any. } ``` In the above example, if the API key hasn't been set before calling the `open` method, the `IllegalArgumentException` will be thrown, and the error message "Error: API Key has not been set." will be printed. * Always ensure that the API key has been set using the `setAPIKey` method before invoking the `open` method. * It's a good practice to wrap the `open` method call inside a try-catch block to handle the `IllegalArgumentException` and provide feedback to the user or log the error for debugging purposes. # Connect Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/web-integration/connect Advanced integration workflow with consent-based access to user data via Open APIs This requires a more hands-on approach from the channel partner's development team. It is suitable for partners who desire a more integrated solution with consent-based access to user data via open APIs. Quicko Web Integration Connect Workflow ## Open API Access In the context of integrating with open APIs, it is crucial to understand that obtaining an access token, which includes user consent, is a fundamental requirement. This process ensures that all interactions with the API are secure and authorized by the user. It's important to note that the workflow for integrating these APIs into a web environment is slightly different compared to mobile integration. This document will provide a clear guide on how to effectively implement the workflow for web integration while adhering to the necessary security protocols and user consent guidelines. ## Workflow Overview The Host app initiates the OAuth flow by redirecting the user to Quicko OAuth with a properly constructed URL including an options object that is base64 encoded. The user grants consent on Quicko's OAuth app for data sharing. Upon successful consent, Quicko redirects back to the Host app with a `request_token`. The Host app exchanges this token for an access token. With the access token, the Host app can now access the user's Quicko data. Finally, the Host redirects the user to Quicko's Income Tax Web App to proceed with their tax-related activities. ## Step-by-Step Integration ### 1. Redirect to Quicko OAuth Construct a redirect URL to Quicko's OAuth endpoint. Include your `api_key` and the `redirect` (the URL to which Quicko will send the user after authorization) and an `options` query parameter, which is a base64-encoded JSON object containing user details and theme preferences. #### Options Object Here is the JSON structure of the options object: ```json theme={null} { "user": { "email": "[email protected]", "mobile": { "isd": "91", "number": "XXXXXXXXXX" } }, "theme": { "mode": "dark", "seed": "#2962FF" }, "intent": "SAVE" | "PAY" | "FILE" | "TRACK" } ``` Encode this JSON object in base64 and append it as a query parameter to the OAuth URL. Additionally, to mark the user as an affiliate of your platform, you'll need to pass an `ref` query parameter. **Sample URL:** ```text theme={null} https://oauth.quicko.com/?api_key={{your_api_key}}&redirect={{base64_encoded_host_redirect}}&ref={{your_affiliate_id}}&options=eyJ1c2VyIjp7ImVtYWlsIjoidXNlckBtYWlsLmNvbSIsIm1vYmlsZSI6eyJpc2QiOiI5MSIsIm51bWJlciI6IlhYWFhYWFhYWFgifX0sInRoZW1lIjp7Im1vZGUiOiJkYXJrIiwic2VlZCI6IiMyOTYyRkYifSwiaW50ZW50IjoiRklMRSJ9 ``` ### 2. User Consent When the user is redirected to Quicko's OAuth endpoint, they will be presented with the consent screen. Upon granting consent, Quicko will redirect the user back to your `redirect`. ### 3. Handle the Redirect Upon user consent, Quicko redirects the user to your `redirect` with a `request_token`. If the user denies consent, they will be redirected back with a query parameter `status` set to `cancelled`. For example, if the host's `redirect` is `host-app.com/incoming`, the user will be redirected to: ```text theme={null} https://host-app.com/incoming?status=cancelled ``` ```text theme={null} https://host-app.com/incoming?status=success&request_token={{token}} ``` #### Handling Denial of Consent If a user denies consent, handle the redirection with the `status` parameter appropriately in your application flow, typically by presenting an appropriate message to the user or offering the option to retry the authorization process. ### 4. Exchange Request Token Your server should exchange the `request_token` for an access token by making a server-side request to Quicko's token exchange endpoint. Store this access token securely on your server for subsequent requests to Quicko's APIs. You can use the OAuth Authorize API for this exchange. ### 5. Redirect to Income Tax Web App With the access token, query the user's data as needed. Then, to continue their tax journey, redirect the user to Quicko's Income Tax Web App. **URL:** `https://it.quicko.com` ## Recommendations Always ensure the `access_token` is stored securely on your server. Never expose it in client-side code or public repositories. Regularly listen to event postbacks from Quicko's services to keep track of the user's journey and take appropriate actions. # Web Integration Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/web-integration/index Overview of integrating your service with Quicko through our web-based platform This document is designed to provide you with an overview of how to integrate your service with Quicko through our web-based platform. ## Why Web Integration? Solving taxes is intricate and often requires comprehensive user interaction. Our web integration ensures that your users access a full-fledged, tax-focused environment, tailored to handle these complexities efficiently. By redirecting users to the Quicko's web app, they can complete their tax journey in a setting specifically designed for this purpose, rather than within the confines of a channel partner's app which may not be optimized for such tasks. ## Integration Options Quicko offers two distinct pathways for web integration: Lite Integration and Advanced Integration. Each path caters to different needs and capabilities of our channel partners. **Overview**: This is the fastest way to connect with Quicko. It's designed for partners seeking a straightforward, minimal development effort. **Overview**: For partners looking for a deeper, more comprehensive, consent based insights into their user's taxes using our Open APIs. # Refer Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/integrations/web-integration/refer Lite integration workflow for hassle-free integration with Quicko The Refer Integration Workflow is designed for channel partners seeking a hassle-free, minimal development effort integration with Quicko. This method primarily involves redirecting your user to our Income Tax Web Application. Quicko Web Integration Refer Workflow ## Workflow Overview The redirect URL would look like: ``` https://it.quicko.com?affiliate_id={{YOUR_AFFILIATE_ID}} ``` An `affiliate_id` helps Quicko attribute a user conversion to you. You can also use your affiliate dashboard to keep track of all the conversions and transactions performed by the users attributed to you. To get started, head over to Clique. Integrate a simple redirection mechanism in your system to navigate users to the acquired URL. # Types of Notifications Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/notifications/types-of-notifications Overview of Quicko's notification system for keeping users informed about their transactions ## Overview This guide is designed to provide an overview of the notification system employed by us to keep users informed about their transactions. By understanding the types of notifications sent by us, Channel Partners can develop complementary communication strategies to enhance user engagement and ensure a seamless experience. ## Types of Notifications from Quicko We employ a multi-channel notification strategy to keep users informed about their activity. These notifications are automatic and designed to provide timely updates. Here's a breakdown of the types of notifications users can expect: These serve as immediate acknowledgment of the transaction's initiation, completion or failure. Some examples of such transactions are present in the Event Directory. For security-related events, such as login attempts from new devices or locations, password changes, or other security settings modifications, users receive alerts. These are crucial for maintaining the integrity of user accounts and for prompt action in case of unauthorized access. Occasionally, users may receive notifications about promotions, special offers, or new services that are available. These are intended to provide users with information that could enhance their experience with Quicko. Our notification system uses multiple channels to ensure users receive important updates through their preferred communication method, whether it's email, SMS, push notifications, or in-app alerts. # OAuth Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/oauth/oauth Learn how to integrate OAuth authentication workflow for third-party applications ## Overview This guide outlines the steps necessary for integrating the OAuth authentication workflow between an **Actor** (end user), a **Host** (client application), and **Quicko**. The end user who initiates the OAuth flow Your client application requesting access to Open APIs Quicko's OAuth application that manages authentication ## OAuth Flow OAuth Authentication Flow The OAuth flow involves four main steps: ## Workflow Steps The Host sends an intent along with options to the OAuth App. **Options include:** * API Key (provided during onboarding) * Redirect URI (where the user returns after consent) The Host application initiates the flow by redirecting the Actor to Quicko's OAuth application. The OAuth App authenticates and obtains consent from the Actor. **Authentication Process:** 1. OAuth App sends an OTP to the Actor to establish their identity 2. Actor enters the OTP to verify their identity 3. Actor is presented with a consent screen 4. Actor reviews and approves the Host's access request The Actor must be a registered Quicko user to complete this step. Once consent is given, the OAuth App generates a `request_token` for the Host. Upon the Actor's consent, the OAuth App redirects back to the Host. **Redirect Details:** * Issues HTTP 302 status code * Redirects to the URI provided by the Host * Appends the Resource Owner's `request_token` as a query parameter ``` https://your-app.com/callback?request_token=eyJhbGciOiJIUzUxMi... ``` The Host exchanges the `request_token` for long-lived tokens. The Host calls the [OAuth Authorize API](/projects/connect/api-reference/authentication/authorization) with: * `request_token` (from the redirect) * `x-api-key` (your API key) * API User's `access_token` (from authenticate endpoint) **Response includes:** * Resource Owner's `access_token` - to access Open APIs * Resource Owner's `refresh_token` - to get new access tokens Securely store both tokens in your database associated with the Actor's account. ## Understanding Different Tokens All of the tokens mentioned below belong to the **Actor (Resource Owner)**, not your application. There are various types of tokens that serve different purposes within the OAuth 2.0 framework. This section explains the different tokens involved in the interaction between your app and Quicko. **Description:** A short-lived token which the Host must exchange to receive the Resource Owner's access token. | Property | Value | | - | - | | **Lifetime** | 10 minutes | | **Purpose** | Initiate token exchange | | **Source** | Returned after Actor grants consent | | **Usage** | Exchange for access token via OAuth Authorize API | The request token expires after 10 minutes. Exchange it immediately for access and refresh tokens. **Description:** Used by the Host to access Quicko's Open APIs on behalf of the Resource Owner. | Property | Value | | - | - | | **Lifetime** | 24 hours | | **Purpose** | Access Open APIs | | **Source** | Received via OAuth Authorize API | | **Usage** | Include in `Authorization` header when calling Open APIs | **Example:** ```bash theme={null} curl https://api.quicko.com/income-tax/tax-payer \ -H "Authorization: Bearer eyJhbGciOiJIUzUxMi..." \ -H "x-api-key: your_api_key" ``` When the access token expires, use the refresh token to obtain a new one without requiring the Actor to re-authenticate. **Description:** Long-lived token for obtaining new access tokens without user interaction. | Property | Value | | - | - | | **Lifetime** | 1 year | | **Purpose** | Obtain new access tokens | | **Source** | Received via OAuth Authorize API | | **Usage** | Exchange for new access token via Authorize API | **When to use:** * Access token has expired (after 24 hours) * You receive 401 Unauthorized response from Open APIs * Proactively refresh before expiry Securely store the refresh token and implement automatic token refresh logic in your application to ensure uninterrupted API access. ## Complete OAuth Journey The diagram above illustrates the complete OAuth flow: 1. **Redirect** - Host App redirects user to Quicko OAuth with `api_key` and `redirect` 2. **Redirect** - After user consent, Quicko redirects back to Host App with `request_token` 3. **Authorize** - Host App calls Quicko API Server with `request_token` 4. **Response** - Quicko API Server returns `access_token` and `refresh_token` 5. **End** - Host App can now access Open APIs on behalf of the user ## Best Practices Store tokens securely in your database with encryption. Never expose them in client-side code or logs. Implement automatic token refresh logic before the access token expires to ensure seamless API access. Handle token expiration gracefully. Catch 401 errors and automatically refresh the access token. Respect user consent. Provide clear options for users to revoke access to their data. ## Next Steps Learn how to exchange request tokens for access tokens Explore the available Open APIs you can access # Open APIs Source: https://company-quicko-8c502003.mintlify.app/projects/connect/guides/open-apis/open-apis Access tax-related data and user insights with consent-based Open APIs Open APIs are simple, easy to understand collection of REST-like APIs designed for **"Connect" partners** to enhance their understanding about their customers. Open APIs provide a secure, consent-based mechanism to gain insights into users' demographics, income situations and tax deductions, enabling data-driven and personalized investment & financial planning products. Quicko Connect Workspace ## Overview Open APIs allow "Connect" partners to access a variety of tax-related data through secure, consent-based endpoints. Retrieve verified identity of the user, such as name, email, and mobile number. Access high-level details about user demographics, including PAN, name, DOB, age as per PAN, category, residential status. Get metadata about Income Tax Returns, such as filing status, type of ITR filed, due dates, and acknowledgment number. Fetch computation of income and tax including income by heads, demat accounts, bank accounts, personal assets and liabilities. Access user's advisory service orders and their status. ## Available Endpoints **Endpoint:** `GET /entitlements/user` Retrieve verified identity information of the user. **Returns:** * Name (first name, last name) * Email address * Mobile number * User ID * Account status * Creation date **Use Cases:** * Verify user identity * Pre-fill application forms * Personalize user experience **Endpoint:** `GET /income-tax/tax-payer` Access comprehensive demographic and tax-related information. **Returns:** * PAN number * Full name as per PAN * Date of birth * PAN holder type (individual, HUF, etc.) * Filing category (general, senior citizen, etc.) * Residential status (resident, non-resident, etc.) * Contact details (address, email, mobile) **Use Cases:** * KYC verification * Age-based product recommendations * Residential status-based tax planning **Endpoint:** `GET /income-tax/tax-payer/itr` Get metadata about the user's Income Tax Returns. **Returns:** * Assessment year * ITR form type (ITR-1, ITR-2, etc.) * Tax regime (old/new) * Filing status (filed, in\_progress, etc.) * Filing type (original, revised, belated) * Due date and filed date * Acknowledgement number * E-verification details **Use Cases:** * Check tax filing compliance * Identify tax regime preference * Verify ITR filing status **Endpoint:** `GET /income-tax/tax-payer/itr/computation-of-tax` Fetch computation of income and tax liability. **Returns:** * Income by heads: * Salary income * House property income * Capital gains (STCG, LTCG) * Business & profession income * Other sources * Chapter VI-A deductions * Total taxable income * Tax payable/refundable * Interest and penalties (234A, 234B, 234C, 234F) * TDS and advance tax paid **Use Cases:** * Tax liability assessment * Investment planning recommendations * Tax saving opportunities identification **Endpoint:** `GET /advisory/contacts/{contact_id}/orders` Access user's advisory service orders. **Returns:** * Order ID and status * Order creation and update timestamps * Order pricing details * GST amount * Order resolution details **Use Cases:** * Track advisory service usage * Service billing and reconciliation ## Authorization Open APIs require an `Authorization` header with the JWT access token obtained through the OAuth flow. All Open API requests must include two headers: | Header | Description | Required | | - | - | - | | `Authorization` | Resource Owner's JWT access token (obtained via OAuth) | Yes | | `x-api-key` | Your API User Key (provided during onboarding) | Yes | ### Example Request ```bash cURL theme={null} curl https://api.quicko.com/income-tax/tax-payer \ -H "Authorization: Bearer eyJhbGciOiJIUzUxMi..." \ -H "x-api-key: key_live_xxxxxxxxxxxxx" ``` ```javascript Node.js theme={null} const axios = require('axios'); const response = await axios.get('https://api.quicko.com/income-tax/tax-payer', { headers: { 'Authorization': 'Bearer eyJhbGciOiJIUzUxMi...', 'x-api-key': 'key_live_xxxxxxxxxxxxx' } }); console.log(response.data); ``` ```python Python theme={null} import requests headers = { 'Authorization': 'Bearer eyJhbGciOiJIUzUxMi...', 'x-api-key': 'key_live_xxxxxxxxxxxxx' } response = requests.get( 'https://api.quicko.com/income-tax/tax-payer', headers=headers ) print(response.json()) ``` Explore and test all Open APIs with detailed request/response examples, schemas, and live API playground. ## Getting Started Contact Quicko to get your API credentials (API Key and Secret). Use the [Authenticate API](/projects/connect/api-reference/authentication/authentication) to get your application's access token. Follow the [OAuth guide](/projects/connect/guides/getting-started/oauth) to get user consent and obtain Resource Owner tokens. Use the Resource Owner's access token to call Open APIs and retrieve user data. Download our Postman collection to test the APIs quickly **Quicko Connect Postman Collection** → ## Recommendations Familiarize yourself with each API endpoint, its purpose, and how it fits into the services you offer. Each API has specific request parameters and response data formats. Understanding these ensures seamless integration. Handle and store user information securely and in compliance with data privacy and protection guidelines (GDPR, DPDPA, etc.). Ensure ongoing consent from users to access their data. Provide clear options to revoke access if desired. ## Data Privacy & Security **Important:** User data obtained through Open APIs is sensitive personal and financial information. You must: Always obtain explicit user consent before accessing their data through the OAuth flow. Use industry-standard encryption (AES-256, TLS 1.2+) for storing and transmitting data. Restrict data access to only authorized personnel and systems. Use role-based access control (RBAC). Ensure compliance with: * Digital Personal Data Protection Act (DPDPA), 2023 * GDPR (for EU users) * Other applicable data protection laws Allow users to: * View what data you've accessed * Revoke access at any time * Request data deletion Conduct regular security assessments and penetration testing of your integration. ## Rate Limiting API rate limits ensure fair usage and system stability. Current limits are subject to your service agreement. If you exceed rate limits, you'll receive a `429 Too Many Requests` response. Implement exponential backoff and retry logic in your application. ## Error Handling Open APIs return standard HTTP status codes and error responses: | Status Code | Meaning | | - | - | | `200` | Success | | `400` | Bad Request - Invalid parameters | | `401` | Unauthorized - Invalid or expired token | | `403` | Forbidden - Insufficient permissions | | `404` | Not Found - Resource doesn't exist | | `429` | Too Many Requests - Rate limit exceeded | | `500` | Internal Server Error | ### Example Error Response ```json theme={null} { "code": 401, "transaction_id": "abc123-def456-ghi789", "timestamp": 1699351274048, "error": { "message": "Invalid or expired access token", "type": "authentication_error" } } ``` Always check the `transaction_id` in responses. This helps Quicko support team debug issues quickly if you encounter problems. ## Next Steps Learn about API authentication Implement OAuth for user consent Explore detailed API documentation # Bank Account Details Source: https://company-quicko-8c502003.mintlify.app/projects/integration/bank-integration/account-details/bank_account_details Bank Account details enable tracking of the inflow and outflow in the user's account ## Overview The Bank Account Details API provides information about the user's bank accounts, including account type, account number, and banking identifiers (IFSC, SWIFT, MICR, UPI ID). This data is essential for Quicko to: * Identify and reconcile bank transactions for income tracking * Match deposits and withdrawals to their sources and purposes * Validate bank account ownership and verify authenticity * Link salary deposits to employer bank account details * Prepare accurate bank reconciliation statements for tax compliance Bank Account details enable tracking of the inflow and outflow in the user's account. Bank Account details help identify the sender or receiver of the user and further provide account type and account number information. ## Response Format Your API should return bank account information with the following data points: ## Bank Account Details | Param | Type | Required | Description | | - | - | - | - | | account\_type | String | Yes | The type of account the user is holding i.e 'Current Account' or 'Savings Account' | | account\_number | Number | Yes | Account number of the user | | ifsc | String | Yes | IFSC of the particular Branch | | upi\_id | String | No | UPI address for the bank account | | swift\_code | String | No | Code for International Interbank Transactions | | micr | String | No | Magnetic Ink Character recognition | | MMID | String | No | Mobile money identifier | # Bank Account Statement Source: https://company-quicko-8c502003.mintlify.app/projects/integration/bank-integration/account-statement/bank_account_statement Bank Account Statement is an official document that summarizes taxpayers' account activity ## Overview The Bank Account Statement API provides a detailed transaction history for a user's bank account over a specific period. This includes all deposits and withdrawals with transaction dates, amounts, and descriptions. This data is critical for Quicko to: * Reconcile bank transactions with income sources * Identify and classify business vs personal transactions * Track cash flow and account balances * Verify salary deposits and other income sources * Maintain audit trails for tax compliance * Identify potential undisclosed income or expenses Bank Account Statement is an official document that summarizes taxpayers' account activity. Bank Account Statement helps understand the type of transaction an individual has incurred which would help Quicko to identify business transactions activity. ## Query Parameters Your API should accept `from` and `to` query parameters to retrieve bank transactions within a specific date range. ``` GET /statement?from=YYYY-MM-DD&to=YYYY-MM-DD ``` ## Response Format Your API should return bank statement transactions with the following fields: ## Headers of Bank Statement API | Param | Type | Required | Description | | - | - | - | - | | transaction\_id | String | Yes | Unique transaction id for each transaction | | transaction\_type | String | Yes | A transaction to be classified as a Withdrawal or Deposit | | transaction\_date | Number | Yes | Date of the transaction | | amount | Number | Yes | Amount of the transaction | | description | String | Yes | The narration of the transaction. | | closing\_balance | Number | No | Closing balance of the account | # Balance Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/balance/balance Balance information for trading accounts ## Overview The Balance API should return the trading account balance information for a user's account on a specific date. This is essential for Quicko to accurately compute taxes and prepare financial reports based on account balances as of a particular date (e.g., year-end, month-end, or any regulatory date). ## Query Parameters Your API should accept a `date` query parameter to retrieve balance information for that specific date. This allows Quicko to fetch historical balance data when needed for compliance and tax computation purposes. ``` GET /user/balance?date=YYYY-MM-DD ``` ### Response Your Balance API should return the following balance information: | Param | Type | Required | Description | | - | - | - | - | | acc\_type | String | No | Type of account, i.e., commodity or security | | opening\_balance | Number | No | The opening balance of the trader | | used\_margin | Number | Yes | The margin used by the trader. Positive values denote the amount blocked into an open order or position. A Negative value denotes the amount being released. | | available\_margin | Number | Yes | Total margin available for trading | | closing\_balance | Number | Yes | The closing balance of the trader | # Domestic Financial Instruments Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/financial_instruments/domestic/domestic_financial_instruments Financial instruments reference data for domestic securities ## Overview The Domestic Financial Instruments API provides reference data for securities held in user accounts. This data includes current market prices (last traded prices) which are essential for Quicko to calculate unrealized P\&L (Profit & Loss) on holdings that have not been sold yet. When users hold securities, mutual funds, or derivatives, we need up-to-date pricing information to accurately compute: * Unrealized gains/losses on active positions * Portfolio valuations * Tax compliance reporting based on current market values * Tax gain/loss harvesting opportunities ## Response Format Your API should return financial instrument reference data organized by three categories: ## Equity Instruments Equity data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | String | No | ISIN is the international security identification number | | symbol | String | Yes | Symbol or description of the instrument | | name | String | No | Name of the scrip | | fmv | Number | No | The High Price of the stock on 31 Jan 2018 | | last\_traded\_price | Number | Yes | The last traded price of the instrument (used to calculate current market value and unrealized P\&L) | ## Mutual Fund Instruments Mutual fund data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | String | No | ISIN is the international security identification number | | symbol | String | Yes | Symbol/Scheme code or description of the instrument | | name | String | No | Name of the scheme | | fund\_type | String | Yes | Type of fund: Equity, Debt or Hybrid | | fmv | Number | No | High NAV of the Mutual Fund on 31 Jan 2018 | | last\_traded\_price | Number | Yes | The last traded price/NAV of the instrument (used to calculate current market value and unrealized P\&L) | ## Derivative Instruments Derivative data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | String | No | ISIN is the international security identification number | | symbol\_underlying | String | Yes | Symbol or description of the underlying security | | name | String | No | Name of the scrip | | instrument\_type | String | Yes | Indicates whether the instrument was Future or Option | | category | String | Yes | Type of F\&O: Equity, Commodity or Currency | | expiry | String | Yes | Expiry Date (for Derivatives) | | strike | Number | Yes | The Strike price (for Options) | | last\_traded\_price | Number | Yes | The last traded price of the instrument (used to calculate current market value and unrealized P\&L) | # Foreign Financial Instruments Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/financial_instruments/foreign/foreign_financial_instruments Financial instruments reference data for foreign securities ## Overview The Foreign Financial Instruments API provides reference data for foreign securities held in user accounts. This data includes current market prices (closing values) which are essential for Quicko to calculate unrealized P\&L (Profit & Loss) on foreign holdings that have not been sold yet. When users hold foreign stocks, depository receipts, mutual funds, or ETFs, we need up-to-date pricing information to accurately compute: * Unrealized gains/losses on active foreign positions * Portfolio valuations in foreign currencies * Tax compliance reporting based on foreign investment holdings * Tax gain/loss harvesting opportunities on international securities ## Response Format Your API should return financial instrument reference data organized by four categories: ## Stock Instruments Stock data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of stock | | address | string | No | Address of the company | | country | string | Yes | Country of the company | | zip\_code | string | Yes | Zip code of the address | | 52\_week\_high | number | Yes | 52 week high price for the calendar year | | closing\_value | number | Yes | Closing value as of last traded date of the calendar year (used to calculate current market value and unrealized P\&L) | ## Depository Receipt Instruments Depository receipt data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of receipt | | address | string | No | Address of the company | | country | string | Yes | Country of the company | | zip\_code | string | Yes | Zip code of the address | | 52\_week\_high | number | Yes | 52 week high price for the calendar year | | closing\_value | number | Yes | Closing value as of last traded date of the calendar year (used to calculate current market value and unrealized P\&L) | ## Mutual Fund Instruments Mutual fund data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | scheme\_name | string | Yes | Symbol or description of fund | | address | string | No | Address of the company | | country | string | Yes | Country of the company | | zip\_code | string | Yes | Zip code of the address | | 52\_week\_high | number | Yes | 52 week high price for the calendar year | | closing\_value | number | Yes | Closing value as of last traded date of the calendar year (used to calculate current market value and unrealized P\&L) | ## ETF Instruments ETF data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | scheme\_name | string | Yes | Symbol or description of fund | | address | string | No | Address of the company | | country | string | Yes | Country of the company | | zip\_code | string | Yes | Zip code of the address | | 52\_week\_high | number | Yes | 52 week high price for the calendar year | | closing\_value | number | Yes | Closing value as of last traded date of the calendar year (used to calculate current market value and unrealized P\&L) | # Domestic Securities Holdings Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/holdings/domestic/domestic_securities_holdings Holdings data for domestic securities including Equity, Mutual Funds, and ETF ## Overview The Domestic Securities Holdings API provides a snapshot of all securities currently held by a user on a specific date. This includes equities, mutual funds, and ETFs. Holdings data is critical for Quicko to understand the user's portfolio composition, calculate capital gains/losses, and prepare accurate tax reports. ## Query Parameters Your API should accept an `as_on_date` query parameter to retrieve holdings for a specific date. This allows Quicko to fetch historical holdings snapshots when needed for tax compliance and regulatory reporting. ``` GET /securities/domestic/holdings?as_on_date=YYYY-MM-DD ``` ## Response Format Your API should return holdings data organized by three categories: ## Equity Holdings Equity holdings data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | Yes | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of the instrument | | quantity | number | Yes | Quantity of shares held of the instrument | | buy\_date | number | Yes | buy date epoch | | buy\_average | number | Yes | Average buy price across all trades | | label | string | No | Refer to Annexure for possible values | | last\_traded\_price | number | Yes | Last traded price of the instrument | ## Mutual Fund Holdings Mutual fund holdings data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | Yes | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of the scheme | | scheme\_type | enum | Yes | Scheme type of mutual fundPossible values are : Equity, Debt, Other | | quantity | number | Yes | Quantity of units held of the scheme | | buy\_date | number | Yes | buy date epoch | | buy\_average | number | Yes | Average buy price across all trades | | label | string | No | Refer to Annexure for possible values | | last\_traded\_price | number | Yes | Pervious closing NAV for the scheme | ## ETF Holdings ETF holdings data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | isin | string | Yes | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of the ETF | | asset\_class | enum | Yes | Scheme type of ETFPossible values are : Equity, Debt, Other | | quantity | number | Yes | Quantity of units held of the scheme | | buy\_date | number | Yes | buy date epoch | | buy\_average | number | Yes | Average buy price across all trades | | label | string | No | Refer to Annexure for possible values | | last\_traded\_price | number | Yes | Last traded price of the instrument | ## Annexure | Corporate Action | ENUM | | - | - | | Amalgamation | amalgamation | | Bonus Issue | bonus\_issue | | Buy Back of Shares | buy\_back | | Consolidation of Shares | consolidation | | Dividend | dividend | | Dividend on Preference Shares | dividend | | Income Distribution (InvIT) | income\_distribution\_invit | | Income Distribution RITES | income\_distribution\_rites | | InvIT - Return of CapitaL | return\_of\_capital\_invit | | Preferential Issue of shares | preferential\_issue | | Reduction of Capital | reduction\_of\_capital | | Right Issue of Equity Shares | right\_issue | | Scheme of Arrangement | scheme\_of\_arrangement | | Spin Off | spin\_off | | Stock Split | stock\_split | | Voluntary Delisting of Shares | voluntary\_delisting\_of\_share | | Donation of security | donation | | Transfer of securities in form of gift | transfer | | Loss of security | lost | | Transfer of securities | transfer | | Other | other | **Quantity of Holdings** The holding quantity in the response should be unpledged. # Foreign Securities Holdings Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/holdings/foreign/foreign_securities_holdings Holdings data for foreign securities including Stocks, Depository Receipts, Mutual Funds, and ETF ## Overview The Foreign Securities Holdings API provides a snapshot of all foreign securities currently held by a user on a specific date. This includes foreign stocks, depository receipts, mutual funds, and ETFs. Foreign holdings data is critical for Quicko to understand international portfolio composition, calculate capital gains/losses in foreign currencies, and prepare accurate tax reports for international investments. ## Query Parameters Your API should accept an `as_on_date` query parameter to retrieve holdings for a specific date. This allows Quicko to fetch historical holdings snapshots when needed for tax compliance and regulatory reporting on foreign investments. ``` GET /securities/foreign/holdings?as_on_date=YYYY-MM-DD ``` ## Response Format Your API should return holdings data organized by client details and four security categories: ## Client Details Client information should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | name | string | Yes | Name of the client | | pan | string | Yes | PAN of the client | | client\_id | string | Yes | Unique identifier of the Client's investment account | | country | string | Yes | Country where investments were made | | tin | string | Yes | TIN for the country or passport number | ## Stock Holdings Stock holdings data should include the following fields: | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | symbol | string | Symbol or description of equity stock | | quantity | number | Trading quantity | | buy\_date | number | The date on which the equity stock was bought | | buy\_price | number | Price at which a unit was bought | | currency | number | The 3 letter currency code for the price based on ISO 4217 | | transaction\_type | string | Indicates whether the order is :buy , sell, send, receive Or trade, | | label | string | Refer to [label](/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl#annexure-1-labels) for possible values | | last\_traded\_price | string | Last traded market price of the equity stock. | ## Depository Receipt Holdings Depository receipt holdings data should include the following fields: | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | symbol | string | Symbol or description of depositary receipt. | | quantity | number | Trading quantity | | buy\_date | number | The date on which the receipt was bought | | buy\_price | number | Price at which a unit was bought | | currency | number | The 3 letter currency code for the price based on ISO 4217 | | transaction\_type | string | Indicates whether the order is :buy , sell, send, receive Or trade, | | label | string | Refer to [label](/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl#annexure-1-labels) for possible values | | last\_traded\_price | string | Last traded market price of the receipt.. | ## Mutual Fund Holdings Mutual fund holdings data should include the following fields: | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | scheme\_name | string | Symbol or description of fund | | quantity | number | Trading quantity | | buy\_date | number | The date on which the fund was bought | | buy\_price | number | Price at which a unit was bought | | currency | number | The 3 letter currency code for the price based on ISO 4217 | | transaction\_type | string | Indicates whether the order is :buy , sell, send, receive Or trade, | | label | string | Refer to [label](/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl#annexure-1-labels) for possible values | | last\_traded\_price | string | Last traded market price of the fund. | ## ETF Holdings ETF holdings data should include the following fields: | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | scheme\_name | string | Symbol or description of fund | | quantity | number | Trading quantity | | buy\_date | number | The date on which the fund was bought | | buy\_price | number | Price at which a unit was bought | | currency | number | The 3 letter currency code for the price based on ISO 4217 | | transaction\_type | string | Indicates whether the order is :buy , sell, send, receive Or trade, | | label | string | Refer to [label](/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl#annexure-1-labels) for possible values | | last\_traded\_price | string | Last traded market price of the fund. | # Open Positions Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/open_positions/open_positions Open Positions for Derivatives Trades ## Overview The Open Positions API provides information about all currently open derivative positions held by a user on a specific date. Open positions represent active futures and options contracts that have not yet been closed. This data is essential for Quicko to: * Calculate unrealized P\&L on active derivative positions * Monitor margin requirements and risk exposure * Prepare accurate profit/loss statements for tax compliance * Track derivative holdings for regulatory reporting ## Query Parameters Your API should accept an `as_on_date` query parameter to retrieve open positions for a specific date. This allows Quicko to fetch historical snapshots of derivative positions when needed for tax and compliance purposes. ``` GET /open-positions?as_on_date=YYYY-MM-DD ``` ## Response Format Your API should return open positions data organized by derivative category: ## Equity Derivatives Equity derivatives open positions data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | symbol | string | Yes | Symbol or description of the instrument | | instrument\_type | string | Yes | Type, possible values: Futures, Options | | strike\_price | number | No | Strike price of the contract | | expiry\_date | number | No | Contract expiry date epoch | | buy\_date | number | Yes | Buy date epoch | | exchange | string | No | Exchange where trade is made | | open\_quantity | number | Yes | Quantity of units held of the instrument | | average\_price | number | Yes | Average buy price across all trades | | previous\_closing\_price | number | Yes | Last traded price of the instrument | | unrealized\_profit\_or\_loss | number | No | Unrealized P\&L = (Previous Closing Price - Average Price) × Open Quantity | ## Currency Derivatives Currency derivatives open positions data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | symbol | string | Yes | Symbol or description of the instrument | | instrument\_type | string | Yes | Type, possible values: Futures, Options | | strike\_price | number | No | Strike price of the contract | | expiry\_date | number | No | Contract expiry date epoch | | buy\_date | number | Yes | Buy date epoch | | exchange | string | No | Exchange where trade is made | | open\_quantity | number | Yes | Quantity of units held of the instrument | | average\_price | number | Yes | Average buy price across all trades | | previous\_closing\_price | number | Yes | Last traded price of the instrument | | unrealized\_profit\_or\_loss | number | No | Unrealized P\&L = (Previous Closing Price - Average Price) × Open Quantity | ## Commodity Derivatives Commodity derivatives open positions data should include the following fields: | Param | Type | Required | Description | | - | - | - | - | | symbol | string | Yes | Symbol or description of the instrument | | instrument\_type | string | Yes | Type, possible values: Futures, Options | | strike\_price | number | No | Strike price of the contract | | expiry\_date | number | No | Contract expiry date epoch | | buy\_date | number | Yes | Buy date epoch | | exchange | string | No | Exchange where trade is made | | open\_quantity | number | Yes | Quantity of units held of the instrument | | average\_price | number | Yes | Average buy price across all trades | | previous\_closing\_price | number | Yes | Last traded price of the instrument | | unrealized\_profit\_or\_loss | number | No | Unrealized P\&L = (Previous Closing Price - Average Price) × Open Quantity | # Crypto Tradebook Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/tradebook/crypto/crypto_tradebook Tradebook provides you with all the trades that have been executed by an investor or trader. Brokers/Exchanges can share Tradebook to Report and calculate the Taxes ## Overview The Crypto Tradebook API provides a comprehensive record of all cryptocurrency transactions executed by a user. This includes buy/sell transactions, crypto-to-crypto swaps, transfers, staking rewards, mining rewards, and other income events. This data is critical for Quicko to: * Calculate capital gains and losses on cryptocurrency transactions * Track cost basis for tax compliance * Report cryptocurrency income (mining, staking, airdrops, etc.) * Prepare accurate crypto tax reports * Ensure compliance with tax regulations on virtual digital assets **Important** All the transactions should be passed in the request since inception of the account to ensure accurate tax calculations and compliance. ## Response Format Your API should return cryptocurrency transaction data with the following structure: | Param | Type | Required | Description | | - | - | - | - | | id | Number | Optional | Transaction ID of the particular trade | | date | Number | Yes | Trade Timestamp in epoch milliseconds | | transaction\_type | String | Yes | Indicates whether the order is :buy, sell, trade, send, receive | | label | String | Optional | Indicates the category of transaction type.Possible values :- interest, staking, staking\_reward, lost, mining\_reward, airdrop, donation, fork, gift, payment, other\_income | | received\_currency | String | Yes | Symbol of the cryptocurrency received(If transaction\_type = send/sellpass null) | | received\_quantity | Number | Yes | Quantity received by executing the transaction.(Required when received\_currency ≠ null) | | price | Number | Yes | Price at which unit is traded.(If transaction\_type = send/receivepass null) | | price\_currency | Number | Yes | Currency in which price is considered.Possible values: INR, USD, BTC etc.(Required when price ≠ null) | | price\_in\_inr | Number | Yes | Per unit value of the crypto in INR(Required when price\_currency ≠INR or = null) | | sent\_currency | String | Yes | Symbol/Name of the crypto sent(If transaction\_type =recieve/buy pass null). | | sent\_quantity | Number | Yes | Quantity sent by executing the transaction(Required if sent\_currency ≠ null). | | fee\_currency | String | No | Currency in which transaction fees or any other expense was made while executing the transaction | | fee\_amount | Number | No | Amount/quantity spent as fees or other expenses while executing transactions | | fee\_in\_inr | Number | No | INR value of the fee paid for the transaction.(Required if fee\_currency ≠ INR) | **Note** Whenever a field is blank pass `null` **Important** All the Transactions should be passed in the request since inception of the account. ## Definition of Transaction Type | Transaction Type | Definition | | - | - | | buy | OTC buy transaction on an exchange | | sell | OTC sell transaction on an exchange | | trade | Crypto to Crypto transaction on the Exchange | | send | Crypto sent out of the wallet | | receive | Crypto received in the wallet | ## Label | Label | Definition | | - | - | | airdrop | An unsolicited distribution of a cryptocurrency token or coin, usually for free | | interest | Cryptocurrency received in the form of Interest on the coins kept as a deposit | | staking | Lock crypto assets for a set period of time to help support the operation of a blockchain | | staking\_reward | The reward received for locked crypto assets for a set period of time | | fork | Crypto received due to hard fork | | gift | Crypto received as a gift in the wallet | | lost | Irrecoverable cryptocurrency from wallets | | mining\_reward | The crypto reward received on mining the coin | | donation | Defines a transaction that was donated to a charity | | payment | A transaction that was received as a payment for a good or service | | other income | Defines any other type of reward received | # Domestic Securities Tradebook Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/tradebook/domestic/domestic_securities A comprehensive trade book for domestic securities including equity, mutual funds, F&O, and foreign securities ## Overview The Domestic Securities Tradebook API provides a comprehensive record of all trades executed by a user for domestic securities. A trade book includes details of every buy and sell transaction, along with associated taxes and expenses. This data is critical for Quicko to: * Calculate capital gains and losses * Track cost basis and holding periods for tax compliance * Identify tax harvesting opportunities * Prepare accurate tax reports and maintain audit trails * Ensure compliance with tax regulations ## Query Parameters Your API should accept `from` and `to` query parameters to retrieve trades within a specific date range. Quicko typically requests all trades since account inception for accurate tax calculations. ``` GET /domestic-securities-trade-book?from=YYYY-MM-DD&to=YYYY-MM-DD ``` **Important** All the transactions should be passed in the request since inception of the account to ensure accurate tax calculations and compliance. ## Trade Types Domestic equity share transactions with tax expense breakdowns Mutual fund purchase and redemption transactions Derivative contracts including futures and options trading International equity, mutual funds, and derivative trades ## Equity Trades Domestic equity share transactions with comprehensive tax expense breakdowns. | Param | Type | Description | | - | - | - | | transaction\_id | string | Transaction Id to uniquely identify the transaction | | symbol | string | Symbol or description of equity share | | quantity | number | Trading quantity | | date | number | Transaction epoch timestamp | | price | number | Transaction price | | transaction\_type | string | Transaction type from possible values of 'BUY' or 'SELL' | | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | fmv | number | High stock price on 31/01/2018 | | brokerage | number | Brokerage expense | | clearing\_charges | number | Charges charged by clearing house | | exchange\_transaction\_charges | number | Transaction charges by exchange | | sebi\_turnover\_fees | number | Turnover fees by SEBI | | stt | number | Security Transaction Tax | | stamp\_duty | number | Stamp duty paid on transfer of shares | | sgst | number | State GST | | cgst | number | Central GST | | igst | number | Integrated GST | | interest | number | Interest paid on margins eg Margin Trading Facility | | depository\_charges | number | Depository charges paid on delivery of shares | | other\_transfer\_expenses | number | Any other expense relating to the transfer of shares | | corporate\_action | string | Corporate Action. Possible values: BUY\_BACK, DIVIDEND | ## Mutual Fund Trades Mutual fund purchase and redemption transactions with scheme classification. | Param | Type | Description | | - | - | - | | transaction\_id | string | Transaction Identifier to uniquely identify the transaction | | type | string | Scheme type, possible values: Equity, Debt, Other | | symbol | string | Symbol or description of mutual fund scheme | | quantity | number | Trading quantity (units) | | date | number | Transaction epoch timestamp | | price | number | NAV (Net Asset Value) at transaction | | transaction\_type | string | Transaction type possible values: 'BUY', 'SELL' | | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | fmv | number | High stock price on 31/01/2018 | | brokerage | number | Brokerage expense | | clearing\_charges | number | Charges charged by clearing house | | exchange\_transaction\_charges | number | Transaction charges by exchange | | sebi\_turnover\_fees | number | Turnover fees by SEBI | | stt | number | Security Transaction Tax | | stamp\_duty | number | Stamp duty paid on transfer of shares | | sgst | number | State GST | | cgst | number | Central GST | | igst | number | Integrated GST | | other\_transfer\_expenses | number | Any other expense relating to the transfer of units | ## Futures and Options Trades Derivative contracts including futures and options trading with comprehensive expense tracking. | Param | Type | Description | | - | - | - | | transaction\_id | string | Transaction identifier to uniquely identify the transaction | | symbol | string | Symbol or description of the derivative contract | | type | string | Type, possible values: Futures, Options | | quantity | number | Trading quantity (lot size) | | date | number | Transaction epoch timestamp | | price | number | Transaction price | | transaction\_type | string | Transaction type possible values: 'BUY', 'SELL' | | Param | Type | Description | | - | - | - | | brokerage | number | Brokerage expense | | clearing\_charges | number | Charges charged by clearing house | | exchange\_transaction\_charges | number | Transaction charges by exchange | | sebi\_turnover\_fees | number | Turnover fees by SEBI | | stt | number | Security Transaction Tax | | stamp\_duty | number | Stamp duty paid on transfer | | sgst | number | State GST | | cgst | number | Central GST | | igst | number | Integrated GST | | interest | number | Interest paid on margins eg Margin Trading Facility | | other\_transfer\_expenses | number | Any other expense relating to the transfer | ## Foreign Securities International equity share transactions. | Param | Type | Required | Description | | - | - | - | - | | transaction\_id | string | Yes | Transaction Identifier to uniquely identify the transaction | | isin | string | No | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of equity share | | quantity | number | Yes | Trading quantity | | date | number | Yes | Transaction epoch timestamp | | price | number | Yes | Transaction price | | transaction\_type | string | Yes | Transaction type from possible values of 'BUY' or 'SELL' | | transfer\_expenses | number | Yes | Transfer expense | | corporate\_action | string | No | Corporate Action. Possible values: BUY\_BACK, DIVIDEND | American Depositary Receipt transactions. | Param | Type | Required | Description | | - | - | - | - | | transaction\_id | string | No | Transaction Identifier to uniquely identify the transaction | | isin | string | No | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of ADR | | quantity | number | Yes | Trading quantity | | date | number | Yes | Transaction epoch timestamp | | price | number | Yes | Transaction price | | transaction\_type | string | Yes | Transaction type from possible values of 'BUY' or 'SELL' | | transfer\_expenses | number | Yes | Transfer expense | | corporate\_action | string | No | Corporate Action. Possible values: BUY\_BACK, DIVIDEND | Foreign mutual fund transactions. | Param | Type | Required | Description | | - | - | - | - | | transaction\_id | string | Yes | Transaction Identifier to uniquely identify the transaction | | isin | string | No | ISIN is the international security identification number | | type | string | Yes | Scheme type, possible values: Equity, Debt, Other | | symbol | string | Yes | Symbol or description of mutual fund scheme | | quantity | number | Yes | Trading quantity (units) | | date | number | Yes | Transaction epoch timestamp | | price | number | Yes | NAV (Net Asset Value) at transaction | | transaction\_type | string | Yes | Transaction type from possible values of 'BUY' or 'SELL' | | transfer\_expenses | number | Yes | Transfer expense | Foreign futures and options trading. | Param | Type | Required | Description | | - | - | - | - | | transaction\_id | string | Yes | Transaction Identifier to uniquely identify the transaction | | symbol | string | Yes | Symbol or description of the derivative contract | | type | string | Yes | Type, possible values: Futures, Options | | quantity | number | Yes | Trading quantity (lot size) | | date | number | Yes | Transaction epoch timestamp | | price | number | Yes | Transaction price | | transaction\_type | string | Yes | Transaction type possible values: 'BUY', 'SELL' | | transfer\_expenses | number | Yes | Transfer expenses | For foreign securities, transfer expenses typically include foreign exchange fees, wire transfer charges, and custodian fees. ## Corporate Actions Use these standard enumeration values when reporting corporate actions in trade data. Corporate actions can significantly impact capital gains calculations. Ensure you use the correct enum value for accurate tax reporting. | Corporate Action | ENUM Value | Description | | - | - | - | | Bonus Issue | **BONUS\_ISSUE** | Free additional shares to shareholders | | Stock Split | **STOCK\_SPLIT** | Subdivision of existing shares | | Consolidation of Shares | **CONSOLIDATION** | Reverse stock split | | Right Issue of Equity Shares | **RIGHT\_ISSUE** | Additional shares offered to existing shareholders | | Corporate Action | ENUM Value | Description | | - | - | - | | Dividend | **DIVIDEND** | Cash or stock dividend payment | | Income Distribution (InvIT) | **INCOME\_DISTRIBUTION\_INVIT** | InvIT income distribution | | Income Distribution RITES | **RITES** | RITES income distribution | | InvIT - Return of Capital | **RETURN\_OF\_CAPITAL\_INVIT** | Return of capital from InvIT | | Corporate Action | ENUM Value | Description | | - | - | - | | Amalgamation | **AMALGAMATION** | Merger of two or more companies | | Scheme of Arrangement | **SCHEME\_OF\_ARRANGEMENT** | Corporate restructuring scheme | | Spin Off | **SPIN\_OFF** | Separation of business division | | Corporate Action | ENUM Value | Description | | - | - | - | | Buy Back of Shares | **BUY\_BACK** | Company repurchasing its own shares | | Reduction of Capital | **REDUCTION\_OF\_CAPITAL** | Reduction in company's share capital | | Preferential Issue of shares | **PREFERENTIAL\_ISSUE** | Private placement of shares | | Voluntary Delisting of Shares | **DELISTING** | Removal from stock exchange listing | When processing corporate actions, ensure you maintain the continuity of cost basis and holding period for accurate capital gains tax calculations. # How to calculate P&L using tradebook? Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/tradebook/index A tradebook refers to a record or log of all trades executed by a particular trader A tradebook refers to a record or log of all trades executed by a particular trader. It serves as a detailed ledger that includes information such as the date and time of the trade, the securities involved, the quantity traded, and the price at which the trade was executed. Tax softwares use the tradebook to calculate Profit and Loss (P\&L) for tax compliance purposes by following a structured process. Here's a general overview of how they might do it: Tax softwares classify each trade based on its tax treatment. For example, trades may be categorized as capital gains/losses, ordinary income, dividends, interest income, or other types of income or expenses, depending on the nature of the transaction and applicable tax laws. FIFO (First In, First Out) settlements refer to a method used to determine the order in which trades are settled when securities are bought or sold. In FIFO settlements, the securities that are acquired or purchased first are also the ones that are considered to be sold first when a trade occurs. For securities held as investments, tax softwares calculate capital gains or losses by calculating FIFO settlements. They may also account for factors such as holding period and any adjustments for corporate actions like buyback etc. Once all trades have been classified and the relevant income and expenses have been accounted for, tax softwares calculate the net Profit and Loss for the period. This involves summing up all gains and losses across different categories and adjusting for any other income or deductions applicable to the taxpayer. Finally, tax softwares report the calculated P\&L on the appropriate tax returns, ensuring compliance with all relevant tax laws and regulations. # Domestic Securities Tradewise P&L Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/tradewise_pnl/domestic/domestic_securities_tradewise_pnl Tradewise P&L helps calculate profit and loss on a trade-level basis ## Overview The Domestic Securities Tradewise P\&L API provides profit and loss calculations on a trade-level basis for completed transactions. This is critical for Quicko to: * Calculate realized capital gains and losses * Segregate transactions by holding period (long-term vs short-term) * Generate accurate P\&L statements for tax compliance * Provide trade-by-trade cost basis and expense tracking * Track specific cost identification for matched buy-sell pairs ## Query Parameters Your API should accept `from` and `to` query parameters to retrieve P\&L data for a specific date range. ``` GET /securities/domestic/tradewise-pnl?from=YYYY-MM-DD&to=YYYY-MM-DD ``` ## Response Format Your API should return matched trade pairs with complete P\&L calculations organized by security type: ## Headers of Tradewise P\&L API ### Equity Trade The headers are explained below: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | symbol | string | Yes | Symbol or description of equity share | | quantity | number | Yes | Trading quantity | | buy\_date | number | Yes | Date of purchase | | buy\_average | number | Yes | Average buy price across all trades | | sell\_date | number | Yes | Date of Sell | | sell\_average | number | Yes | Average sell price across all trades | | fmv | number | No | High stock price on 31/01/2018 | | brokerage | number | No | Brokerage expense | | clearing\_charges | number | No | Charges charged by clearing house | | exchange\_transaction\_charges | number | No | Transaction charges by exchange | | sebi\_turnover\_fees | number | No | Turnover fees by SEBI | | stt | number | No | Security Transaction Tax | | stamp\_duty | number | No | Stamp duty paid on transfer of shares | | sgst | number | No | State GST | | cgst | number | No | Central GST | | igst | number | No | Integrated GST | | interest | number | No | Interest paid on margins eg Margin Trading Facility | | depository\_charges | number | No | Depository charges paid on delivery of shares | | other\_transfer\_expenses | number | No | Any other expense relating to the transfer of shares | | corporate\_action | string | No | Corporate Action. Possible values: BUY\_BACK, DIVIDEND | ### Mutual Fund Trade The headers are explained below: | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | scheme\_type | string | Yes | Scheme type, possible valuesEquity, Debt, Other | | symbol | string | Yes | Symbol or description of equity share | | quantity | number | Yes | Trading quantity | | buy\_date | number | Yes | Date of purchase | | buy\_average | number | Yes | Average buy price across all trades | | sell\_date | number | Yes | Date of Sell | | sell\_average | number | Yes | Average sell price across all trades | | fmv | number | No | High stock price on 31/01/2018 | | brokerage | number | No | Brokerage expense | | clearing\_charges | number | No | Charges charged by clearing house | | exchange\_transaction\_charges | number | No | Transaction charges by exchange | | sebi\_turnover\_fees | number | No | Turnover fees by SEBI | | stt | number | No | Security Transaction Tax | | stamp\_duty | number | No | Stamp duty paid on transfer of shares | | sgst | number | No | State GST | | cgst | number | No | Central GST | | igst | number | No | Integrated GST | | other\_transfer\_expenses | number | No | Any other expense relating to the transfer of shares | | corporate\_action | string | No | Corporate Action. Possible values: BUY\_BACK, DIVIDEND | ### Futures and Options Trade The headers are explained below: | Param | Type | Required | Description | | - | - | - | - | | symbol | string | Yes | Symbol or description of equity share | | type | string | Yes | Type, possible valuesFutures, Options | | quantity | number | Yes | Trading quantity | | buy\_average | number | Yes | Average buy price across all trades | | sell\_average | number | Yes | Average sell price across all trades | | brokerage | number | No | Brokerage expense | | clearing\_charges | number | No | Charges charged by clearing house | | exchange\_transaction\_charges | number | No | Transaction charges by exchange | | sebi\_turnover\_fees | number | No | Turnover fees by SEBI | | stt | number | No | Security Transaction Tax | | stamp\_duty | number | No | Stamp duty paid on transfer of shares | | sgst | number | No | State GST | | cgst | number | No | Central GST | | igst | number | No | Integrated GST | | other\_transfer\_expenses | number | No | Any other expense relating to the transfer of shares | ### Bonds & Debentures Trade | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | security\_name | string | Yes | Symbol or description of debt/ bond | | quantity | number | Yes | Trading quantity | | buy\_date | number | Yes | Date of Purchase | | buy\_price | number | Yes | Average buy price across all trades | | sell\_date | number | Yes | Date of Sell | | sell\_price | number | Yes | Average buy price across all trades | | brokerage | number | No | Brokerage expense | | clearing\_charges | number | No | Charges charged by clearing house | | exchange\_transaction\_charges | number | No | Transaction charges by exchange | | sebi\_turnover\_fee | number | No | Turnover fees by SEBI | | stamp\_duty | number | No | Stamp duty paid on transfer of shares | | sgst | number | No | State GST | | cgst | number | No | Central GST | | igst | number | No | Integrated GST | | other\_transfer\_expenses | number | No | Any other expense relating to the transfer of shares | #### Interest Table | Param | Type | Required | Description | | - | - | - | - | | description | string | No | Description of interest credit | | date | number | Yes | Date of the interest payment | | amount | number | Yes | Interest amount received | | tax\_withheld | number | Yes | TDS amount deducted on the interest | ## Corporate Actions The enumeration explained below: | Corporate Action | ENUM | | - | - | | Amalgamation | **AMALGAMATION** | | Bonus Issue | **BONUS\_ISSUE** | | Buy Back of Shares | **BUY\_BACK** | | Consolidation of Shares | **CONSOLIDATION** | | Dividend | **DIVIDEND** | | Dividend on Preference Shares | **DIVIDEND** | | Income Distribution (InvIT) | **INCOME\_DISTRIBUTION\_INVIT** | | Income Distribution RITES | **RITES** | | InvIT - Return of Capital | **RETURN\_OF\_CAPITAL\_INVIT** | | Preferential Issue of shares | **PREFERENTIAL\_ISSUE** | | Reduction of Capital | **REDUCTION\_OF\_CAPITAL** | | Right Issue of Equity Shares | **RIGHT\_ISSUE** | | Scheme of Arrangement | **SCHEME\_OF\_ARRANGEMENT** | | Spin Off | **SPIN\_OFF** | | Stock Split | **STOCK\_SPLIT** | | Voluntary Delisting of Shares | **DELISTING** | # Foreign Securities Tradewise P&L Source: https://company-quicko-8c502003.mintlify.app/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl Tradewise P&L helps calculate profit and loss on a trade-level basis ## Overview The Foreign Securities Tradewise P\&L API provides profit and loss calculations on a trade-level basis for completed foreign transactions. This is critical for Quicko to: * Calculate realized capital gains and losses on international investments * Track foreign currency implications and exchange rate impacts * Segregate transactions by holding period (long-term vs short-term) * Generate accurate P\&L statements for foreign investment tax compliance * Track dividend and interest income from foreign securities with TDS deductions * Identify tax harvesting opportunities on international positions ## Query Parameters Your API should accept `from` and `to` query parameters to retrieve P\&L data for a specific date range. ``` GET /securities/foreign/tradewise-pnl?from=YYYY-MM-DD&to=YYYY-MM-DD ``` ## Response Format Your API should return matched trade pairs with complete P\&L calculations organized by security type: ## Stock Tradewise Settlement Sheet ### Stock Tradewise Settlement Table | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | symbol | string | Symbol or description of equity share | | quantity | number | Trading quantity | | buy\_trade\_id | string | Transaction ID of the buy transaction | | buy\_date | number | The date on which the equity stock was bought | | buy\_price | number | Price at which a unit was bought | | sell\_trade\_id | string | Transaction ID of the sell transaction | | sell\_date | number | The date on which the equity stock was sold | | sell\_price | number | Price at which a unit was sold | | currency | string | The 3 letter currency code for the price based on ISO 421 | | transfer\_expenses | number | expense relating to the transfer of stocks | | nature\_of\_settlement | string | The [nature of the settlement](/projects/integration/broker-integration/tradewise_pnl/foreign/foreign_securities_tradewise_pnl#annexure-2-nature-of-settlement) of transaction | | product\_type | string | Indicates whether the order is :delivery , intraday | ### Stock Tradewise Open Sell Table | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | symbol | string | Symbol or description of equity share | | quantity | number | Trading quantity | | sell\_trade\_id | string | Transaction ID of the sell transaction | | sell\_date | number | The date on which the equity stock was sold | | sell\_price | number | Price at which a unit was sold | | currency | string | The 3 letter currency code for the price based on ISO 4217 | | transaction\_type | string | Indicates whether the order is :buy, sell, trade, send, receive | | label | string | Indicates the category of transaction type. Possible values: interest, staking, staking\_reward, lost, mining\_reward, airdrop, donation, fork, gift, payment, other\_income | | last\_traded\_price | number | Last traded price of the security | ### Stock Tradewise Transfer Table | Param | Type | Description | | - | - | - | | isin | string | ISIN is the international security identification number | | symbol | string | Symbol or description of equity share | | quantity | number | Trading quantity | | transfer\_date | number | The date on which the transfer was made | | price | number | Price at which a unit was transferred | | currency | string | The 3 letter currency code for the price based on ISO 4217 | | transfer\_type | string | Indicates whether the transfer is :transfer\_in, transfer\_out | | nature\_of\_settlement | string | The [nature of the settlement](/reference/foreign-securities-tradewise-pl#annexure-2-nature-of-settlement) of transaction | | transfer\_value | number | total value of transfers made | | transfer\_expense | number | expenses incurred while transferring the asset. | ### Dividend Table | Param | Type | Required | Description | | - | - | - | - | | isin | string | No | ISIN is the international security identification number | | scheme\_name | string | Yes | Symbol or description of the fund | | quantity | number | Yes | Trading quantity | | date | number | Yes | Transaction epoch timestamp | | dividend\_amount | number | Yes | Dividend amount received | | currency | string | Yes | The 3 letter currency code for the price based on ISO 4217 | | tax\_withheld | number | Yes | TDS amount deducted on the dividend | ## Interest Income Sheet ### Interest Table | Param | Type | Required | Description | | - | - | - | - | | description | string | No | Description of interest credit | | date | number | Yes | Transaction ID of the particular entry | | amount | number | Yes | Interest amount received | | currency | string | Yes | The 3 letter currency code for the price based on ISO 4217 | | tax\_withheld | number | Yes | TDS amount deducted on the interest | ## Annexures ### Annexure-1 Labels The enumeration is explained below: | Corporate Action | ENUM | | - | - | | Amalgamation | amalgamation | | Bonus Issue | bonus\_issue | | Buy Back of Shares | buy\_back | | Consolidation of Shares | consolidation | | Dividend | dividend | | Dividend on Preference Shares | dividend | | Income Distribution (InvIT) | income\_distribution\_invit | | Income Distribution RITES | income\_distribution\_rites | | InvIT - Return of Capital | return\_of\_capital\_invit | | Preferential Issue of shares | preferential\_issue | | Reduction of Capital | reduction\_of\_capital | | Right Issue of Equity Shares | right\_issue | | Scheme of Arrangement | scheme\_of\_arrangement | | Spin Off | spin\_off | | Stock Split | stock\_split | | Voluntary Delisting of Shares | voluntary\_delisting\_of\_share | | Donation of security | donation | | Transfer of securities in form of gift | gift | | Loss of security | lost | | Transfer of securities | transfer | | Other | other | ### Annexure-2 Nature of Settlement | Nature of Settlement | ENUM | | - | - | | Trade type settlement | trade | | Interest on security | interest | | Asset transferred in | transfer\_in | | Asset transferred out | transfer\_out | | Asset sent as Gift | gift\_send | | Asset received as Gift | gift\_receive | | Asset donated | donation | | Buy back for the security | buy\_back | | Other | other | # Employer Details Source: https://company-quicko-8c502003.mintlify.app/projects/integration/hrms-integration/employer-details/employer_details Employer details data points required for tax filing ## Overview The Employer Details API provides information about the user's employer(s). This includes employer identification details (name, PAN, TAN), contact address, and employer category. This data is essential for Quicko to: * Reconcile Form 16 (salary certificate) information * Prepare accurate tax returns (ITR) with employer details * Validate salary income sources and ensure tax compliance * Match employer data across multiple documents for verification ## Response Format Your API should return employer information with the following structure: ## Employer Details | Serial No. (Field) | Param | Type | Required | Description | | - | - | - | - | - | | 1. | Name | string | Yes | Name of the employer | | 2. | TAN | string | Yes | Tax Deduction and Collection Account Number | | 3. | PAN | string | Yes | Permanent Account Number of the employer | | 4. | Address | string | Yes | Address of the workplace of the employer | | 5. | City | string | Yes | Address of the workplace of the employer (City) | | 6. | State | string | Yes | Address of the workplace of the employer (State)enums: State outside India, Assam, Gujarat, etc. | | 7. | Postal Code | number | Yes | Address of the workplace of the employer (Postal Code) | | 8. | Country | string | Yes | Country where employer belongs | ## Employer Address | Serial No. (Field) | Param | Type | Required | Description | | - | - | - | - | - | | 1. | Address | string | Yes | Address of the workplace of the employer | | 2. | City | string | Yes | Address of the workplace of the employer (City) | | 3. | State | string | Yes | Address of the workplace of the employer (State)enums: State outside India, Assam, Gujarat, etc. | | 4. | Postal Code | number | Yes | Address of the workplace of the employer (Postal Code) | | 5. | Country | string | Yes | Country where employer belongs | # Introduction Source: https://company-quicko-8c502003.mintlify.app/projects/integration/hrms-integration/index HRMS Integration with Quicko for tax compliance Salaried Individuals have to file Income Tax Return form ITR-1. Form-16 TDS Certificate has details including employer name, salary breakdown, deductions and tax credits necessary to prepare ITR. Quicko is India's leading tax planning, preparation and filing platform. Customers can connect their Broker, HRMS, Bank and Investment apps to Quicko and import data into their income tax returns with ease. There were 7 crore ITRs filed in FY 22 of which 3.5 crore were ITR-1s. HRMS platforms can easily integrate with Quicko to simplify tax compliance for employees. This documentation explains how HRMS platforms can integrate with Quicko using APIs. ## Integration Journey Most modern HRMS platforms help employers with TDS compliances. Employers must file Form 24Q for TDS on Salary. Q4 filing also includes Schedule Salary Details which forms the basis of Form 16. Employees can easily file their tax returns by sourcing Salary details information from their HRMS platforms. Basic Employer details must also be filled in as they are the deductor. The following diagram shows how this journey would work. User Logs into Quicko User explores Apps (includes Broker, HRMS, Bank and Investment Apps) User selects HRMS app If the app is not connected * User gets redirected to the HRMS OAuth app * OAuth-Redirection Based * User logs into his/her account and grants access to Quicko Once connected, user can import salary and employer details using API integrations Quicko prepares tax return by mapping salary details to income tax return forms * Refer Salary Details for salary schedule data points * Salary Details API * Refer Employer Details for basic employer data points * Employer Details API User files return without any hassle # Salary Details Source: https://company-quicko-8c502003.mintlify.app/projects/integration/hrms-integration/salary-details/salary_details Schedule Salary Details data points for Form 24Q TDS Return ## Overview The Salary Details API provides comprehensive salary and income information for a specific financial year. This includes gross salary, allowances, exemptions, deductions (80C, 80D, 80E, etc.), perquisites, and TDS deducted. This data is essential for Quicko to: * Reconcile Form 16 (salary certificate) issued by employers * Validate TDS deduction and match with income tax filings * Calculate income under various sections for tax compliance * Prepare accurate salary schedules for income tax returns (ITR) * Verify eligibility for tax deductions and exemptions ## Query Parameters Your API should accept a `financial_year` query parameter to retrieve salary details for a specific financial year. ``` GET /salary-details?financial_year=YYYY-YY ``` ## Response Format Your API should return salary details for the specified financial year with the following data points: Employers file Form 24Q for TDS on Salary including Schedule Salary Details which forms the basis of Form 16. Schedule Salary details must be furnished along with Form 24Q TDS Return for Q4 filing. Following are the data points entailed in Schedule Salary Details. HRMS platform must avail the Salary Details for successful integration. ## Salary Schedule Data points | Serial No. (Field) | Param | Type | Required | Description | | - | - | - | - | - | | 1. | Employee PAN | String | Yes | Permanent Account Number of the employee ('PANAPPLIED' or 'PANNOTAVBL' in case of no valid PAN) | | 2. | PAN Ref. No. | String | Yes | Reference number in case of PAN applied | | 3. | Name of Employee | String | Yes | Mention the Name of the employee | | 4. | Period of Employment From - Date | Date | Yes | Date from which employed with the current Employer (DDMMYYYY) | | 5. | Period of Employment To - Date | Date | Yes | Date to which employed with the current Employer (DDMMYYYY) | | 6. | Total deduction under section 16(ii) | Number | Yes | Entertainment Allowance received | | 7. | Total deduction under section 16(iii) | Number | Yes | Professional tax paid | | 8. | Income (including admissible loss from house property) under any head other than income under the head "salaries" offered for TDS \[section 192 (2B)] | Number | Yes | Any other Income except salary Income | | 9. | Deduction in respect of life insurance premia, contributions to provident fund etc. (section 80C) (Gross Amount) | Number | Yes | Actual amount of contribution made to Life Insurance schemes | | 10. | Deduction in respect of contribution to certain pension funds (section 80CCC) (Gross Amount) | Number | Yes | Actual amount of contribution made to any pension funds | | 11. | Deduction in respect of contribution by taxpayer to notified pension scheme \[section 80CCD(1)] (Gross Amount) | Number | Yes | Actual amount of contribution made to National Pension Fund | | 12. | Deduction in respect of amount paid or deposited under notified pension scheme \[section 80CCD(1B)] (Gross Amount) | Number | Yes | Actual amount of contribution made to New Pension Scheme account regardless of contribution under section 80CCD(1) | | 13. | Deduction in respect of contribution by employer to notified pension scheme \[section 80CCD(2)] (Gross Amount) | Number | Yes | Actual amount of contribution made by employer to notified Pension Scheme under section 80CCD(2) | | 14. | Deduction in respect of health insurance premia \[section 80D] (Gross Amount) | Number | Yes | Actual amount of contribution to medical insurance premium, medical expenditure, preventive health checkup | | 15. | Deduction in respect of interest on loan taken for higher education (section 80E) (Gross Amount) | Number | Yes | Actual amount of Interest paid on higher education loan | | 16. | Total deduction in respect of donations to certain funds charitable institutions (section 80G) (Gross Amount) | Number | Yes | Actual amount of donations made to certain relief funds and charitable institutions | | 17. | Deduction in respect of interest on deposits in savings account (section 80TTA) (Gross Amount) | Number | Yes | Actual amount of Interest received from Savings account | | 18. | Deduction in respect of interest on deposits in savings account (section 80TTB) (Gross Amount) | Number | Yes | Actual amount of Interest received from Savings account (Senior Citizen) | | 19. | Deduction in respect of maintenance including medical treatment of a dependent who is a person with disability (section 80DD) (Gross Amount) | Number | Yes | Actual amount of expenses incurred on the medical treatment of differently abled dependents | | 20. | Deduction in respect of interest on loan taken for residential house property (section 80EE) (Gross Amount) | Number | Yes | Actual amount of interest paid on a home loan taken by a first-time homeowner | | 21. | Deduction in respect of interest on loan taken for certain house property (section 80EEA) (Gross Amount) | Number | Yes | Actual amount of interest paid on a home loan taken by a first-time homeowner under Affordable Housing | | 22. | Deduction in respect of rents paid (section 80GG) (Gross Amount) | Number | Yes | Actual amount of Rent paid for furnished or unfurnished accommodation | | 23. | Deduction in respect of contributions given by any person to political parties (section 80GGC) (Gross Amount) | Number | Yes | Donations to a political party or candidate | | 24. | Deduction in case of a person with disability (section 80U) (Gross Amount) | Number | Yes | Expenses incurred on the medical treatment of disabled | | 25. | Income Tax Relief u/s 89 when salary etc is paid in arrear or advance | Number | No | Salary paid in arrear or advance and hence government gives relief for change in slab rates | | 26. | Total Amount of tax deducted at source by the current employer for the whole year | Number | Yes | TDS deducted by the current employer for the employment period in the whole year | | 27. | PAN of landlord | String | No | PAN of landlord (subject to when yearly rent paid exceeds Rs. 1 lakh) | | 28. | Name of landlord | String | No | Name of Landlord | | 29. | In case of deduction of interest under the head income from house property - PAN of lender | String | No | PAN of lender | | 30. | In case of deduction of interest under the head income from house property - Name of lender | String | No | Name of Lender | | 31. | Gross Salary as per provisions contained in sec.17(1) | Number | Yes | Includes Basic salary, DA, conveyance allowance, HRA, etc. | | 32. | Value of perquisites \[section 17(2)]\(as per Form No.12BA) | Number | Yes | Includes accommodation, free travel, free meal, holiday expense, stock options, etc. | | 33. | Profits in lieu of salary \[section 17(3)]\(as per Form No.12BA) | Number | Yes | Includes terminal compensation, keyman Insurance policy, unrecognized PF, etc. | | 34. | Travel concession or assistance \[section 10(5)] | Number | Yes | LTA (Leave Travel Allowance) is paid by employers to their employees when they are on leave and traveling either alone or with family within India | | 35. | Death-cum-retirement gratuity \[section 10(10)] | Number | Yes | Gratuity is received as a lump sum amount for at least completing 5 years | | 36. | Commuted value of pension \[section 10(10A)] | Number | Yes | Pension value received in advance as a lump sum payment | | 37. | Cash equivalent of leave salary encashment\[section 10(10AA)] | Number | Yes | Income from cashing out unused leaves | | 38. | House rent allowance \[section 10(13A)] | Number | Yes | Allowance received to cover the rent expenses for accommodation | | 39. | Amount of any other exemption under section 10 | Number | Yes | Any other exemption received | | 40. | Income under the head other sources offered for TDS \[section 192 (2B)] | Number | Yes | Income from Other Sources | | 41. | Whether opting for taxation u/s 115BAC | String | No | Opt for taxation under the new regime | # Introduction Source: https://company-quicko-8c502003.mintlify.app/projects/integration/index # Overview This **Integration Documentation** is intended for partners that want to **integrate with Quicko** to simplify tax compliances for their customers. The integration enables Quicko to pull structured data from partners—such as brokers, payroll providers, and banks—so it can be used for tax computation, reporting, and filing compliance. *** ## What this documentation covers This documentation is organized into focused sections, each addressing a specific integration capability. OAuth app for users to securely authenticate and grant necessary claims to Quicko to access APIs. Retrieve authenticated user profile and identity information. Fetch holdings, trades, and financial instruments data from brokers. Fetch employer, employee and salary data from payroll systems. Retrieve bank account details and transaction statements. *** ## Integration flow The following steps outline the typical process for integrating your system with Quicko, regardless of whether you are a bank, broker, HRMS provider, or another platform. Identify the nature of your integration (for example, bank, broker, or HRMS) and review the data requirements defined in the relevant integration section.\ This helps determine the APIs, payload structures, and compliance data expected by Quicko. Build the required APIs and data pipelines based on the integration documentation.\ Ensure request formats, authentication mechanisms, and validations match the specifications provided. Provide the implemented API endpoints and required credentials to the Quicko team so the integration can be coded and deployed. Validate data exchange in the testing environment to ensure accuracy, completeness, and compliance with expected workflows. Once testing is complete and approved, move the integration to production and begin referring customers to Quicko. *** # API Based OAuth Source: https://company-quicko-8c502003.mintlify.app/projects/integration/oauth/api_based/api_based API-based OAuth workflow that allows access without any redirection. ## API Based Workflow The API-based workflow is a two-step process: Generate OTP for users using the Generate OTP endpoint. Users will obtain a One Time Password (OTP) on their registered email address with a validity of 10 minutes. | HTTP Method | Resource | Description | | - | - | - | | GET | `{{your_oauth_app_authenticate}}/otp?username={username}` | API accepts username and sends OTP to registered email. | Provide the OTP and username (user's email) to verify the OTP. Obtain the `access_token` and use that with all subsequent requests. | HTTP Method | Resource | Description | | - | - | - | | POST | `{{your_oauth_app_authenticate}}/otp` | API verifies the OTP and returns the access token. | ### Step 2 After obtaining the `access_token`, use it for all subsequent requests to access protected resources. ### Additional Information * The OTP is valid for 10 minutes. * Ensure to handle errors appropriately, such as invalid OTP or expired OTP. *** # Redirection Based OAuth Source: https://company-quicko-8c502003.mintlify.app/projects/integration/oauth/redirection_based/redirection_based Redirection based OAuth journeys offer secure access to third-party apps such as Quicko, just like Google OAuth app can be used to get access to users google profile, contacts, calendar, emails etc. Following steps explain a standard OAuth journey: User navigates to your OAuth Login Page Upon successful login control is passed back with a `request_token` to the registered redirect URL Quicko exchanges short lived `request_token` with a long lived `access_token` Quicko can now import data using APIs provided by you using `access_token` **Note** An optional redirect param should be supported by your OAuth login endpoint, which will be used to navigate the user after a successful login attempt. Redirect URL request parameter must be Base64 encoded, eg: `https://join.quicko.com` will be used like: ``` {{your_oauth_app_url}}/login?api_key={api_key}&redirect=aHR0cHM6Ly9qb2luLnF1aWNrby5jb20= ``` ## Authorize Endpoint The authorize endpoint is used to exchange a request token for a resource owner's access token. The short-lived request token obtained from the OAuth login page ## API Reference | HTTP Method | Resource | Description | | - | - | - | | GET | `/oauth/authorize?request_token={{request_token}}` | Requires Request Token | # User Details Source: https://company-quicko-8c502003.mintlify.app/projects/integration/profile/user_details User Details API is required to establish the identity of the user ## User Details Datapoints The response data points are explained below: | Param | Type | Required | Description | | - | - | - | - | | client\_id | string | Yes | Unique identifier of user in source system | | email | string | Yes | Verified Customer Email | | PAN | string | Yes | Verified Tax Payer Identifier | | first\_name | string | No | First name of the user | | last\_name | string | No | Last name of the user | | dob | string | No | Date of Birth | | gender | string | No | Gender of the user | | aadhaar | string | No | Aadhar number of the user | | mobile | string | No | Mobile number of the user | # Check Residential Status Source: https://company-quicko-8c502003.mintlify.app/projects/tools/directory/check-residential-status Check how your stay in India determines your Resident, NRI, or RNOR tax status. Check Residential Status tool helps you determine whether an individual qualifies as Resident, Non-Resident, or Resident but Not Ordinarily Resident (RNOR) for Indian income tax purposes based on their physical presence in India. ## Features Calculates residential status based on stay duration and tax residency rules. Considers current and previous years' stay for comprehensive assessment. Identifies Resident but Not Ordinarily Resident status. Provides reasoning behind the determined residential status. ## Integration ### Web (iframe) ```html theme={null} ``` With customization: ```html theme={null} ``` ### Mobile (WebView) ```swift theme={null} import WebKit let theme: [String: Any] = [ "mode": "light", "seed": "#006AD4" ] if let jsonData = try? JSONSerialization.data(withJSONObject: theme), let base64Theme = jsonData.base64EncodedString() .addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) { let toolUrl = "https://tools.quicko.com/check-residential-status?theme=\(base64Theme)" webView.load(URLRequest(url: URL(string: toolUrl)!)) } ``` ```kotlin theme={null} import android.util.Base64 import org.json.JSONObject val theme = JSONObject().apply { put("mode", "light") put("seed", "#006AD4") } val base64Theme = Base64.encodeToString( theme.toString().toByteArray(Charsets.UTF_8), Base64.NO_WRAP ) val toolUrl = "https://tools.quicko.com/check-residential-status?theme=$base64Theme" webView.loadUrl(toolUrl) ``` ```dart theme={null} import 'dart:convert'; final theme = {'mode': 'light', 'seed': '#006AD4'}; final base64Theme = base64Encode(utf8.encode(jsonEncode(theme))); final toolUrl = 'https://tools.quicko.com/check-residential-status?theme=$base64Theme'; controller.loadRequest(Uri.parse(toolUrl)); ``` ```jsx theme={null} import { Buffer } from 'buffer'; const theme = { mode: 'light', seed: '#006AD4' }; const base64Theme = Buffer.from(JSON.stringify(theme)).toString('base64'); const toolUrl = `https://tools.quicko.com/check-residential-status?theme=${base64Theme}`; ``` *** ## Residential Status Rules The tool follows Income Tax Act provisions: An individual is a Resident if they satisfy any one of the following conditions: * Present in India for 182 days or more during the FY * Present in India for 60 days or more during the FY AND 365 days or more in preceding 4 years An individual who does not satisfy the conditions for being a Resident is a Non-Resident. A Resident qualifies as RNOR if they satisfy any one condition: * Non-resident in 9 out of 10 preceding years * Present in India for 729 days or less in preceding 7 years *** ## Demo ``` With customization: ```html theme={null} ``` ### Mobile (WebView) ```swift theme={null} import WebKit let theme: [String: Any] = [ "mode": "light", "seed": "#006AD4" ] if let jsonData = try? JSONSerialization.data(withJSONObject: theme), let base64Theme = jsonData.base64EncodedString() .addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) { let toolUrl = "https://tools.quicko.com/hra-calculator?theme=\(base64Theme)" webView.load(URLRequest(url: URL(string: toolUrl)!)) } ``` ```kotlin theme={null} import android.util.Base64 import org.json.JSONObject val theme = JSONObject().apply { put("mode", "light") put("seed", "#006AD4") } val base64Theme = Base64.encodeToString( theme.toString().toByteArray(Charsets.UTF_8), Base64.NO_WRAP ) val toolUrl = "https://tools.quicko.com/hra-calculator?theme=$base64Theme" webView.loadUrl(toolUrl) ``` ```dart theme={null} import 'dart:convert'; final theme = {'mode': 'light', 'seed': '#006AD4'}; final base64Theme = base64Encode(utf8.encode(jsonEncode(theme))); final toolUrl = 'https://tools.quicko.com/hra-calculator?theme=$base64Theme'; controller.loadRequest(Uri.parse(toolUrl)); ``` ```jsx theme={null} import { Buffer } from 'buffer'; const theme = { mode: 'light', seed: '#006AD4' }; const base64Theme = Buffer.from(JSON.stringify(theme)).toString('base64'); const toolUrl = `https://tools.quicko.com/hra-calculator?theme=${base64Theme}`; ``` ## Input Fields The HRA Calculator collects the following information: | Field | Description | Required | | - | - | - | | Basic Salary | Basic salary amount | Yes | | HRA Received | HRA component in salary | Yes | | Rent Paid | Rent paid for accommodation | Yes | | Metro City | Whether the city is a metro (Mumbai, Delhi, Chennai, Kolkata) | Yes | ## Output The calculator displays: * **Exempt HRA Amount** – The tax-exempt portion of HRA * **Taxable HRA Amount** – The portion that will be taxed * **Breakdown** – All three calculation components for transparency *** ## Use Cases Enhance tax-related articles and guides by embedding an interactive HRA calculator. Pre-calculate HRA exemption to streamline the tax filing process. Provide employees with a tool to understand their salary components. *** ## Demo ``` With customization: ```html theme={null} ``` ### Mobile (WebView) ```swift theme={null} import WebKit let theme: [String: Any] = [ "mode": "light", "seed": "#006AD4" ] if let jsonData = try? JSONSerialization.data(withJSONObject: theme), let base64Theme = jsonData.base64EncodedString() .addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) { let toolUrl = "https://tools.quicko.com/tds-calculator?theme=\(base64Theme)" webView.load(URLRequest(url: URL(string: toolUrl)!)) } ``` ```kotlin theme={null} import android.util.Base64 import org.json.JSONObject val theme = JSONObject().apply { put("mode", "light") put("seed", "#006AD4") } val base64Theme = Base64.encodeToString( theme.toString().toByteArray(Charsets.UTF_8), Base64.NO_WRAP ) val toolUrl = "https://tools.quicko.com/tds-calculator?theme=$base64Theme" webView.loadUrl(toolUrl) ``` ```dart theme={null} import 'dart:convert'; final theme = {'mode': 'light', 'seed': '#006AD4'}; final base64Theme = base64Encode(utf8.encode(jsonEncode(theme))); final toolUrl = 'https://tools.quicko.com/tds-calculator?theme=$base64Theme'; controller.loadRequest(Uri.parse(toolUrl)); ``` ```jsx theme={null} import { Buffer } from 'buffer'; const theme = { mode: 'light', seed: '#006AD4' }; const base64Theme = Buffer.from(JSON.stringify(theme)).toString('base64'); const toolUrl = `https://tools.quicko.com/tds-calculator?theme=${base64Theme}`; ``` ## Input Fields The TDS Calculator collects the following information: | Field | Description | Required | | - | - | - | | Recipient Type | Individual / HUF / Sole Proprietor or Others | Yes | | Residential Status | Resident or Non-Resident | Yes | | PAN Available | Whether recipient PAN is available | Yes | | Nature of Payment | Section & nature of payment | Yes | | Amount of Payment | Gross payment amount | Yes | ## Output The calculator displays: * **TDS Rate** – Applicable rate based on section and conditions * **TDS Amount** – Tax deducted at source * **Amount Payable** – Net amount after TDS deduction * **TDS Rule** – Explanation of applicable threshold and rate *** ## Use Cases Enhance tax-related articles and guides by embedding an interactive TDS calculator. Help users calculate accurate TDS before making payments. Ensure correct TDS deduction for employee and vendor payments. *** ## Demo ``` ## Integration Steps Select the tool you want to embed from our [directory](/projects/tools/directory/index). Each tool has a unique URL endpoint. Customize the tool's appearance by passing [theme](/projects/tools/options/index) as a JSON object for mode and seed color. Insert the iframe code into your webpage at the desired location. Verify the tool displays correctly across different screen sizes and browsers, then deploy. ## Passing Theme You can customize the tool's appearance by passing an `theme` JSON object as a URL-encoded query parameter: ```javascript theme={null} const theme = { mode: "dark", seed: "#006AD4" }; const encodedOptions = encodeURIComponent(JSON.stringify(theme)); const iframeSrc = `https://tools.quicko.com/hra-calculator?theme=${encodedOptions}`; ``` ```html theme={null} ``` ### Theme Object Structure ```json theme={null} "theme": { "mode": "light", "seed": "#006AD4" } ``` | Property | Description | Values | | - | - | - | | `theme.mode` | Theme mode | `light`, `dark` | | `theme.seed` | Seed color (hex with #) | e.g., `#006AD4` | Learn about all available customization options. ## Responsive Embedding For responsive designs, wrap the iframe in a container with appropriate CSS: ```html theme={null}
``` ## Best Practices Ensure the iframe has enough height to display the tool without internal scrolling. Include `allow="clipboard-write"` for tools that let users copy results. Use the seed color option to match the tool's accent color with your website's branding. Verify the embedded tool works well on mobile viewports. *** ## Next Steps Explore all tools available for embedding on your website. # License Source: https://company-quicko-8c502003.mintlify.app/projects/tools/license Quicko Tools are free to use with proper attribution to Quicko. Quicko Tools are **free to use** for both commercial and non-commercial purposes. There are no usage fees, API limits, or hidden costs associated with embedding our tools into your platform. ## Attribution Requirement While Quicko Tools are free, **attribution is required**. We believe in the philosophy of giving credit where it's due. By providing proper attribution: * You help others discover these tools * You support the ecosystem of free, high-quality tax utilities * You acknowledge the expertise and effort behind building these tools > \[!IMPORTANT] > Attribution is not just recommended—it is **required** when using Quicko Tools. The attribution must be visible to end users. ## Attribution Guidelines When embedding Quicko Tools, you must include a visible attribution that links back to Quicko. The attribution should be: 1. **Visible** – Easily noticeable to users 2. **Proximate** – Near the embedded tool 3. **Linked** – Hyperlinked to `https://quicko.com` ## Attribution Snippets Add attribution near your embedded tool. Here are ready-to-use snippets: ```html theme={null}
Powered by Quicko
``` ```jsx theme={null}
window.open("https://quicko.com", "_blank", "noopener,noreferrer")} style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: '8px', height: '56px', padding: '0 8px', borderTop: '1px solid #c6c5d0', backgroundColor: '#f6f7f8', cursor: 'pointer' }} > Powered by Quicko
``` ```markdown theme={null} *Powered by [Quicko](https://quicko.com)* ``` ### Complete Integration Example Here's how to embed a tool with proper attribution: ```html theme={null}
Powered by Quicko
``` ## Why We Choose This Model We believe tax-related utilities should be accessible to all. By offering free tools, we empower developers, businesses, and end-users to make informed tax decisions. Attribution creates awareness and helps build a community of developers and partners who contribute to the ecosystem of tax utilities. When you attribute Quicko, you help us grow organically. This allows us to continue developing and maintaining high-quality, free tools for everyone. *** ## Terms Summary | Aspect | Terms | | - | - | | **Usage** | Free for commercial and non-commercial use | | **Attribution** | Required and must be visible to end users | | **Modifications** | Tools must be embedded as-is; no modifications | | **Liability** | Quicko provides tools "as-is" without warranties | For complete terms and conditions, please refer to our [Terms of Service](https://quicko.com/terms). *** ## Questions? Have questions about usage or attribution? Reach out to our team. # Theme Source: https://company-quicko-8c502003.mintlify.app/projects/tools/options/index Customize Quicko Tools appearance with theme mode and seed color options based on design. Quicko Tools support customization to match your platform's branding. You pass an `theme` object that contains theme configuration to generate a complete color scheme. ## Structure The `theme` object contains the following properties: ```json theme={null} { "mode": "light", "seed": "#2962FF" } ``` | Property | Description | Default | | - | - | - | | `$.theme.mode` | Theme mode (`light` or `dark`) | `light` | | `$.theme.seed` | Seed color for theme generation (hex with `#`) | `#2962FF` | ## Theme Mode Control whether the tool displays in light or dark mode: Clean, bright interface suitable for light-themed applications. Dark interface that reduces eye strain and suits dark-themed applications. ```json theme={null} "theme": { "mode": "dark" } ``` ```swift theme={null} let theme: [String: Any] = [ "mode": "dark" ] ``` ```kotlin theme={null} val theme = JSONObject().apply { put("mode", "dark") } ``` ## Seed Color Provide a seed color and Quicko Tools will generate a complete color scheme. This ensures harmonious colors across the entire tool interface. ```json theme={null} "theme": { "mode": "light", "seed": "#2962FF" } ``` ```swift theme={null} let theme: [String: Any] = [ "mode": "light", "seed": "#2962FF" ] ``` ```kotlin theme={null} val theme = JSONObject().apply { put("mode", "light") put("seed", "#2962FF") } ``` ## Best Practices Pass your brand's primary color as the seed. It will generate complementary colors automatically. Detect the user's system theme preference and set the mode accordingly for a consistent experience. Always test your integration in both light and dark modes to ensure readability and visual appeal. Choose seed colors with sufficient contrast. Very light or very dark colors may produce themes with accessibility issues. ## Example Themes Here are some example seed color configurations: | Brand Color | Hex Code | Usage | | - | - | - | | Quicko Blue | `#2962FF` | Default Quicko branding | | Forest Green | `#2E7D32` | Eco-friendly or financial apps | | Deep Purple | `#673AB7` | Creative or premium apps | | Orange | `#F57C00` | Energetic or action-oriented apps | *** ## Next Steps Learn how to pass options when embedding tools. Learn how to configure options in the mobile SDK.