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 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 and creating an app, you’ll be able to get all the authentication credentials you need to access the Sandbox environment (cf. demo below).

   Are you interested in seeing how Qonto Embed could supercharge your platform with embedded financial services? Check out our sample app.

   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 if you need to perform sensitive actions (cf. the endpoints access table 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 otherwise.

   The API key authentication method is much more simple to implement than OAuth 2.0.

   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.

   This use case requires validation from Qonto if you are requesting sensitive 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).

   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.

   Requires signing an ORIAS mandate (France only) and a partnership contract with Qonto before going live.

   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.

   In the following steps, if any verification screen is prompted, please fill 123456.

   Log in to the Sandbox web app

   1. From the Toolkit, click on “Sandbox web app”.

      Please, do not click on “Open an account”.

   2. Log in with the credentials available in the Developer Portal.

      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.

   You have access to Qonto Sandbox web app!

   Create my own user (optional)

   Do I need to create my own user?

   The user associated to [e-mail] 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, click on “Sandbox web app”.
   2. Log in with the credentials available in the Developer Portal.
   3. For any organization, click on the “User management” tab.
   4. Click on the “Invite team member” button.
   5. Create a new user.
   6. If the verification screen is prompted, fill 123456.
   7. From the 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.

   Your new user is activated!

   N.B. : You don’t need to verify your identity.

   Create my own organization (optional)

   Do I need my own organization?

   The organizations associated to [e-mail] 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, click on “QA tool”.

   3. Click on “Create Organization”.

   4. Fill the following fields:

      

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

      

   From the Toolkit, click on “Sandbox web app”. Your new organization is created!

4. Make your first API call

   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;
   • Onboarding API Collection.

   2. Fork our Postman environments in your workspace:

   • Sandbox environment;
   • Production environment.

   2. On your workspace, select an environment before making any API call.

      

   Your Postman workspace is set up!

   Authenticate

   You’ll find all the authentication credentials you need in the Developer Portal.

   Don’t forget to include the X-Qonto-Staging-Token header in your API calls to the Sandbox environment.

   Business API

   If you need to authenticate through:

   • OAuth 2.0 (customers using sensitive endpoints and partners) 👉 follow those steps;
   • your API Key (customers only) 👉 follow those steps.

   Onboarding API

   Follow those steps.

5. Build your integration

   Not a developer? Use Make or Zapier (no-code tools) to build your integration!

   Not sure how to start building?

   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.

   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.

   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.

   2. Replace your Sandbox credentials by your Production credentials.

      The X-Qonto-Staging-Token header is not necessary in Production.

   3. Replace the endpoints base URL.

      • Business API URLs
      • Onboarding API URLs

   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

   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); 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, 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, send us at [e-mail]:
      • 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.