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

# Collect with Direct Debit

> Set up SEPA Direct Debit to collect recurring payments from customer accounts across Europe.

# Collect Payments Automatically

SEPA Direct Debit lets you pull funds directly from customer accounts - ideal for subscriptions, recurring billing, and scheduled collections. Inventi routes your direct debits through CSM to reach accounts across Europe.

<Info>
  **What happens when you collect a payment:**

  1. You submit a direct debit request via API with a valid mandate
  2. Inventi validates and forwards to CSM
  3. The debtor's bank processes the collection
  4. You receive status updates via webhooks
</Info>

## Supported Schemes

<CardGroup cols={1}>
  <Card title="SDD Core" icon="users">
    Consumer direct debits with extended refund rights (8 weeks unconditional, 13 months for unauthorized)
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Create SDD Payment" icon="file-invoice-dollar" href="/payments/api/sepa-dd/create-payment">
    Initiate a direct debit collection
  </Card>

  <Card title="Cancel SDD Payment" icon="ban" href="/payments/api/sepa-dd/cancel-transactions">
    Recall an accepted collection before settlement
  </Card>

  <Card title="Return SDD Payment" icon="rotate-left" href="/payments/api/sepa-dd/return-transaction">
    Return a settled collection that debited your account
  </Card>

  <Card title="Reverse SDD Payment" icon="arrow-rotate-left" href="/payments/api/sepa-dd/reverse-transaction">
    Reverse after settlement
  </Card>
</CardGroup>

## Business Requirements

<AccordionGroup>
  <Accordion title="Valid mandate is required" icon="file-signature">
    Every direct debit must reference a valid SEPA mandate signed by the debtor. Store mandate details including:

    * Mandate reference (unique identifier)
    * Signing date
    * Debtor name and IBAN
    * Sequence type (FRST, RCUR, OOFF, FNAL)

    <Warning>
      Collections without valid mandates will be rejected or returned by the debtor's bank.
    </Warning>
  </Accordion>

  <Accordion title="Respect collection timing" icon="calendar">
    You choose the settlement date when creating the collection:

    * Settlement date must be at least the next business day (submit by 11:30 EEST for next-day settlement) and at most 14 calendar days ahead

    <Info>
      Submissions past the cutoff for the chosen settlement date are rejected - resubmit with a later settlement date.
    </Info>
  </Accordion>

  <Accordion title="Handle refunds and returns" icon="arrow-rotate-left">
    Debtors can dispute direct debits:

    * **Core scheme**: 8 weeks unconditional refund right, 13 months for unauthorized debits

    <Tip>
      Build automated handling for returns and refunds to update your billing system promptly.
    </Tip>
  </Accordion>

  <Accordion title="Use idempotency for collections" icon="key">
    Always send an `Idempotency-Key` header when creating direct debits. If your request times out, retry with the same key to prevent duplicate collections.

    <Warning>
      Duplicate direct debits can result in customer complaints and chargebacks.
    </Warning>
  </Accordion>
</AccordionGroup>

## Transaction Lifecycle

```mermaid actions={true} theme={null}
stateDiagram-v2
  [*] --> Created: create SDD
  Created --> To_sign: requires approval
  Created --> Sent_to_clear: auto-accepted
  To_sign --> Signed: approve/sign
  Signed --> Sent_to_clear: sent to clearing
  Sent_to_clear --> Accepted: accepted by CSM
  Accepted --> Completed: settled
  Sent_to_clear --> Rejected: rejected
  Accepted --> Rejected: rejected
  Accepted --> Cancelled: recalled
  Created --> Cancelled: cancelled
  To_sign --> Cancelled: cancelled
  Completed --> [*]
  Rejected --> [*]
  Cancelled --> [*]
```

## Transaction Statuses

