> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Direct debit

How direct debit works as a payment method in Solvimon, what Solvimon stores about a bank account, and where mandates live.

---

## Why this matters

Direct debit is the default collection method for recurring B2B and B2C billing in much of Europe: it costs less than cards, it does not expire, and it fails less often. It also carries a legal requirement that cards do not, the mandate, which is the customer's authorisation for you to pull funds from their account. Knowing which system owns the mandate determines who is responsible when a debit is disputed.

## How it works

A direct debit collection has three parts:

1. **The mandate.** The customer's signed authorisation, under a scheme such as SEPA Direct Debit (Core or B2B), Bacs Direct Debit, ACH, or Autogiro. Mandates are captured, stored, and referenced on collection by your **payment service provider**, not by Solvimon.
2. **The payment method.** A record on the Solvimon customer that identifies the bank account the mandate covers, and links to the provider integration that holds the mandate.
3. **The collection.** Solvimon raises a payment against the invoice using that payment method, and the provider debits the account under the mandate.

> **Warning**
>
> Solvimon does not model mandates. There is no mandate reference, signature date, scheme, or mandate status in the Solvimon API. Mandate capture, storage, scheme rules, notice periods, and the audit trail for a disputed debit are all the responsibility of the connected provider (Adyen or Stripe). Solvimon holds only the payment method that the provider's mandate relates to.

## The payment method record

A direct debit payment method has `type` set to `DIRECT_DEBIT`, alongside the other supported types: `CARD`, `DIRECT_DEBIT`, `ONLINE_BANKING`, `BUY_NOW_PAY_LATER`, `DIGITAL_WALLET`, and `UNKNOWN`.

For direct debit, Solvimon stores:

| Field             | Description                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `variant`         | The scheme or provider variant the method was created under, for example the provider's SEPA or Autogiro variant |
| `owner_name`      | The account holder's name, as it appears on the mandate                                                          |
| `iban`            | The account number                                                                                               |
| `bic`             | The bank identifier                                                                                              |
| `country`         | The account's country, ISO 3166                                                                                  |
| `billing_address` | The address used for the payment method                                                                          |
| `is_default`      | Whether this is the customer's default method                                                                    |
| `integration_id`  | The provider integration that holds the mandate and performs the debit                                           |

Statuses follow a short lifecycle:

| Status     | Meaning                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| `SETUP`    | Created, but not yet usable for collection. The provider is still completing setup, including the mandate |
| `ACTIVE`   | Usable for collection                                                                                     |
| `INACTIVE` | Retained but not usable, for example after the mandate was revoked at the provider                        |
| `ARCHIVED` | No longer in use                                                                                          |

> **Note**
>
> A method sitting in `SETUP` is the usual cause of a first collection failing on a new customer. Check the status before the first billing run rather than after it.

## Setting one up

### Via API

Which schemes are available depends on the connected provider and the billing entity's country. Ask for the options before creating a method, so the `variant` you send is one the provider accepts:

**`Get available direct debit options`**

```bash Get available direct debit options
curl -X POST https://test.api.solvimon.com/v1/payment-acceptors/payment-method-options \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_acceptor_id": "paya_example",
    "payment_method_type": "DIRECT_DEBIT"
  }'
```

**`Response`**

```json Response
[
  {
    "payment_acceptor": {
      "id": "paya_example",
      "type": "PAYMENT_GATEWAY"
    },
    "integration": {
      "id": "intg_example",
      "provider": "ADYEN"
    },
    "options": [
      {
        "payment_method_variant": "sepaDirectDebit",
        "payment_gateway_variant": "sepadirectdebit"
      }
    ]
  }
]
```

Each option pairs a `payment_method_variant` with a `payment_gateway_variant`, plus the provider-specific configuration for Adyen or Stripe.

Do not collect and post bank details yourself. Tokenize them through the provider so the mandate is created and the account details are held by the provider:

**`Tokenize a direct debit payment method`**

```bash Tokenize a direct debit payment method
curl -X POST https://test.api.solvimon.com/v1/payment-methods/tokenize \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_example",
    "payment_acceptor_id": "paya_example",
    "payment_method_type": "DIRECT_DEBIT",
    "payment_method_variant": "sepaDirectDebit",
    "payment_gateway_variant": "sepadirectdebit"
  }'
```

**`Response`**

```json Response
{
  "object_type": "PAYMENT_METHOD",
  "id": "paym_example",
  "customer_id": "cust_example",
  "type": "DIRECT_DEBIT",
  "status": "SETUP",
  "is_default": false,
  "direct_debit": {
    "variant": "sepaDirectDebit",
    "owner_name": null,
    "iban": null,
    "bic": null,
    "country": null
  },
  "integration_id": "intg_example"
}
```

Read the customer's methods back with `GET /v{version}/payment-methods`, and use `POST /v{version}/payment-methods/refresh` to pull the current state from the provider after a mandate change.

### Via hosted pages

The lower-effort route is to let the customer set the mandate up themselves. Both [hosted checkout](/platform-guides/customers-and-billing/checkout) and the [customer portal](/platform-guides/customers-and-billing/customer-portal) render the provider's payment method form, so the mandate is captured by the provider and the resulting payment method appears on the Solvimon customer with no integration work.

### Via Desk

Add or inspect a customer's payment methods on the customer record. The available direct debit variants come from the payment acceptor configured on the billing entity, so configure the [payment acceptor](/platform-guides/platform-configuration/payment-options) first.

## Collection and failures

Direct debit failures arrive later than card failures: a debit can be returned days after it is presented. That return surfaces as a payment result of `REFUSED` or, where funds were taken and reversed, `CHARGED_BACK`, with the provider's reason in `result_details`.

Because the timing differs from cards, do not assume an unpaid invoice means the debit was never presented. See [Dunning & payment retries](/platform-guides/invoicing/dunning-and-payment-retries) for how attempts are recorded and chased.

## Edge cases

* **Scheme-specific rules are the provider's.** Advance notice requirements, B2B versus Core mandate handling, and return windows differ per scheme and are enforced at the provider.
* **A revoked mandate** is not visible in Solvimon until the payment method is refreshed or a collection fails.
* **Changing bank accounts** means a new mandate and a new payment method. Set the new method as default and archive the old one; do not edit the account details in place.

---