Skip to main content
WEBHOOK
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.

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: on_hold (collected, guarding period), completed (amount collected and settled), 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