# `BankingCircle.DirectDebit`
[🔗](https://github.com/iamkanishka/banking_circle/blob/main/lib/banking_circle/direct_debit.ex#L1)

Direct Debit Collections: initiating a collection against a
pre-authorized mandate you (the creditor) hold on the debtor's account.

Banking Circle does **not** manage mandate creation, signing, or
storage — mandate lifecycle is entirely your responsibility per the
applicable scheme rulebook (see the moduledoc's "Mandate Data
Requirements" below). You reference your stored mandate by id when
initiating a collection here.

## Mandate data you must hold before collecting

Per Banking Circle's documented requirements, a valid mandate record
needs: creditor (your) name and address, your Creditor Identifier (CID),
a unique mandate reference, the customer's name and IBAN, payment type
(one-off/recurring), and captured customer consent (checkbox, email
confirmation, or digital signature) — none of which this library stores
or manages for you.

## Idempotency

This is, at time of writing, the **one** payment-initiation endpoint
Banking Circle documents idempotency-key support for. `initiate/2`
always attaches one (generated, unless you supply `:idempotency_key`) —
see `BankingCircle.HTTP.Middleware.Idempotency`. A replayed key returns
a 400 identifying the original acceptance, which
`BankingCircle.Error.parse/2` surfaces like any other error
(`kind: :client_error`, with the original timestamp/entity id in the
message) — this is what makes it safe for `initiate/2` to be one of the
few POSTs this library is comfortable letting you retry blindly.

## Reconciling collections

Match a collection to its resulting incoming payment via the
`end_to_end_id` you supplied here (shows up in
**Remittance Information Line 1** on the incoming credit entry), or via
Banking Circle's own reference (**Account Servicer Reference** in the
Customer Payment Status Report, **Reference Number** in reconciliation
reports). See `BankingCircle.Reporting` and the `IncomingPaymentBooked` /
`IncomingPaymentProcessed` webhook events.

# `client`

```elixir
@type client() :: atom()
```

# `initiate`

```elixir
@spec initiate(map(), client()) ::
  {:ok, map()} | {:error, BankingCircle.Error.t() | {:missing_field, atom()}}
```

Initiates a Direct Debit collection against a stored mandate.

Required: `:creditor_account_id`, `:mandate_id` (your stored mandate's
identifier — becomes `mandateRelatedInformation.mandateId`),
`:debtor_iban`, `:amount`, `:currency`, `:end_to_end_id` (your
reconciliation reference — see the moduledoc).

Optional: `:requested_execution_date`, `:remittance_information`,
`:idempotency_key` (generated for you otherwise).

---

*Consult [api-reference.md](api-reference.md) for complete listing*