Collect payments with SEPA Direct Debit

SEPA Direct Debit (SDD) lets you collect payments directly from your customers’ bank accounts — no manual action required in the Qonto app. With the SDD Collection API, you can automate your entire receivables workflow: create mandates, trigger one-off or recurring collections, and track outcomes in real time. This is particularly useful if you:

Issue invoices from an external tool (e.g. an ERP or invoicing platform) and want to trigger SDD collections programmatically
Build a direct debit payment method into your own product on top of Qonto

This guide walks you through the available API endpoints and how to integrate them into your business operations.

To use the API, you must be eligible for SEPA Direct Debit and have the feature activated in the Qonto app. Go to Business Account → Incoming Direct Debits to check your eligibility and create your SCI (SEPA Creditor Identifier).

To test the API in the sandbox environment, follow the sandbox setup guide to enable SDD collections for your test organization.

How SDD collection works

1. Authenticate with the right scopes

All SDD endpoints are protected by OAuth 2.0. Request the following scopes depending on the operations you need:

Scope	Access
`sepa_direct_debit.read`	Read mandates, subscriptions, and collections
`sepa_direct_debit.write`	Create and cancel mandates, create subscriptions

You can manage your OAuth credentials from the Developer Portal.

2. Create a mandate

A mandate is the authorization from your customer (the debtor) to collect payments from their bank account. You must have a valid, signed mandate before collecting any payment. To create a mandate, send a POST request to /v2/sepa/direct_debit_mandates. The payment_info object is optional; when provided, it stores first-payment details on the mandate for the signature request and approval communications. It does not create or schedule a collection. Minimal request (mandate only):

{
  "direct_debit_mandate": {
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

You can omit payment_info to create only the mandate. Include it to attach first-payment details to the mandate; it does not create a collection. To collect after the customer signs, create a subscription via POST /v2/sepa/direct_debit_subscriptions referencing the mandate and payment details. Example with payment_info:

{
  "direct_debit_mandate": {
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "payment_info": {
      "first_payment": {
        "collection_date": "2026-01-01",
        "amount": { "value": "250.00", "currency": "EUR" },
        "reference": "INV-2025-001"
      },
      "notify_client": true,
      "schedule_type": "one_off"
    },
    "send_mandate_signature_email": true
  }
}

When the mandate is awaiting signature, the response includes a sign_url — a link your customer must visit to sign the mandate electronically, whether or not payment_info was provided. You can send this URL yourself or have Qonto send the signature request email automatically by setting send_mandate_signature_email: true. The email can be sent for a standalone mandate; it omits the amount and date when payment_info is absent.

{
  "direct_debit_mandate": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "unique_mandate_reference": "UMR-...",
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending_signature",
    "schedule_type": "one_off",
    "notify_client": true,
    "sign_url": "https://...",
    "created_at": "2026-01-01T10:00:00Z"
  }
}

When payment_info was included in the request, the response includes a payment_info object (a snapshot of the details provided at creation). The root schedule_type and notify_client fields are deprecated in favor of payment_info.schedule_type and payment_info.notify_client. payment_info also accepts a recurring schedule, so the signature request shows the frequency to your customer:

{
  "direct_debit_mandate": {
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "payment_info": {
      "first_payment": {
        "collection_date": "2026-11-15",
        "amount": { "value": "49.90", "currency": "EUR" },
        "reference": "SUBSCRIPTION-2026"
      },
      "notify_client": true,
      "schedule_type": "monthly",
      "schedule_total_collection_count": 12
    }
  }
}

When a client IBAN is associated with the mandate, list and retrieve responses also include iban with the last four digits visible (for example, ••••3000). Once your customer signs, you will receive a v1/sepa-direct-debit-mandates webhook with event accepted (see Webhooks below). You can also poll the mandate status with a GET request to /v2/sepa/direct_debit_mandates/{direct_debit_mandate_id}. You can list all mandates for a given client by sending a GET request to /v2/sepa/direct_debit_mandates?client_id={client_id}.

3. Create a subscription

A subscription represents a one-off or recurring payment schedule against a mandate. Once you have a signed mandate, you can trigger a subscription at any time. Send a POST request to /v2/sepa/direct_debit_subscriptions:

{
  "direct_debit_subscription": {
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "direct_debit_mandate_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "bank_account_id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
    "initial_collection_date": "2026-01-01",
    "amount": { "value": "250.00", "currency": "EUR" },
    "reference": "INV-2025-001",
    "notify_client": true,
    "schedule_type": "one_off"
  }
}

Using an existing mandate: provide the direct_debit_mandate_id as shown above. Creating a mandate and collection in one step: omit direct_debit_mandate_id. A new mandate will be created automatically and the response will include a sign_url. Recurring collections: set schedule_type to weekly, monthly, quarterly, yearly, or custom (with schedule_custom_interval and schedule_custom_unit, e.g. every 2 weeks). Use schedule_total_collection_count to limit the number of collections, or omit it for a schedule without end. Qonto then creates each collection automatically.

{
  "direct_debit_subscription": {
    "client_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "bank_account_id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
    "initial_collection_date": "2026-11-15",
    "amount": { "value": "49.90", "currency": "EUR" },
    "reference": "SUBSCRIPTION-2026",
    "notify_client": true,
    "schedule_type": "monthly",
    "schedule_total_collection_count": 12
  }
}

The response includes schedule_next_collection_date and, when the schedule has an end, schedule_end_date. To stop a recurring series, cancel the mandate with POST /v2/sepa/direct_debit_mandates/{id}/cancel. You can retrieve a specific subscription with a GET request to /v2/sepa/direct_debit_subscriptions/{direct_debit_subscription_id}, or list all subscriptions with GET /v2/sepa/direct_debit_subscriptions.

4. Track collection outcomes

Once a subscription has been triggered, Qonto processes it through the SEPA banking network. You can track the outcome in two ways: Webhooks (recommended): subscribe to v1/sepa-direct-debit-collections to receive real-time notifications when a collection status changes (see Webhooks below). Polling: retrieve a collection by ID with a GET request to /v2/sepa/direct_debit_collections/{direct_debit_collection_id}, or list all collections — optionally filtered by subscription — with GET /v2/sepa/direct_debit_collections?direct_debit_subscription_id={id}.

{
  "direct_debit_collection": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "direct_debit_subscription_id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
    "amount": { "value": "250.00", "currency": "EUR" },
    "collection_date": "2026-01-01",
    "status": "completed",
    "unique_mandate_reference": "UMR-..."
  }
}

