# Automatische Aufladung für Unterkonten (Benutzerdefinierter Zahlungsanbieter)

Wenn Sie es vorziehen, Zahlungen für Unterkonten-Guthaben über Ihren eigenen Anbieter anstelle von Stripe abzuwickeln (Banküberweisungen, lokale Zahlungs-Gateways, benutzerdefinierte Abrechnungssysteme), stellt die Plattform ein Webhook- und API-Paar bereit, damit Sie den gesamten Prozess der Belastung und Gutschrift selbst steuern können. Den nicht-technischen Überblick finden Sie auf der Seite [Agenturkonten](agency-accounts.md#option-2-custom-payment-provider); diese Seite behandelt die genaue Webhook-Payload und den API-Aufruf, den Sie anschließend tätigen, um das Guthaben zu gewähren.

Der Webhook ist nur eine der Möglichkeiten, wie automatische Aufladungen bezahlt werden. Wenn Sie [Stripe](agency-accounts.md#option-1-connect-stripe) oder [PayPal](agency-accounts.md#option-3-connect-paypal) im SaaS-Modus verbunden haben, belastet die Plattform die gespeicherte Karte oder das PayPal-Konto des Kunden selbst und gewährt die Guthaben. Sie müssen also auf dieser Seite nichts einrichten. Lesen Sie nur weiter, wenn Sie die Zahlung selbst abwickeln möchten.

***

## Der Ablauf auf einen Blick

1. Das Guthaben eines Unterkontos fällt unter dessen Schwellenwert für die automatische Aufladung.
2. Die Plattform ruft Ihre **Webhook-URL** mit den Details des Unterkontos und der benötigten Guthabenmenge auf.
3. Ihr Server belastet den Kunden über den von Ihnen genutzten Anbieter.
4. Ihr Server ruft die **Guthaben-Gewährungs-API** auf, um dem Unterkonto Guthaben hinzuzufügen.
5. Ihr Server antwortet mit `200`, um den Webhook zu bestätigen.

***

## 1. Webhook: `agency_sub_account_auto_recharge`

Konfigurieren Sie die Webhook-URL, indem Sie in der Hauptseitenleiste auf **SaaS Mode** klicken, **Use a Custom Payment Provider Instead** auswählen (oder nach der Konfiguration die Karte **Custom Payment Provider** öffnen) und das Feld **Auto-Recharge Webhook** ausfüllen.

### Auslösebedingungen

Wenn das Guthaben eines Unterkontos unter den konfigurierten Schwellenwert für die automatische Aufladung fällt.

### Payload

```json
{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<sub-account-id>",
  "sub_account_email": "customer@example.com",
  "sub_account_name": "John Doe",
  "agency_id": "<agency-id>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}
```

| Feld | Beschreibung |
|---|---|
| `event` | Immer `agency_sub_account_auto_recharge` für diesen Webhook. |
| `sub_account_id` | Die eindeutige ID des Unterkontos, das Guthaben benötigt. |
| `sub_account_email` | Die E-Mail-Adresse des Unterkontos. |
| `sub_account_name` | Der Anzeigename des Unterkontos. |
| `agency_id` | Die eindeutige ID Ihres Agenturkontos. |
| `credits_requested` | Wie viele Credits gewährt werden sollen. Dies ist Ihr konfigurierter Aufladebetrag. Wenn das Guthaben jedoch weiter unter den Schwellenwert gefallen ist, als dieser Betrag abdecken würde, wird er automatisch auf den Betrag erhöht, der erforderlich ist, um das Guthaben in einem Schritt wieder über den Schwellenwert zu heben. Berechnen Sie immer den Wert `credits_requested` aus der Payload (und gewähren Sie diesen) — hartkodieren Sie Ihren Aufladebetrag nicht. |
| `current_balance` | Das Guthaben des Unterkontos zum Zeitpunkt des Webhook-Versands. |
| `threshold` | Der Schwellenwert für das Guthaben, der die Aufladung ausgelöst hat. |
| `price_per_credit_cents` | Ihr konfigurierter Preis pro Credit in Cent. |
| `price_per_credit_currency` | Die Währung für den Preis (z. B. `usd`). |
| `total_amount_cents` | Der Gesamtbetrag, der berechnet werden soll, in Cent (`credits_requested` × `price_per_credit_cents`). |
| `timestamp` | Zeitpunkt des Webhook-Versands (ISO 8601-Format). |
| `idempotency_key` | Ein eindeutiger Schlüssel für diese spezifische Aufladeanfrage. Verwenden Sie diesen, um eine doppelte Gutschrift zu verhindern, falls Ihr Server denselben Webhook mehr als einmal erhält. |

### Wichtige Hinweise

- **5-Minuten-Abklingzeit** — Nach einem Aufladeversuch für ein Unterkonto sendet die Plattform für mindestens 5 Minuten keinen weiteren Webhook für dieses Unterkonto, selbst wenn das Guthaben weiter sinkt. Dies verhindert doppelte Belastungen während der Verarbeitung.
- **Verwenden Sie den Idempotenz-Schlüssel** — Überprüfen Sie immer `idempotency_key`, bevor Sie Guthaben gewähren. Wenn Ihr Server nach der Gewährung des Guthabens, aber vor der Antwort abgestürzt ist, sendet die Plattform den Webhook beim nächsten Unterschreiten des Guthabens möglicherweise erneut.
- **Fehler sind sicher und selbstheilend** — Wenn Ihre Webhook-URL nicht erreichbar ist oder einen Fehler zurückgibt, wird kein Guthaben gewährt. Die Plattform sendet den Webhook weiterhin (einmal pro 5-minütiger Abklingzeit), solange das Unterkonto unter dem Schwellenwert bleibt — es ist **nicht** erforderlich, dass das Guthaben erst wieder über den Schwellenwert steigt und erneut fällt. Eine einzelne verpasste Belastung kann nicht dazu führen, dass ein Unterkonto dauerhaft nicht mehr aufgeladen wird.
- **Legen Sie Ihren Aufladebetrag auf oder über dem Schwellenwert fest** — Ihr konfigurierter Aufladebetrag muss größer oder gleich dem Schwellenwert für die automatische Aufladung sein, damit eine Aufladung das Guthaben immer wieder über den Schwellenwert hebt. (Falls Sie jemals ein Unterkonto korrigieren müssen, das weit unter den Schwellenwert gefallen ist, füllt die Plattform es automatisch um das gesamte Defizit auf — siehe `credits_requested` oben.)

***

## 2. Guthaben-Gewährungs-API

Nachdem Ihr Server die Zahlung verarbeitet hat, rufen Sie diesen Endpunkt auf, um dem Unterkonto das Guthaben hinzuzufügen.

### Anfrage

```http
POST https://api.dmchamp.com/v1/subaccounts/credits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}
```

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `email` | Ja | Die E-Mail-Adresse des Unterkontos (muss mit einem bestehenden Unterkonto unter Ihrer Agentur übereinstimmen). |
| `amount` | Ja | Die Anzahl der zu gewährenden Credits. |
| `description` | Nein | Eine Notiz, die beschreibt, warum Credits hinzugefügt wurden (wird in der Transaktionshistorie des Guthabens angezeigt). |

**Authentifizierung:** Senden Sie Ihren API-Schlüssel in einem Request-Header — entweder `X-API-Key: YOUR_API_KEY` oder `Authorization: Bearer YOUR_API_KEY`. Header sind die empfohlene Methode, da ein Schlüssel in der URL im Browserverlauf, in Proxy-Protokollen und in Serverzugriffsprotokollen landet. Der `?apiKey=YOUR_API_KEY`-Abfrageparameter und ein `apiKey`-Feld im JSON-Body funktionieren ebenfalls weiterhin, sodass ältere Integrationen unverändert weiterlaufen.

### Antwort

```json
{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}
```

::: tip
**Tipp:** Speichern Sie die `idempotency_key` aus dem Webhook-Payload und überprüfen Sie diese, bevor Sie diesen Endpunkt aufrufen. Dies verhindert, dass versehentlich zweimal Guthaben gewährt wird, falls Ihr Server denselben Webhook mehr als einmal empfängt.
:::


### Was passiert mit gewährten Guthaben beim monatlichen Zurücksetzen

Dies hängt davon ab, wie das Unterkonto eingerichtet ist:

- **Wiederverkauf** (das Unterkonto bezahlt Sie für Guthaben): Guthaben, das Sie hier gewähren, wird als gekauftes Guthaben verbucht und **jeden Monat übertragen**. Was das Unterkonto nicht ausgegeben hat, verbleibt auf dem Guthabenstand.
- **Zuteilung** (Sie gewähren dem Unterkonto ein monatliches Kontingent): Der Guthabenstand wird am Zurücksetzungsdatum wieder auf das monatliche Kontingent aufgefüllt, sodass nicht verbrauchtes Guthaben nicht übertragen wird. Dies ist beabsichtigt – das Kontingent wird jeden Monat neu gewährt.

Wenn Sie möchten, dass das Restguthaben eines Unterkontos zusätzlich zum neuen monatlichen Kontingent hinzugefügt wird, anstatt es zu ersetzen, aktivieren Sie die Guthabenübertragung:

```
PUT https://api.dmchamp.com/v1/subaccounts/{subAccountUid}/limits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "usageLimits": { "roll_over_to_next_month": true }
}
```

Wenn für das Unterkonto – oder den Plan, auf dem es sich befindet – auch eine Übertragungsobergrenze oder ein Ablaufdatum festgelegt ist, erfolgt die Zurücksetzung in dem Moment, in dem diese greifen: Das übertragene Guthaben wird auf die von Ihnen zugelassenen Monate gekürzt, und Guthaben, das länger als das Ablaufzeitfenster ungenutzt bleibt, verfällt, bevor das neue Guthaben hinzugefügt wird. Über diesen Endpunkt gewährte Guthaben, automatische Aufladungen und die eigenen Aufladungen des Kunden sind einmalige Guthaben und werden niemals gekürzt. Siehe [Begrenzung der Übertragung](sub-accounts.md#capping-what-rolls-over).

***

## End-to-End-Beispiel

Ein typischer Handler sieht wie folgt aus:

```pseudo
on POST /your-recharge-webhook:
  payload = request.body

  if seen(payload.idempotency_key):
    return 200  // already processed, ack and exit

  charge_result = your_payment_provider.charge(
    email = payload.sub_account_email,
    amount_cents = payload.total_amount_cents,
    currency = payload.price_per_credit_currency,
  )

  if not charge_result.ok:
    return 500  // platform will retry on next balance drop

  api.post("/v1/subaccounts/credits", {
    email = payload.sub_account_email,
    amount = payload.credits_requested,
    description = "Auto-recharge via " + your_provider_name,
  })

  mark_seen(payload.idempotency_key)
  return 200
```