<Tabs>
  <Tab title="Collection Flow">
    | Status          | Description                       | Timing                                |
    | --------------- | --------------------------------- | ------------------------------------- |
    | `Created`       | Direct debit initiated            | Immediate                             |
    | `To sign`       | Awaiting approval (if configured) | Until signed                          |
    | `Signed`        | Approved, queued for clearing     | Until sent to clearing                |
    | `Sent to clear` | Delivered to CSM for processing   | Same business day as submission       |
    | `Accepted`      | Accepted by the CSM               | From acceptance until settlement date |
    | `Completed`     | Funds collected                   | On settlement date                    |
  </Tab>

  <Tab title="Error States">
    | Status      | Description                                                                                         |
    | ----------- | --------------------------------------------------------------------------------------------------- |
    | `Cancelled` | Cancelled before sending, or recalled while Accepted - possible until 11:30 EEST on settlement day  |
    | `Rejected`  | Rejected by the CSM or the debtor's bank - possible from submission until the settlement-day cutoff |
  </Tab>
</Tabs>

## Create a Direct Debit

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pgw-sandbox.finventi.com/v1/createSepaDDPayment \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: {uuid}" \
    -d '{
      "amount": 4999,
      "currencyIsoCode": "EUR",
      "settlementDate": "2024-01-22",
      "sequenceType": "RCUR",
      "creditor": {
        "id": "LT11ZZZ123456789",
        "iban": "LT543210010000000003",
        "name": "Your Company"
      },
      "debtor": {
        "iban": "DE89370400440532013000",
        "name": "Customer Name"
      },
      "mandateInformation": {
        "id": "MNDT-2024-001",
        "dateOfSignature": "2024-01-15"
      },
      "purpose": {
        "unstructured": "Monthly subscription - January 2024"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "result": {
      "id": 12345,
      "amount": 4999,
      "currencyIsoCode": "EUR",
      "settlementDate": "2024-01-22",
      "sequenceType": "RCUR",
      "endToEndId": "...",
      "creditor": { "..." : "..." },
      "debtor": { "..." : "..." },
      "mandateInformation": { "..." : "..." }
    }
  }
  ```
</CodeGroup>

### Request Fields

<ResponseField name="amount" type="integer" required>
  Amount in minor currency units (cents)
</ResponseField>

<ResponseField name="currencyIsoCode" type="string" required>
  Currency code - must be `EUR`
</ResponseField>

<ResponseField name="settlementDate" type="string" required>
  Collection date (YYYY-MM-DD) - at least the next business day (11:30 EEST cutoff), at most 14 calendar days ahead
</ResponseField>

<ResponseField name="sequenceType" type="string" required>
  `FRST` (first), `RCUR` (recurring), `OOFF` (one-off), `FNAL` (final)
</ResponseField>

<ResponseField name="creditor.id" type="string" required>
  Your SEPA Creditor Identifier (CI) - must match the mandate. See [Create SDD payment](/payments/api/sepa-dd/create-payment) for details
</ResponseField>

<ResponseField name="creditor.iban" type="string">
  Collection account IBAN that receives the funds
</ResponseField>

<ResponseField name="creditor.name" type="string">
  Creditor name (max 70 characters)
</ResponseField>

<ResponseField name="debtor.iban" type="string" required>
  Debtor's IBAN to debit
</ResponseField>

<ResponseField name="debtor.name" type="string" required>
  Debtor's name as on the mandate (max 70 characters)
</ResponseField>

<ResponseField name="debtor.bic" type="string">
  Optional - the debtor's bank is derived from the IBAN
</ResponseField>

<ResponseField name="mandateInformation.id" type="string" required>
  Mandate reference (max 35 characters) - must match the signed mandate
</ResponseField>

<ResponseField name="mandateInformation.dateOfSignature" type="string" required>
  Mandate signing date (YYYY-MM-DD)
</ResponseField>

<ResponseField name="purpose.unstructured" type="string">
  Payment description shown to debtor (max 140 characters)
</ResponseField>

<ResponseField name="ultimateCreditor.name" type="string">
  Name of the party the collection is ultimately for, when you collect on behalf of another party (max 70 characters)
</ResponseField>

<ResponseField name="endToEndId" type="string">
  Your transaction identifier (max 35 characters)
</ResponseField>

## Handle Returns and Reversals

<Tabs>
  <Tab title="Return / Refund (Post-Settlement)">
    Return a settled direct debit that debited your account - operational returns within 5 business days after settlement, customer refunds via MD06 (8 weeks) or MD01 (13 months).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.pgw-sandbox.finventi.com/v1/transactions/{id}:return \
        -H "Authorization: Bearer {token}" \
        -H "Content-Type: application/json" \
        -d '{
          "reason": "AM04",
          "additionalInfo": "Insufficient funds"
        }'
      ```
    </CodeGroup>

    **Common return reasons:**

    | Code   | Description                                                                |
    | ------ | -------------------------------------------------------------------------- |
    | `AM04` | Insufficient funds                                                         |
    | `AC04` | Closed account                                                             |
    | `MD01` | Unauthorized transaction / no valid mandate - refund right up to 13 months |
    | `MS02` | Not specified reason (customer generated)                                  |
  </Tab>

  <Tab title="Reversal (Post-Settlement)">
    Reverse a completed direct debit when funds need to be returned after settlement.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.pgw-sandbox.finventi.com/v1/transactions/sdd/{id}:reverse \
        -H "Authorization: Bearer {token}" \
        -H "Content-Type: application/json" \
        -d '{
          "reason": "Customer dispute",
          "amount": 4999
        }'
      ```
    </CodeGroup>

    <Warning>
      A reversal creates a new linked transaction returning the funds to the debtor - the original collection stays Completed. Ensure sufficient balance in your account.
    </Warning>
  </Tab>
</Tabs>

## Collection Flow

```mermaid actions={true} theme={null}
sequenceDiagram
  autonumber
  participant App as Your System
  participant Platform as Payments Platform
  participant Webhook as Your Webhook
  participant Bank as Debtor's Bank

  App->>Platform: POST /v1/createSepaDDPayment
  Platform-->>App: 200 {id}
  Note over App: Store trx_id

  Platform->>Bank: Submit collection (settles on chosen settlement date)
  Platform-->>Webhook: Status: Created
  Platform-->>Webhook: Status: Accepted

  alt Collection successful
    Bank-->>Platform: Funds collected
    Platform-->>Webhook: Status: Completed
    Webhook->>App: Credit your account
  else Collection failed
    Bank-->>Platform: Reject (pacs.002)
    Platform-->>Webhook: Status: Rejected
    Webhook->>App: Update billing status
  end
