> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer guidelines

> Step-by-step guide to build, test and release your integration.

## 1. Discover our available APIs and endpoints

Go through our [API Reference](https://docs.qonto.com/api-reference/business-api/introduction/overview.md) to identify the API(s) and endpoints you will need for your use case.

## 2. Sign up to the Developer Portal

By signing up to the [Developer Portal](https://developers.qonto.com/) and creating an app, you'll be able to get all the authentication credentials you need to access the Sandbox environment (cf. demo below).

> [!NOTE]
>
> If you sign up with your **email address** (without a Qonto account), your organization will go through a review before your account is activated. This process takes around **48 hours** on average. You will receive a confirmation email once your account is approved.
>
> If you sign up using **Sign in with Qonto**, no additional review is needed since it is already handled through your Qonto account.

> [!NOTE]
>
> Are you interested in seeing how Qonto Embed could supercharge your platform with embedded financial services? Check out our [sample app](https://docs.qonto.com/partnerships/embed/sample-app.md).

[Qonto Developers - Production access](https://demo.arcade.software/5vCsPC8oSQnuGlXKf9FQ?embed\&embed_mobile=tab\&embed_desktop=inline\&show_copy_link=true)

### Selecting your use case

When creating your application, you select a **use case** that shapes which scopes are available and what approval process is required. Use cases only apply to **OAuth 2.0** and have no effect on API key authentication.

> **Automate your business operations**
>
> **Qonto account owners** automating their own workflows (accounting sync, internal reporting, reconciliation) using the **Business API**.
>
> Access with:
>
> * [OAuth 2.0](https://docs.qonto.com/guides/authentication/oauth-flow.md) if you need to perform sensitive actions (cf. the [endpoints access table](https://docs.qonto.com/api-reference/business-api/introduction/authentication/scopes.md#endpoints-access) to identify if you need to use an endpoint which is only accessible through OAuth) OR if you want to restrict the scopes accessible with your authentication credentials to a specific list of scopes;
>
> * Your [API key](https://docs.qonto.com/guides/authentication/api-key.md) otherwise.
>
> > [!TIP]
> >
> > The API key authentication method is much more simple to implement than OAuth 2.0.
>
> > [!NOTE]
> >
> > This use case requires **no validation from Qonto**, for either authentication method. You can start building right away.

> **Connect your customers' Qonto accounts to your platform**
>
> **Third-party platforms** connecting to Qonto on behalf of their users (ERPs, accounting software, financial tools).
>
> Access with: [OAuth 2.0](https://docs.qonto.com/guides/authentication/oauth-flow.md).
>
> > [!WARNING]
> >
> > This use case **requires validation from Qonto** if you are requesting [sensitive scopes](https://docs.qonto.com/api-reference/business-api/introduction/authentication/scopes.md#available-scopes).

> **Embed Qonto business features into your platform**
>
> **Partners embedding Qonto** natively into their product.
>
> * To create Qonto business accounts (and eventually companies) for your customers, use the **Onboarding API**;
>
> * To operate those accounts directly from your platform, use the **Business API** (with [OAuth 2.0](https://docs.qonto.com/guides/authentication/oauth-flow.md)).
>
> > [!WARNING]
> >
> > Requires **signing a partnership contract** with Qonto before going live.

> **Streamline company creation**
>
> **Platforms** using the **Onboarding API** to create Qonto accounts and companies (digital KYB, KYC and capital deposit) programmatically.
>
> > [!WARNING]
> >
> > Requires **signing an ORIAS mandate** (France only) and a **partnership contract** with Qonto before going live.

> [!NOTE]
>
> An application's use case cannot be changed after creation. If you selected the wrong use case, create a new application. You will receive a new `client_id` and `client_secret`, but the integration structure remains identical.

## 3. Set up the Sandbox environment

Before making your first API calls, we strongly recommend you set up the Sandbox environment to play with dummy data and check if the API responses are the expected ones.

> [!NOTE]
>
> In the following steps, if any verification screen is prompted, please fill `123456`.

> **Log in to the Sandbox web app**
>
> 1. From the [Toolkit](https://developers.qonto.com/toolkit/), click on "Sandbox web app". ![sandbox-web-app-login-screen.png ](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/sandbox-web-app-login-screen.png)
>
>    > [!WARNING]
>    >
>    > Please, do not click on “Open an account”.
>
> 2. Log in with the credentials available in the [Developer Portal](https://developers.qonto.com/authentication/). ![Developer Portal - Sandbox GUI access](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/Developer+Portal+-+Sandbox+GUI+access.png)
>
>    > [!WARNING]
>    >
>    > Please, do not change this password and the preferred language (english) since it’s a shared account.
>
> 3. If the verification screen is prompted, fill `123456`.
>
> > [!TIP]
> >
> > You have access to Qonto Sandbox web app!

> **Create my own user (optional)**
>
> > [!NOTE]
> >
> > **Do I need to create my own user?**
> >
> > The user associated to [owner@qonto.eu](mailto:owner@qonto.eu) is a shared user.
> >
> > If you need privacy concerning your testing data and/or more autonomy, then you should create your own user.
>
> 1. From the [Toolkit](https://developers.qonto.com/toolkit/), click on "Sandbox web app".
>
> 2. Log in with the credentials available in the [Developer Portal](https://developers.qonto.com/authentication/). ![Developer Portal - Sandbox GUI access](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/Developer+Portal+-+Sandbox+GUI+access.png)
>
> 3. For any organization, click on the “User management” tab.
>
> 4. Click on the “Invite team member” button. ![sandbox-web-app-invite-team-member.png ](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/sandbox-web-app-invite-team-member.png)
>
> 5. Create a new user.
>
> 6. If the verification screen is prompted, fill `123456`.
>
> 7. From the [Toolkit](https://developers.qonto.com/toolkit/), click on "Mailcatcher".
>
> 8. Find the email sent to the email address of your new user.
>
> 9. Click on “Accept invitation” in the email and go through the self-onboarding process.
>
> > [!TIP]
> >
> > Your new user is activated!
> >
> > N.B. : You don’t need to verify your identity.

> **Create my own organization (optional)**
>
> > [!NOTE]
> >
> > **Do I need my own organization?**
> >
> > The organizations associated to [owner@qonto.eu](mailto:owner@qonto.eu) are shared organizations.
> >
> > If you need privacy concerning your testing data and/or more autonomy, then you should create your own organization.
>
> 1. Create your own user (cf. previous step).
>
> 2. From the [Toolkit](https://developers.qonto.com/toolkit/), click on "QA tool".
>
> 3. Click on "[Create Organization](https://qa-sandbox.staging.qonto.co/create_organizations/new)".
>
> 4. Fill the following fields:
>
>    ![qa-tool-create-organization-form.png](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/qa-tool-create-organization-form.png)
>
>    * `Owner` : the email address of your new user.
>    * `Price plan code`  : choose your plan depending on the functionalities you need to test; indeed, some functionalities are only available for given plans (cf. [Qonto pricing for more details](https://qonto.com/en/pricing)).
>    * `Organization name`
>    * `Balance amount` : it will be the amount available in your test bank account, `100000` € will be a good start!
>
> 5. Submit the form.
>
>    ![qa-tool-create-organization-success.png](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/qa-tool-create-organization-success.png)
>
> > [!TIP]
> >
> > From the [Toolkit](https://developers.qonto.com/toolkit/), click on "Sandbox web app". Your new organization is created!

## 4. Make your first API call

> [!NOTE]
>
> To call the Sandbox environment, you should use Sandbox base URLs not Production base URLs.

> **Set up Postman (optional)**
>
> 1. Fork our Postman collections in your workspace:
>
> * [Business API Collection](https://www.postman.com/qontoteam/qonto-public-api/collection/52766385-49b1c98f-f4a6-44fa-9f81-7a9d00b79d4d?creator=52766385);
>
> * [Onboarding API Collection](https://www.postman.com/qontoteam/qonto-public-api/collection/52766385-6861988a-519a-4e80-9006-c729360a6713?creator=52766385).
>
> 2. Fork our Postman environments in your workspace:
>
> * [Sandbox environment](https://www.postman.com/qontoteam/qonto-public-api/environment/33800365-54d105d1-bebe-4e32-b08a-f78cbf2e4cc6?creator=52766385);
>
> * [Production environment](https://www.postman.com/qontoteam/qonto-public-api/environment/33800365-22049dbd-e7ea-401f-95bf-430751d9e5e0?creator=52766385).
>
> 3. On your workspace, select an environment before making any API call.
>
>    ![postman-environment-to-select.png](https://qonto-assets.s3.eu-central-1.amazonaws.com/api-doc/postman-environment-to-select.png)
>
> > [!TIP]
> >
> > Our collections are automatically kept in sync with the latest API spec. Enable Postman's **Watch** feature on your forked collection — or use **Pull Changes** — to get notified and pull updates as they are published.
>
> > [!TIP]
> >
> > Your Postman workspace is set up!

> **Authenticate**
>
> > [!NOTE]
> >
> > You'll find all the authentication credentials you need in the [Developer Portal](https://developers.qonto.com/).
>
> > [!WARNING]
> >
> > Don't forget to include the `X-Qonto-Staging-Token` header in your API calls to the Sandbox environment. See [Accessing the Sandbox environment](https://docs.qonto.com/guides/developer-portal/sandbox-access.md) for the full explanation, and for how to bypass the OneLogin gate from a browser when you need to open a Sandbox URL.
>
> **Business API**
>
> If you need to authenticate through:
>
> * **OAuth 2.0** (customers using sensitive endpoints and partners) 👉 follow [those steps](https://docs.qonto.com/guides/authentication/oauth-flow.md);
> * your **API Key** (customers only) 👉 follow [those steps](https://docs.qonto.com/guides/authentication/api-key.md).
>
> **Onboarding API**
>
> Follow [those steps](https://docs.qonto.com/api-reference/onboarding-api/introduction/authentication.md).

## 5. Build your integration

> [!TIP]
>
> **Not a developer?** Use [Make](https://www.make.com/en/integrations/qonto) or [Zapier](https://zapier.com/apps/qonto/integrations) (no-code tools) to build your integration!

> **[Not sure how to start building?](https://docs.qonto.com/guides/use-cases/index.md)**
>
> Check out our step-by-step use case guides to see how common integrations are built end-to-end. Each guide walks through real scenarios with full code examples in Python and Node.js, including how to send SEPA transfers, sync invoices and attachments, bulk upload supplier invoices, generate Factur-X PDFs, and sync transactions.

## 6. Release your integration

All the API operations can be replicated from the Sandbox to the Production environment. Before getting your production credentials, [verify what your use case requires](https://docs.qonto.com/guides/developer-portal/developer-guidelines.md#selecting-your-use-case).

### Sensitive scopes

Some scopes are classified as **sensitive** because they cover operations regulated under PSD2 (Payment Services Directive 2). Using a sensitive scope means your application can initiate payments or access broad financial data on behalf of users — actions that require regulatory oversight and Strong Customer Authentication (SCA).

If your application uses sensitive scopes, additional approval is required before going to production — **except for Automate your business operations**, which requires no review even for sensitive scopes. [Discover available scopes and workarounds](https://docs.qonto.com/api-reference/business-api/introduction/authentication/scopes.md).

| Scope | Why it is sensitive | Requires review for |
| - | - | - |
| `organization.read` | Grants access to balances, IBANs, transaction history, and organizational data | Connect, Embed |
| `payment.write` | Allows initiating outbound payments to any beneficiary | Connect, Embed |
| `international_transfer.write` | Allows initiating international transfers outside SEPA, subject to the same PSD2 regulatory oversight as domestic payment initiation | Connect, Embed |
| `internal_transfer.write` | Allows moving funds between business accounts | Connect, Embed |
| `beneficiary.trust` | Allows marking SEPA beneficiaries as trusted or removing them from trusted beneficiaries, enabling automated transfers without SCA verification | Embed |

### Obtain Production credentials

Once your application is approved (if required for your use case), follow these steps to go live:

1. Get your Production credentials through the [Developer Portal](https://developers.qonto.com/sign-in/).

   [Qonto Developers - Production access](https://demo.arcade.software/LeIHlx2JIndctoBYV8AQ?embed\&embed_mobile=tab\&embed_desktop=inline\&show_copy_link=true)

2. Replace your Sandbox credentials by your **Production credentials**.

   > [!TIP]
   >
   > The `X-Qonto-Staging-Token` header is not necessary in Production.

3. Replace the endpoints base URL.
   * [Business API URLs](https://docs.qonto.com/api-reference/business-api/introduction/base-urls.md)
   * [Onboarding API URLs](https://docs.qonto.com/api-reference/onboarding-api/introduction/base-urls.md)

> [!TIP]
>
> Your integration is ready to be released in Production!
>
> We would be super grateful if you could take a few minutes to share your feedback regarding our Public APIs: [Tell us what you think](https://qonto.typeform.com/to/d1cVa9Hc)

> [!WARNING]
>
> If you are a licensed partner, you must identify yourself through your QSeal certificate when calling our Business API endpoints in Production (cf. [the requirements](https://docs.qonto.com/guides/authentication/qsealc.md)); otherwise you will receive a `401 Unauthorized` error to your API calls.

## 7. Publish your integration in our Marketplace (optional)

To publish your app in our [Integrations & Partnership section](https://support-fr.qonto.com/hc/en-us/articles/23947671003921-What-is-the-Integrations-and-Partnerships-section), you need to meet the following requirements:

1. Your integration should be used at least by 25 beta testers.
2. Once you meet the first requirement, submit a ticket as "Ask questions" on [Developer Support](https://qonto-developers.zendesk.com/hc/en-001/requests/new):
   * a video of the functionalities of your integration;
   * credentials so we can login into your product and test your integration.
3. Once your integration is approved, you will have to provide us with the information you want to display in the integration page.