Mandate statuses

Status	Description
`pending_signature`	The mandate has been created but not yet signed by the customer
`approved`	The mandate has been signed and is ready to use for collections
`canceled`	The mandate has been cancelled.

Collection statuses

Status	Description
`pending`	The collection has been scheduled and is awaiting processing
`completed`	The payment was successfully collected and settled
`declined`	The collection was declined before processing
`rejected`	The collection was rejected during processing
`canceled`	The collection was canceled
`returned`	The payment was reversed by the debtor’s bank (typically up to D+5 after settlement)
`refunded`	The payment was reversed following a request by the debtor (typically up to 8 weeks after settlement)

When a collection fails, the status_reason field provides additional detail (e.g. insufficient_funds, amount_limit_reached, account_closed). The full list of allowed values is documented in the API reference.

Webhooks

Subscribe to webhook topics to receive real-time notifications about key events. The event field in the webhook payload body identifies what happened.

`v1/sepa-direct-debit-mandates`

Event	Description
`accepted`	The mandate has been signed by the customer

Example payload:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "v1/sepa-direct-debit-mandates",
  "created_at": "2026-01-01T10:55:00Z",
  "data": {
    "event": "accepted",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "unique_mandate_reference": "UMR-...",
    "status": "approved",
    "mandate_signature_date": "2026-01-01T10:54:00Z"
  }
}

`v1/sepa-direct-debit-collections`

Event	Description
`completed`	The payment was successfully collected and settled
`failed`	The collection did not succeed. Check `data.status` for the fine-grained reason (`declined`, `rejected`, or `canceled`) and `data.status_reason` for more details
`returned`	The payment was reversed by the debtor’s bank, typically within D+5 of settlement
`refunded`	The payment was reversed at the debtor’s request, typically up to 8 weeks after settlement

Tip: The event field uses a simplified set of outcomes (completed, failed, returned, refunded). For failed events, data.status retains the fine-grained value (declined, rejected, or canceled) so you can handle each case precisely.

Example payload (failed):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "v1/sepa-direct-debit-collections",
  "created_at": "2026-01-01T10:55:00Z",
  "data": {
    "event": "failed",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "direct_debit_subscription_id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
    "amount": { "value": "250.00", "currency": "EUR" },
    "reference": "INV-2025-001",
    "status": "rejected",
    "status_reason": "insufficient_funds"
  }
}

Summary

Here are the steps to follow when integrating SDD collection:

Request the right OAuth scopes: sepa_direct_debit.read and/or sepa_direct_debit.write from the Developer Portal
Create a mandate: POST /v2/sepa/direct_debit_mandates — share or send the sign_url to your customer
Wait for mandate acceptance: subscribe to v1/sepa-direct-debit-mandates webhooks, or poll GET /v2/sepa/direct_debit_mandates/{id}
Create a subscription: POST /v2/sepa/direct_debit_subscriptions with the signed mandate ID, amount, and collection date
Track the outcome: subscribe to v1/sepa-direct-debit-collections webhooks, or poll GET /v2/sepa/direct_debit_collections/{id}

Step	Endpoint
Create a mandate	`POST /v2/sepa/direct_debit_mandates`
Get a mandate	`GET /v2/sepa/direct_debit_mandates/{id}`
List mandates	`GET /v2/sepa/direct_debit_mandates?client_id={id}`
Cancel a mandate	`POST /v2/sepa/direct_debit_mandates/{id}/cancel`
Create a subscription	`POST /v2/sepa/direct_debit_subscriptions`
Get a subscription	`GET /v2/sepa/direct_debit_subscriptions/{id}`
List subscriptions	`GET /v2/sepa/direct_debit_subscriptions`
Get a collection outcome	`GET /v2/sepa/direct_debit_collections/{id}`
List collection outcomes	`GET /v2/sepa/direct_debit_collections`

Business API

Onboarding API

Collect payments with SEPA Direct Debit

How SDD collection works

1. Authenticate with the right scopes

2. Create a mandate

3. Create a subscription

4. Track collection outcomes

Mandate statuses

Collection statuses

Webhooks

`v1/sepa-direct-debit-mandates`

`v1/sepa-direct-debit-collections`

Summary

​How SDD collection works

​1. Authenticate with the right scopes

​2. Create a mandate

​3. Create a subscription

​4. Track collection outcomes

​Mandate statuses

​Collection statuses

​Webhooks

​v1/sepa-direct-debit-mandates

​v1/sepa-direct-debit-collections

​Summary

How SDD collection works

1. Authenticate with the right scopes

2. Create a mandate

3. Create a subscription

4. Track collection outcomes

Mandate statuses

Collection statuses

Webhooks

`v1/sepa-direct-debit-mandates`

`v1/sepa-direct-debit-collections`

Summary