Skip to main content
WEBHOOK
v1
/
sepa-direct-debit-collections
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "membership_id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "v1/sepa-direct-debit-collections",
    "created_at": "2025-01-24T10:55:00Z",
    "data": {
        "event": "completed",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "direct_debit_subscription_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "amount": { "value": "102.34", "currency": "EUR" },
        "reference": "ref-123",
        "status": "completed",
        "collection_date": "2026-01-01"
    }
}
This topic delivers events related to SEPA Direct Debit collections. Events:
  • completed — The collection amount was successfully collected and settled.
  • failed — The collection did not succeed. For internal statuses declined, rejected, or canceled, the webhook sets data.event to "failed" so subscribers see a single event type; data.status remains fine-grained (e.g. rejected). data.status_reason indicates why (e.g. insufficient_funds, amount_limit_reached, no_mandate).
  • returned — The collection had been credited but was reversed by the debtor’s bank (R-transaction). Typically from settlement up to D+5. Bank-triggered.
  • refunded — The collection had been credited but was reversed following a request by the client (debtor). Typically from settlement up to 8 weeks. Client-triggered.
Return vs refund: Return = bank-triggered, D+5. Refund = client-triggered, up to 8 weeks. data.direct_debit_subscription_id is included so you can correlate the collection with an SDD subscription. Allowed values for status_reason are documented in the API reference. 
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "subscription_id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "membership_id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "v1/sepa-direct-debit-collections",
    "created_at": "2025-01-24T10:55:00Z",
    "data": {
        "event": "completed",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "direct_debit_subscription_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "amount": { "value": "102.34", "currency": "EUR" },
        "reference": "ref-123",
        "status": "completed",
        "collection_date": "2026-01-01"
    }
}

Authorizations

​
X-Qonto-Signature
string
header
required

The signature header follows the format t={timestamp},v1={signature}.

Verification steps:

  1. Extract the timestamp and signature from the signature header
  2. Reject the request if the timestamp is older than 5 minutes
  3. Recreate the signed payload: '{timestamp}.{raw_request_body}'
  4. Compute HMAC-SHA256 of the signed payload using your webhook secret as the key
  5. Compare the computed signature with the one in the header

Body

application/json

Webhook payload for topic v1/sepa-direct-debit-collections. Events: completed (amount collected), failed (declined/rejected/canceled — data.event is "failed", data.status stays fine-grained), returned (bank-triggered reversal, settlement to D+5), refunded (client-triggered reversal, settlement up to 8 weeks).

​
id
string<uuid>
required
​
subscription_id
string<uuid>
required
​
organization_id
string<uuid>
required
​
membership_id
string<uuid>
required
​
type
enum<string>
required
Available options:
v1/sepa-direct-debit-collections
​
created_at
string<date-time>
required
​
data
object
required

Response

200

Webhook received successfully