```

## Webhook Integration

Each status transition triggers a webhook notification:

<ResponseField name="trx_id" type="string" required>
  Transaction identifier
</ResponseField>

<ResponseField name="direction" type="string" required>
  INBOUND for collections you initiated (direction follows the funds); OUTBOUND when your account is being debited
</ResponseField>

<ResponseField name="status" type="string" required>
  Current transaction status
</ResponseField>

<ResponseField name="amount" type="integer" required>
  Amount in cents
</ResponseField>

## Data Model

Store these fields for complete tracking:

<ResponseField name="trx_id" type="string" required>
  Platform transaction ID (primary key)
</ResponseField>

<ResponseField name="mandate_id" type="string" required>
  Reference to customer mandate
</ResponseField>

<ResponseField name="sequence_type" type="string" required>
  FRST, RCUR, OOFF, or FNAL
</ResponseField>

<ResponseField name="idempotency_key" type="string" required>
  Your generated key for retry safety
</ResponseField>

<ResponseField name="current_status" type="string" required>
  Latest transaction status
</ResponseField>

<ResponseField name="return_reason" type="string">
  Reason code if returned
</ResponseField>

## Integration Checklist

<Steps>
  <Step title="Implement mandate management">
    Store valid mandates with references, dates, and sequence tracking
  </Step>

  <Step title="Use idempotency">
    Generate and persist an `Idempotency-Key` for each collection
  </Step>

  <Step title="Submit with correct timing">
    Choose a settlement date from next business day (11:30 EEST cutoff) up to 14 calendar days ahead
  </Step>

  <Step title="Handle returns and reversals">
    Build automated processing for failed collections and customer disputes
  </Step>

  <Step title="Track sequence types">
    Update sequence type from FRST to RCUR after first successful collection
  </Step>

  <Step title="Implement webhook receiver">
    Process status updates to keep your billing system synchronized
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Send SEPA Payments" icon="paper-plane" href="/payments/outgoing-sepa-payment">
    Send outbound credit transfers
  </Card>

  <Card title="Track and Reconcile" icon="chart-line" href="/payments/integration-guide/payment-information">
    Monitor transactions and reconcile with statements
  </Card>
</CardGroup>