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

# Overview

> Integrate your own mandate signing service to handle SEPA Direct Debit mandate collection.

Use this extension when you need full control over the SEPA mandate signing process — particularly for **SEPA B2B Direct Debit**, which requires stricter verification than CORE.

If you provide a signing service, Hellgate Commerce will delegate mandate creation and status tracking to it.

<Info>
  This extension is not enabled by default.

  Contact Hellgate Support to enable it for your account.
</Info>

## How it works

Hellgate Commerce initiates a mandate signing request and then waits for your service to report the outcome via a callback URL.

```mermaid theme={null}
sequenceDiagram
    participant HC as Hellgate Commerce
    participant SVC as Your SEPA Service
    participant Customer as Customer

    HC->>SVC: POST /sepa-mandates
    Note over HC,SVC: Debtor IBAN/BIC, debit method,<br/>sequence type, signees, return_url
    SVC-->>HC: 201 { id }

    SVC-)Customer: Signing request (email / portal)
    Customer--)SVC: Signs mandate

    SVC->>HC: POST return_url — CREATE
    Note over SVC,HC: Signed mandate PDF, reference, signed_on
    HC-->>SVC: 202 Accepted

    Note over HC,SVC: Lifecycle events (expiry, withdrawal…)
    SVC->>HC: POST return_url — CHANGE_STATUS / TERMINATE / FAIL
    HC-->>SVC: 202 Accepted
```

## Callback actions

Your service posts status updates to the `return_url` provided at mandate creation. Each callback carries an `action` field:

| Action          | When                               | Key payload fields                                              |
| --------------- | ---------------------------------- | --------------------------------------------------------------- |
| `CREATE`        | Mandate fully signed               | `mandate_pdf` (base64 PDF), `reference`, `signed_on`            |
| `CHANGE_STATUS` | Lifecycle state change             | `target_state`: `ACTIVE`, `EXPIRED`, `INACTIVE`, or `WITHDRAWN` |
| `FAIL`          | Signing process failed             | Optional `failure_details`                                      |
| `TERMINATE`     | Mandate terminated by your service | Optional `failure_details`                                      |

Respond with `202 Accepted` for each callback. Any other status is treated as a delivery failure.